pyBIA.cnn_model =============== .. py:module:: pyBIA.cnn_model .. autoapi-nested-parse:: Created on Thu Sep 16 22:40:39 2021 @author: daniel Classes ------- .. autoapisummary:: pyBIA.cnn_model.Classifier Functions --------- .. autoapisummary:: pyBIA.cnn_model.custom_model pyBIA.cnn_model.AlexNet pyBIA.cnn_model.VGG16 pyBIA.cnn_model.Resnet18 pyBIA.cnn_model.resnet_block pyBIA.cnn_model.f1_score pyBIA.cnn_model.calculate_tp_fp pyBIA.cnn_model.focal_loss pyBIA.cnn_model.dice_loss pyBIA.cnn_model.jaccard_loss pyBIA.cnn_model.weighted_binary_crossentropy pyBIA.cnn_model.get_optimizer pyBIA.cnn_model.get_loss_function pyBIA.cnn_model.print_params pyBIA.cnn_model.format_labels Module Contents --------------- .. py:class:: Classifier(positive_class=None, negative_class=None, val_positive=None, val_negative=None, img_num_channels=1, clf='alexnet', normalize=False, min_pixel=0, max_pixel=100, epochs=25, patience=5, metric='loss', opt_cv=None, augment_data=False, batch_positive=10, batch_negative=1, balance=True, image_size=70, shift=10, rotation=False, horizontal=False, vertical=False, mask_size=None, num_masks=None, blend_positive=0, blending_func='mean', num_images_to_blend=2, blend_negative=0, zoom_range=(0.9, 1.1), skew_angle=0, batch_size=32, optimizer='sgd', lr=0.0001, momentum=0.9, decay=0.0, nesterov=False, rho=0.9, beta_1=0.9, beta_2=0.999, amsgrad=False, conv_init='uniform_scaling', dense_init='truncated_normal', activation_conv='relu', activation_dense='relu', conv_reg=0, dense_reg=0, padding='same', model_reg='batch_norm', verbose=2, path=None, use_gpu=False) Creates and trains a convolutional neural network for binary classification, with optional normalization, augmentation, simple cross-validation, and convenience utilities for saving, loading, and visualization. :param positive_class: Training images for the positive class. Accepts (N, H, W) or (N, H, W, C) arrays where N is the number of samples, H×W are spatial dimensions, and C is the number of channels. Default is None. :type positive_class: ndarray or None, optional :param negative_class: Training images for the negative class. Accepts (N, H, W) or (N, H, W, C) arrays with the same conventions as `positive_class`. Default is None. :type negative_class: ndarray or None, optional :param val_positive: Optional validation images for the positive class using the same shape rules as training data. Default is None. :type val_positive: ndarray or None, optional :param val_negative: Optional validation images for the negative class using the same shape rules as training data. Default is None. :type val_negative: ndarray or None, optional :param img_num_channels: Number of channels per image (last dimension). Inferred from 4-D inputs when possible; may be set explicitly for legacy compatibility. Default is 1. :type img_num_channels: int, optional :param clf: Backbone architecture to build and train. Default is 'alexnet'. :type clf: {'alexnet','vgg16','resnet18','custom_cnn'}, optional :param normalize: If True, min–max normalize each image/channel using `min_pixel` and `max_pixel` before training or prediction. Default is False. :type normalize: bool, optional :param min_pixel: Lower clamp applied during min–max normalization (used only if `normalize=True`). Default is 0. :type min_pixel: float, optional :param max_pixel: Upper clamp applied during min–max normalization (used only if `normalize=True`). If multi-channel, a list may specify per-channel maxima. Default is 100. :type max_pixel: float or list, optional :param epochs: Number of training epochs. If set to 0, the model is constructed but not trained. Default is 25. :type epochs: int, optional :param patience: Early-stopping patience (epochs) for the monitored `metric`. Default is 5. :type patience: int, optional :param metric: Metric used for monitoring/selection during training/early stopping. Default is 'loss'. :type metric: {'loss','binary_accuracy','f1_score','all','val_loss','val_binary_accuracy','val_f1_score'}, optional :param opt_cv: If set to an integer K, perform simple K-fold-like training by rotating validation blocks (requires `val_positive`/`val_negative`). Default is None. :type opt_cv: int or None, optional :param augment_data: If True, apply the configured augmentation pipeline to the training data (positive class, and optionally negative). Default is False. :type augment_data: bool, optional :param batch_positive: Augmentation multiplier applied to the positive class (outputs per input). Default is 10. :type batch_positive: int, optional :param batch_negative: Augmentation multiplier applied to the negative class (0 disables negative augmentation). Default is 1. :type batch_negative: int, optional :param balance: After augmentation/resizing, trim the larger class to match the smaller. Default is True. :type balance: bool, optional :param image_size: Target square side length used by augmentation/resize utilities. Default is 70. :type image_size: int, optional :param shift: Maximum absolute pixel shift applied horizontally and vertically during augmentation. Default is 10. :type shift: int, optional :param rotation: If True, allow random rotations in the full 0–360° range. Default is False. :type rotation: bool, optional :param horizontal: If True, allow random horizontal flips in augmentation. Default is False. :type horizontal: bool, optional :param vertical: If True, allow random vertical flips in augmentation. Default is False. :type vertical: bool, optional :param mask_size: Side length of random square cutouts applied during augmentation; if a tuple (low, high) is given, sizes are sampled uniformly from the range. Default is None. :type mask_size: int or tuple or None, optional :param num_masks: Number of cutouts per image when `mask_size` is set; if a tuple (low, high) is given, counts are sampled uniformly from the range. Default is None. :type num_masks: int or tuple or None, optional :param blend_positive: Blended-image synthesis factor for the positive class (≥1 adds synthetic samples, 0 disables blending). Default is 0. :type blend_positive: float, optional :param blending_func: Operator used when blending multiple images to synthesize samples. Default is 'mean'. :type blending_func: {'mean','max','min','random'}, optional :param num_images_to_blend: Number of images combined per synthetic blend operation. Default is 2. :type num_images_to_blend: int, optional :param blend_negative: Blended-image synthesis factor for the negative class (≥1 adds synthetic samples, 0 disables blending). Default is 0. :type blend_negative: float, optional :param zoom_range: Random zoom range specified as (min_zoom, max_zoom). Default is (0.9, 1.1). :type zoom_range: tuple of (float, float) or None, optional :param skew_angle: Maximum absolute skew angle in degrees; the actual angle is sampled uniformly from [−skew_angle, +skew_angle]. Default is 0. :type skew_angle: float, optional :param batch_size: Mini-batch size used during training. Default is 32. :type batch_size: int, optional :param optimizer: Optimizer name forwarded to the model builders. Default is 'sgd'. :type optimizer: {'sgd','adam','rmsprop','adadelta',...}, optional :param lr: Optimizer learning rate. Default is 0.0001. :type lr: float, optional :param momentum: Momentum parameter used by SGD-like optimizers. Default is 0.9. :type momentum: float, optional :param decay: Per-epoch learning-rate decay. Default is 0.0. :type decay: float, optional :param nesterov: If True, use Nesterov momentum with SGD. Default is False. :type nesterov: bool, optional :param rho: Rho parameter for Adadelta/RMSprop optimizers. Default is 0.9. :type rho: float, optional :param beta_1: Beta1 parameter for Adam-type optimizers. Default is 0.9. :type beta_1: float, optional :param beta_2: Beta2 parameter for Adam-type optimizers. Default is 0.999. :type beta_2: float, optional :param amsgrad: If True, use the AMSGrad variant of Adam. Default is False. :type amsgrad: bool, optional :param conv_init: Kernel initializer for convolutional layers. Default is 'uniform_scaling'. :type conv_init: str, optional :param dense_init: Kernel initializer for dense layers. Default is 'truncated_normal'. :type dense_init: str, optional :param activation_conv: Activation function used in convolutional layers. Default is 'relu'. :type activation_conv: str, optional :param activation_dense: Activation function used in dense layers. Default is 'relu'. :type activation_dense: str, optional :param conv_reg: L2 regularization strength applied to convolutional layers. Default is 0. :type conv_reg: float, optional :param dense_reg: L2 regularization strength applied to dense layers. Default is 0. :type dense_reg: float, optional :param padding: Convolution padding mode used throughout the network. Default is 'same'. :type padding: {'same','valid'}, optional :param model_reg: Model-level regularization utility applied to the network. Default is 'batch_norm'. :type model_reg: {'batch_norm', None, ...}, optional :param verbose: Keras verbosity level (0 = silent, 1 = progress bar, 2 = per-epoch line). Default is 2. :type verbose: {0,1,2}, optional :param path: Base directory for saving/loading artifacts; the home directory is used when None. Default is None. :type path: str or None, optional :param use_gpu: If False, disable GPU via the environment variable `CUDA_VISIBLE_DEVICES='-1'`. Default is False. :type use_gpu: bool, optional .. attribute:: model Trained model (or list of models if `opt_cv` is used). :type: keras.Model or list[keras.Model] or None .. attribute:: history Keras history object(s) from training. :type: keras.callbacks.History or list[History] or None .. attribute:: model_train_metrics Stacked training metrics per epoch: columns [binary_accuracy, loss, f1_score]. If CV, a list per fold. :type: ndarray or list[ndarray] .. attribute:: model_val_metrics Same as above but for validation, if validation data was provided. :type: ndarray or list[ndarray] .. attribute:: path Folder where artifacts are saved/loaded (set by `save()`/`load()`). :type: str or None .. py:attribute:: positive_class :value: None .. py:attribute:: negative_class :value: None .. py:attribute:: val_positive :value: None .. py:attribute:: val_negative :value: None .. py:attribute:: img_num_channels :value: 1 .. py:attribute:: clf :value: 'alexnet' .. py:attribute:: normalize :value: False .. py:attribute:: min_pixel :value: 0 .. py:attribute:: max_pixel :value: 100 .. py:attribute:: epochs :value: 25 .. py:attribute:: patience :value: 5 .. py:attribute:: metric :value: 'loss' .. py:attribute:: opt_cv :value: None .. py:attribute:: augment_data :value: False .. py:attribute:: batch_positive :value: 10 .. py:attribute:: batch_negative :value: 1 .. py:attribute:: balance :value: True .. py:attribute:: image_size :value: 70 .. py:attribute:: shift :value: 10 .. py:attribute:: rotation :value: False .. py:attribute:: horizontal :value: False .. py:attribute:: vertical :value: False .. py:attribute:: mask_size :value: None .. py:attribute:: num_masks :value: None .. py:attribute:: blending_func :value: 'mean' .. py:attribute:: num_images_to_blend :value: 2 .. py:attribute:: blend_negative :value: 0 .. py:attribute:: zoom_range :value: (0.9, 1.1) .. py:attribute:: skew_angle :value: 0 .. py:attribute:: blend_positive :value: 0 .. py:attribute:: batch_size :value: 32 .. py:attribute:: optimizer :value: 'sgd' .. py:attribute:: lr :value: 0.0001 .. py:attribute:: momentum :value: 0.9 .. py:attribute:: decay :value: 0.0 .. py:attribute:: nesterov :value: False .. py:attribute:: rho :value: 0.9 .. py:attribute:: beta_1 :value: 0.9 .. py:attribute:: beta_2 :value: 0.999 .. py:attribute:: amsgrad :value: False .. py:attribute:: conv_init :value: 'uniform_scaling' .. py:attribute:: dense_init :value: 'truncated_normal' .. py:attribute:: activation_conv :value: 'relu' .. py:attribute:: activation_dense :value: 'relu' .. py:attribute:: conv_reg :value: 0 .. py:attribute:: dense_reg :value: 0 .. py:attribute:: padding :value: 'same' .. py:attribute:: model_reg :value: 'batch_norm' .. py:attribute:: verbose :value: 2 .. py:attribute:: path :value: None .. py:attribute:: use_gpu :value: False .. py:attribute:: model :value: None .. py:attribute:: history :value: None .. py:method:: create(overwrite_training=False, save_training=False) Build and train the configured CNN (optionally with augmentation and CV). Models and histories are stored on the instance (`self.model`, `self.history`). If `epochs == 0`, the network is constructed but not trained. :param overwrite_training: If True, replace `positive_class`/`negative_class` (and validation sets, if any) with the processed arrays actually used for training (after normalization, resizing, and augmentation). Default is False. :type overwrite_training: bool, optional :param save_training: If True, persist the processed training/validation arrays alongside the model artifacts (location determined by `path`). Default is False. :type save_training: bool, optional :rtype: None .. py:method:: save(dirname=None, overwrite=False) Save the trained model(s), metrics, and class attributes to disk. Creates a folder named 'pyBIA_cnn_model' under the base directory (`path` or home directory). If multiple CV models exist, each is saved separately. :param dirname: Optional subdirectory created beneath the base path before saving (e.g., to group experiments). If the subdirectory already exists, an error is raised unless handled by the caller. Default is None. :type dirname: str or None, optional :param overwrite: If True, delete any existing 'pyBIA_cnn_model' folder at the target location and recreate it to avoid duplicates. Default is False. :type overwrite: bool, optional :rtype: None :raises ValueError: If the destination folder already exists and `overwrite` is False. .. py:method:: load(path=None, load_training_data=False) Load a saved model (or CV models), metrics, and class attributes from disk. Looks for a 'pyBIA_cnn_model' folder under `path` (or the home directory if `path` is None). Optionally restores the saved training/validation arrays. :param path: Base directory that contains the 'pyBIA_cnn_model' folder to load from. If None, the home directory is used. Default is None. :type path: str or None, optional :param load_training_data: If True, also load the saved `positive_class`, `negative_class`, and optional validation arrays (when present). Default is False. :type load_training_data: bool, optional :rtype: None .. py:method:: predict(data, target='LAB', return_proba=False, cv_model=0) Predict class labels for new images using the trained CNN. Images are preprocessed using the current normalization settings and resized to the model’s required input size when necessary. :param data: Input images as (N, H, W) for single-channel or (N, H, W, C) for multi-channel. A single image may be passed as (H, W) or (H, W, C) and will be promoted. :type data: ndarray :param target: String label used for the positive class when returning class names. Default is 'LAB'. :type target: str, optional :param return_proba: If True, also return predicted probabilities for the positive class. Default is False. :type return_proba: bool, optional :param cv_model: Index of the CV model to use when multiple models were trained, or 'all' to average probabilities across all models. Default is 0. :type cv_model: int or {'all'}, optional :returns: If `return_proba` is False, an array of predicted class strings with shape (N,). If `return_proba` is True, an array of shape (N, 2) with columns [predicted_label, probability_for_target]. :rtype: ndarray :raises ValueError: If no trained model is available or if inputs are incompatible with the model. .. py:method:: augment_positive(batch=1, width_shift=0, height_shift=0, horizontal=False, vertical=False, rotation=False, fill='nearest', image_size=None, zoom_range=None, mask_size=None, num_masks=None, blend_multiplier=0, blending_func='mean', num_images_to_blend=2, skew_angle=0) Apply the configured augmentation pipeline to the positive class and replace it. :param batch: Number of augmented outputs to create per input image. Default is 1. :type batch: int, optional :param width_shift: Maximum horizontal pixel shift applied uniformly at random. Default is 0. :type width_shift: int, optional :param height_shift: Maximum vertical pixel shift applied uniformly at random. Default is 0. :type height_shift: int, optional :param horizontal: If True, allow random horizontal flips. Default is False. :type horizontal: bool, optional :param vertical: If True, allow random vertical flips. Default is False. :type vertical: bool, optional :param rotation: If True, allow random rotations in the full 0–360° range. Default is False. :type rotation: bool, optional :param fill: Fill mode for pixels introduced by rotations/shifts. Default is 'nearest'. :type fill: {'constant','nearest','reflect','wrap'}, optional :param image_size: Target square size after augmentation; if None, keep original size. Default is None. :type image_size: int or None, optional :param zoom_range: Random zoom range given as (min_zoom, max_zoom). Default is None. :type zoom_range: tuple of (float, float) or None, optional :param mask_size: Side length of each random square cutout; if None, disable cutouts. Default is None. :type mask_size: int or None, optional :param num_masks: Number of cutouts applied per image when `mask_size` is set. Default is None. :type num_masks: int or None, optional :param blend_multiplier: Synthetic blending factor (≥1 adds blended samples, 0 disables blending). Default is 0. :type blend_multiplier: float, optional :param blending_func: Operator used when blending multiple images. Default is 'mean'. :type blending_func: {'mean','max','min','random'}, optional :param num_images_to_blend: Number of images combined per synthetic blend operation. Default is 2. :type num_images_to_blend: int, optional :param skew_angle: Maximum absolute skew angle in degrees; sampled uniformly from [−skew_angle, +skew_angle]. Default is 0. :type skew_angle: float, optional :rtype: None .. py:method:: augment_negative(batch=1, width_shift=0, height_shift=0, horizontal=False, vertical=False, rotation=False, fill='nearest', image_size=None, zoom_range=None, mask_size=None, num_masks=None, blend_multiplier=0, blending_func='mean', num_images_to_blend=2, skew_angle=0) Apply the configured augmentation pipeline to the negative class and replace it. :param batch: Number of augmented outputs to create per input image. Default is 1. :type batch: int, optional :param width_shift: Maximum horizontal pixel shift applied uniformly at random. Default is 0. :type width_shift: int, optional :param height_shift: Maximum vertical pixel shift applied uniformly at random. Default is 0. :type height_shift: int, optional :param horizontal: If True, allow random horizontal flips. Default is False. :type horizontal: bool, optional :param vertical: If True, allow random vertical flips. Default is False. :type vertical: bool, optional :param rotation: If True, allow random rotations in the full 0–360° range. Default is False. :type rotation: bool, optional :param fill: Fill mode for pixels introduced by rotations/shifts. Default is 'nearest'. :type fill: {'constant','nearest','reflect','wrap'}, optional :param image_size: Target square size after augmentation; if None, keep original size. Default is None. :type image_size: int or None, optional :param zoom_range: Random zoom range given as (min_zoom, max_zoom). Default is None. :type zoom_range: tuple of (float, float) or None, optional :param mask_size: Side length of each random square cutout; if None, disable cutouts. Default is None. :type mask_size: int or None, optional :param num_masks: Number of cutouts applied per image when `mask_size` is set. Default is None. :type num_masks: int or None, optional :param blend_multiplier: Synthetic blending factor (≥1 adds blended samples, 0 disables blending). Default is 0. :type blend_multiplier: float, optional :param blending_func: Operator used when blending multiple images. Default is 'mean'. :type blending_func: {'mean','max','min','random'}, optional :param num_images_to_blend: Number of images combined per synthetic blend operation. Default is 2. :type num_images_to_blend: int, optional :param skew_angle: Maximum absolute skew angle in degrees; sampled uniformly from [−skew_angle, +skew_angle]. Default is 0. :type skew_angle: float, optional :rtype: None .. py:method:: plot_tsne(legend_loc='upper center', title='Feature Parameter Space', savefig=False) Plot a t-SNE projection of images (train and optional validation). Data are flattened per image and embedded into 2D using sklearn’s TSNE. :param legend_loc: Matplotlib legend location string (e.g., 'upper center'). Default is 'upper center'. :type legend_loc: str, optional :param title: Figure title displayed above the plot. Default is 'Feature Parameter Space'. :type title: str, optional :param savefig: If True, save the figure to 'Images_tSNE_Projection.png' instead of showing it. Default is False. :type savefig: bool, optional :rtype: None .. rubric:: Notes Data should be normalized prior to plotting for meaningful distances (see the `normalize` option during training). .. py:method:: plot_performance(metric='acc', combine=False, cv_model=0, ylabel=None, title=None, xlim=None, ylim=None, xlog=False, ylog=False, legend_loc=9, savefig=False) Plot training (and optional validation) curves for a chosen metric. :param metric: Metric to visualize: accuracy, loss, or F1 score. Default is 'acc'. :type metric: {'acc','loss','f1'}, optional :param combine: If True, include the corresponding validation curves when available. Default is False. :type combine: bool, optional :param cv_model: Which CV model’s history to plot, or 'all' to overlay every fold. Default is 0. :type cv_model: int or {'all'}, optional :param ylabel: Custom y-axis label; if None, derived from `metric`. Default is None. :type ylabel: str or None, optional :param title: Custom plot title; if None, derived from `metric`. Default is None. :type title: str or None, optional :param xlim: Matplotlib-style (xmin, xmax) limits for the x-axis. Default is None. :type xlim: tuple or None, optional :param ylim: Matplotlib-style (ymin, ymax) limits for the y-axis. Default is None. :type ylim: tuple or None, optional :param xlog: If True, use a logarithmic x-axis. Default is False. :type xlog: bool, optional :param ylog: If True, use a logarithmic y-axis. Default is False. :type ylog: bool, optional :param legend_loc: Legend location (Matplotlib convention). Default is 9. :type legend_loc: int or str, optional :param savefig: If True, save to 'CNN_Training_History_.png' instead of showing. Default is False. :type savefig: bool, optional :rtype: None :raises ValueError: If histories are not available or `combine=True` without validation metrics. .. py:method:: _plot_positive(index=0, channel=0, default_scale=True, vmin=None, vmax=None, cmap='gray', title='') Display a single positive-class image (optionally a single channel or colorized). :param index: Index of the sample within the positive class to display. Default is 0. :type index: int, optional :param channel: Channel index (0-based) to display, or 'all' to show a colorized composite. Default is 0. :type channel: int or {'all'}, optional :param default_scale: If True, use Matplotlib’s default scaling; if False, use `vmin`/`vmax` or compute robust limits. Default is True. :type default_scale: bool, optional :param vmin: Lower display limit when `default_scale` is False; if None, compute robust limits. Default is None. :type vmin: float or None, optional :param vmax: Upper display limit when `default_scale` is False; if None, compute robust limits. Default is None. :type vmax: float or None, optional :param cmap: Colormap used when displaying a single channel. Default is 'gray'. :type cmap: str, optional :param title: Title displayed above the image. Default is ''. :type title: str, optional :rtype: None .. py:method:: _plot_negative(index=0, channel=0, default_scale=True, vmin=None, vmax=None, cmap='gray', title='') Display a single negative-class image (optionally a single channel or colorized). :param index: Index of the sample within the negative class to display. Default is 0. :type index: int, optional :param channel: Channel index (0-based) to display, or 'all' to show a colorized composite. Default is 0. :type channel: int or {'all'}, optional :param default_scale: If True, use Matplotlib’s default scaling; if False, use `vmin`/`vmax` or compute robust limits. Default is True. :type default_scale: bool, optional :param vmin: Lower display limit when `default_scale` is False; if None, compute robust limits. Default is None. :type vmin: float or None, optional :param vmax: Upper display limit when `default_scale` is False; if None, compute robust limits. Default is None. :type vmax: float or None, optional :param cmap: Colormap used when displaying a single channel. Default is 'gray'. :type cmap: str, optional :param title: Title displayed above the image. Default is ''. :type title: str, optional :rtype: None .. py:function:: custom_model(positive_class, negative_class, img_num_channels=1, normalize=True, min_pixel=0, max_pixel=100, val_positive=None, val_negative=None, epochs=100, batch_size=32, optimizer='sgd', lr=0.0001, momentum=0.9, decay=0.0, nesterov=False, rho=0.9, beta_1=0.9, beta_2=0.999, amsgrad=False, loss='binary_crossentropy', conv_init='uniform_scaling', dense_init='truncated_normal', activation_conv='relu', activation_dense='relu', conv_reg=0, dense_reg=0, padding='same', model_reg='batch_norm', filter_1=256, filter_size_1=7, strides_1=1, pooling_1='average', pool_size_1=3, pool_stride_1=3, filter_2=0, filter_size_2=0, strides_2=0, pooling_2=None, pool_size_2=0, pool_stride_2=0, filter_3=0, filter_size_3=0, strides_3=0, pooling_3=None, pool_size_3=0, pool_stride_3=0, dense_neurons_1=4096, dropout_1=0.5, dense_neurons_2=0, dropout_2=0, dense_neurons_3=0, dropout_3=0, patience=0, metric='binary_accuracy', early_stop_callback=None, checkpoint=False, weight=None, verbose=1, save_training_data=False, path=None) Build and train a configurable CNN with 1–3 Conv2D(+pool) blocks followed by up to 3 dense layers. The network applies optional normalization, shuffles classes, constructs train/validation sets, and trains with optional early stopping and checkpointing. Batch normalization is applied after each Conv2D when `model_reg='batch_norm'`. :param positive_class: Training images for the positive class. Shape (N, H, W) for single-channel or (N, H, W, C) for multi-channel. Required. :type positive_class: ndarray :param negative_class: Training images for the negative class. Shape (N, H, W) or (N, H, W, C). Required. :type negative_class: ndarray :param img_num_channels: Number of channels per image (C). Used by preprocessing and input shape. Default is 1. :type img_num_channels: int, optional :param normalize: If True, apply min–max normalization using `min_pixel`/`max_pixel`. Default is True. :type normalize: bool, optional :param min_pixel: Lower clip bound used during normalization when `normalize` is True. Default is 0. :type min_pixel: float, optional :param max_pixel: Upper clip bound used during normalization when `normalize` is True. Default is 100. :type max_pixel: float, optional :param val_positive: Validation images for the positive class, same shape convention as training. Default is None. :type val_positive: ndarray or None, optional :param val_negative: Validation images for the negative class, same shape convention as training. Default is None. :type val_negative: ndarray or None, optional :param epochs: Number of training epochs. Default is 100. :type epochs: int, optional :param batch_size: Mini-batch size. Default is 32. :type batch_size: int, optional :param optimizer: Optimizer name understood by `get_optimizer`. Default is 'sgd'. :type optimizer: {'sgd','adam','rmsprop','adadelta','adamw'} or str, optional :param lr: Base learning rate passed to the optimizer. Default is 1e-4. :type lr: float, optional :param momentum: Momentum parameter for SGD-like optimizers. Default is 0.9. :type momentum: float, optional :param decay: Learning-rate decay per epoch (if supported by the optimizer). Default is 0.0. :type decay: float, optional :param nesterov: If True, enable Nesterov momentum for SGD. Default is False. :type nesterov: bool, optional :param rho: Decay factor used by Adadelta/RMSprop-style optimizers. Default is 0.9. :type rho: float, optional :param beta_1: First-moment decay for Adam-style optimizers. Default is 0.9. :type beta_1: float, optional :param beta_2: Second-moment decay for Adam-style optimizers. Default is 0.999. :type beta_2: float, optional :param amsgrad: If True, use the AMSGrad variant for Adam-style optimizers. Default is False. :type amsgrad: bool, optional :param loss: Loss identifier passed to `get_loss_function` (supports class weighting via `weight`). Default is 'binary_crossentropy'. :type loss: str, optional :param conv_init: Convolution kernel initializer. The alias 'uniform_scaling' maps to `VarianceScaling(scale=1.0, mode='fan_in', distribution='uniform')`. Default is 'uniform_scaling'. :type conv_init: str or tf.keras.initializers.Initializer, optional :param dense_init: Dense kernel initializer. The alias 'uniform_scaling' maps as above. Default is 'truncated_normal'. :type dense_init: str or tf.keras.initializers.Initializer, optional :param activation_conv: Activation applied after each Conv2D (post-BN if enabled). Default is 'relu'. :type activation_conv: str, optional :param activation_dense: Activation applied in dense layers (post-BN if enabled). Default is 'relu'. :type activation_dense: str, optional :param conv_reg: L2 weight for convolution kernels. Default is 0. :type conv_reg: float, optional :param dense_reg: L2 weight for dense kernels. Default is 0. :type dense_reg: float, optional :param padding: Padding mode for Conv2D and pooling layers. Default is 'same'. :type padding: {'same','valid'}, optional :param model_reg: Per-block regularization: batch normalization or local response normalization (LRN after pooling), or None. Default is 'batch_norm'. :type model_reg: {'batch_norm','local_response',None}, optional :param filter_1: Number of filters in Conv2D block 1. Set ≤0 to disable the block. Default is 256. :type filter_1: int, optional :param filter_size_1: Kernel size (square) for block 1 Conv2D. Default is 7. :type filter_size_1: int, optional :param strides_1: Convolution stride for block 1. Default is 1. :type strides_1: int, optional :param pooling_1: Pooling type after block-1 Conv2D (custom 'min' pooling supported). Default is 'average'. :type pooling_1: {'max','average','min',None}, optional :param pool_size_1: Pooling window size for block 1. Default is 3. :type pool_size_1: int, optional :param pool_stride_1: Pooling stride for block 1. Default is 3. :type pool_stride_1: int, optional :param filter_2: Number of filters in Conv2D block 2. Set ≤0 to disable the block. Default is 0. :type filter_2: int, optional :param filter_size_2: Kernel size (square) for block 2 Conv2D (required if block enabled). Default is 0. :type filter_size_2: int, optional :param strides_2: Convolution stride for block 2 (required if block enabled). Default is 0. :type strides_2: int, optional :param pooling_2: Pooling type after block-2 Conv2D. Default is None. :type pooling_2: {'max','average','min',None}, optional :param pool_size_2: Pooling window size for block 2. Default is 0. :type pool_size_2: int, optional :param pool_stride_2: Pooling stride for block 2. Default is 0. :type pool_stride_2: int, optional :param filter_3: Number of filters in Conv2D block 3. Set ≤0 to disable the block. Default is 0. :type filter_3: int, optional :param filter_size_3: Kernel size (square) for block 3 Conv2D (required if block enabled). Default is 0. :type filter_size_3: int, optional :param strides_3: Convolution stride for block 3 (required if block enabled). Default is 0. :type strides_3: int, optional :param pooling_3: Pooling type after block-3 Conv2D. Default is None. :type pooling_3: {'max','average','min',None}, optional :param pool_size_3: Pooling window size for block 3. Default is 0. :type pool_size_3: int, optional :param pool_stride_3: Pooling stride for block 3. Default is 0. :type pool_stride_3: int, optional :param dense_neurons_1: Units in the first fully-connected (dense) layer. Default is 4096. :type dense_neurons_1: int, optional :param dropout_1: Dropout rate after the first dense layer (0–1). Default is 0.5. :type dropout_1: float, optional :param dense_neurons_2: Units in the second dense layer; set ≤0 to skip the layer. Default is 0. :type dense_neurons_2: int, optional :param dropout_2: Dropout rate after the second dense layer. Default is 0. :type dropout_2: float, optional :param dense_neurons_3: Units in the third dense layer; set ≤0 to skip the layer. Default is 0. :type dense_neurons_3: int, optional :param dropout_3: Dropout rate after the third dense layer. Default is 0. :type dropout_3: float, optional :param patience: Early-stopping patience (epochs without improvement on `metric`). A value of 0 disables early stopping. Default is 0. :type patience: int, optional :param metric: Metric monitored by early stopping and checkpointing. The token 'all' is coerced internally to 'loss' or 'val_loss'. Default is 'binary_accuracy'. :type metric: {'loss','val_loss','binary_accuracy','val_binary_accuracy','f1_score','val_f1_score'}, optional :param early_stop_callback: Additional callback (e.g., from an external optimizer) to signal pruning. Default is None. :type early_stop_callback: keras.callbacks.Callback or None, optional :param checkpoint: If True, save the best model weights to '~/checkpoint.hdf5' monitored by `metric`. Default is False. :type checkpoint: bool, optional :param weight: Class weight used by certain custom loss wrappers (see `get_loss_function`). Default is None. :type weight: float or None, optional :param verbose: Keras verbosity level (0=silent, 1=progress bar, 2=one line per epoch). Default is 1. :type verbose: {0,1,2}, optional :param save_training_data: If True, save the processed training/validation arrays to `path`. Default is False. :type save_training_data: bool, optional :param path: Directory used when saving training data. If None, the home directory is used. Default is None. :type path: str or None, optional :returns: * **model** (*tf.keras.Model*) -- The compiled and trained Keras model (binary sigmoid output). * **history** (*tf.keras.callbacks.History*) -- Keras history object containing per-epoch metrics. :raises ValueError: If any enabled convolutional block is missing its required `filter_size_*` or `strides_*` arguments. .. rubric:: Notes - Inputs are shuffled within each class before constructing the training set. - When validation data are provided, the same normalization/clipping is applied. - Batch normalization can be unstable with very small `batch_size`; if training diverges (NaNs), try a larger batch or smaller learning rate. - `model_reg='local_response'` inserts LRN after pooling in each enabled block. .. py:function:: AlexNet(positive_class, negative_class, img_num_channels=1, normalize=True, min_pixel=0, max_pixel=100, val_positive=None, val_negative=None, epochs=100, batch_size=32, optimizer='sgd', lr=0.0001, momentum=0.9, decay=0.0, nesterov=False, rho=0.9, beta_1=0.9, beta_2=0.999, amsgrad=False, loss='binary_crossentropy', conv_init='uniform_scaling', dense_init='truncated_normal', activation_conv='relu', activation_dense='relu', conv_reg=0, dense_reg=0, padding='same', model_reg='local_response', filter_1=96, filter_size_1=11, strides_1=4, pooling_1='max', pool_size_1=3, pool_stride_1=2, filter_2=256, filter_size_2=5, strides_2=1, pooling_2='max', pool_size_2=3, pool_stride_2=2, filter_3=384, filter_size_3=3, strides_3=1, pooling_3='max', pool_size_3=3, pool_stride_3=2, filter_4=384, filter_size_4=3, strides_4=1, filter_5=256, filter_size_5=3, strides_5=1, dense_neurons_1=4096, dense_neurons_2=4096, dropout_1=0.5, dropout_2=0.5, patience=0, metric='binary_accuracy', early_stop_callback=None, checkpoint=False, weight=None, verbose=1, save_training_data=False, path=None) Build and train an AlexNet-style CNN adapted for binary classification of astronomical images. The architecture follows the classic Conv–Pool blocks with Local Response Normalization (LRN) by default and provides options for Batch Normalization instead. Inputs can be min–max normalized to mitigate gradient issues; the model trains with optional early stopping and checkpointing. :param positive_class: Training images for the positive class. Shape (N, H, W) for single-channel or (N, H, W, C) for multi-channel. Required. :type positive_class: ndarray :param negative_class: Training images for the negative class. Shape (N, H, W) or (N, H, W, C). Required. :type negative_class: ndarray :param img_num_channels: Number of channels per image (C). Used for preprocessing and model input shape. Default is 1. :type img_num_channels: int, optional :param normalize: If True, apply min–max normalization using `min_pixel` and `max_pixel`. Default is True. :type normalize: bool, optional :param min_pixel: Lower clip bound used during normalization when `normalize` is True. Default is 0. :type min_pixel: float, optional :param max_pixel: Upper clip bound used during normalization when `normalize` is True. Default is 100. :type max_pixel: float, optional :param val_positive: Validation images for the positive class, same shape convention as training. Default is None. :type val_positive: ndarray or None, optional :param val_negative: Validation images for the negative class, same shape convention as training. Default is None. :type val_negative: ndarray or None, optional :param epochs: Number of training epochs. Default is 100. :type epochs: int, optional :param batch_size: Mini-batch size. Default is 32. :type batch_size: int, optional :param optimizer: Optimizer name understood by `get_optimizer`. Default is 'sgd'. :type optimizer: {'sgd','adam','rmsprop','adadelta','adamw'} or str, optional :param lr: Base learning rate passed to the optimizer. Default is 1e-4. :type lr: float, optional :param momentum: Momentum parameter for SGD-like optimizers. Default is 0.9. :type momentum: float, optional :param decay: Learning-rate decay per epoch (if supported by the optimizer). Default is 0.0. :type decay: float, optional :param nesterov: If True, enable Nesterov momentum for SGD. Default is False. :type nesterov: bool, optional :param rho: Decay factor used by Adadelta/RMSprop-style optimizers. Default is 0.9. :type rho: float, optional :param beta_1: First-moment decay for Adam-style optimizers. Default is 0.9. :type beta_1: float, optional :param beta_2: Second-moment decay for Adam-style optimizers. Default is 0.999. :type beta_2: float, optional :param amsgrad: If True, use the AMSGrad variant for Adam-style optimizers. Default is False. :type amsgrad: bool, optional :param loss: Loss identifier passed to `get_loss_function` (supports class weighting via `weight`). Default is 'binary_crossentropy'. :type loss: str, optional :param conv_init: Convolution kernel initializer. The alias 'uniform_scaling' maps to `VarianceScaling(scale=1.0, mode='fan_in', distribution='uniform')`. Default is 'uniform_scaling'. :type conv_init: str or tf.keras.initializers.Initializer, optional :param dense_init: Dense kernel initializer. The alias 'uniform_scaling' maps as above when used. Default is 'truncated_normal'. :type dense_init: str or tf.keras.initializers.Initializer, optional :param activation_conv: Activation applied after each Conv2D (post-BN if enabled). Default is 'relu'. :type activation_conv: str, optional :param activation_dense: Activation applied in dense layers (post-BN if enabled). Default is 'relu'. :type activation_dense: str, optional :param conv_reg: L2 weight for convolution kernels. Default is 0. :type conv_reg: float, optional :param dense_reg: L2 weight for dense kernels. Default is 0. :type dense_reg: float, optional :param padding: Padding mode for Conv2D and pooling layers. Default is 'same'. :type padding: {'same','valid'}, optional :param model_reg: Block-level regularization: Batch Normalization (after Conv2D), Local Response Normalization (after pooling, AlexNet-style), or None. Default is 'local_response'. :type model_reg: {'batch_norm','local_response',None}, optional :param filter_1: Number of filters in Conv2D block 1. Default is 96. :type filter_1: int, optional :param filter_size_1: Kernel size (square) for block-1 Conv2D. Default is 11. :type filter_size_1: int, optional :param strides_1: Convolution stride for block-1. Default is 4. :type strides_1: int, optional :param pooling_1: Pooling type after block-1 Conv2D (custom 'min' pooling supported). Default is 'max'. :type pooling_1: {'max','average','min',None}, optional :param pool_size_1: Pooling window size for block-1. Default is 3. :type pool_size_1: int, optional :param pool_stride_1: Pooling stride for block-1. Default is 2. :type pool_stride_1: int, optional :param filter_2: Number of filters in Conv2D block 2. Default is 256. :type filter_2: int, optional :param filter_size_2: Kernel size (square) for block-2 Conv2D. Default is 5. :type filter_size_2: int, optional :param strides_2: Convolution stride for block-2. Default is 1. :type strides_2: int, optional :param pooling_2: Pooling type after block-2 Conv2D. Default is 'max'. :type pooling_2: {'max','average','min',None}, optional :param pool_size_2: Pooling window size for block-2. Default is 3. :type pool_size_2: int, optional :param pool_stride_2: Pooling stride for block-2. Default is 2. :type pool_stride_2: int, optional :param filter_3: Number of filters in Conv2D block 3. Default is 384. :type filter_3: int, optional :param filter_size_3: Kernel size (square) for block-3 Conv2D. Default is 3. :type filter_size_3: int, optional :param strides_3: Convolution stride for block-3. Default is 1. :type strides_3: int, optional :param pooling_3: Pooling type after block-3 Conv2D (applied after block-5 in this variant). Default is 'max'. :type pooling_3: {'max','average','min',None}, optional :param pool_size_3: Pooling window size for the final pooling stage. Default is 3. :type pool_size_3: int, optional :param pool_stride_3: Pooling stride for the final pooling stage. Default is 2. :type pool_stride_3: int, optional :param filter_4: Number of filters in Conv2D block 4. Default is 384. :type filter_4: int, optional :param filter_size_4: Kernel size (square) for block-4 Conv2D. Default is 3. :type filter_size_4: int, optional :param strides_4: Convolution stride for block-4. Default is 1. :type strides_4: int, optional :param filter_5: Number of filters in Conv2D block 5. Default is 256. :type filter_5: int, optional :param filter_size_5: Kernel size (square) for block-5 Conv2D. Default is 3. :type filter_size_5: int, optional :param strides_5: Convolution stride for block-5. Default is 1. :type strides_5: int, optional :param dense_neurons_1: Units in the first fully-connected (dense) layer. Default is 4096. :type dense_neurons_1: int, optional :param dense_neurons_2: Units in the second fully-connected (dense) layer. Default is 4096. :type dense_neurons_2: int, optional :param dropout_1: Dropout rate after the first dense layer (0–1). Default is 0.5. :type dropout_1: float, optional :param dropout_2: Dropout rate after the second dense layer (0–1). Default is 0.5. :type dropout_2: float, optional :param patience: Early-stopping patience (epochs without improvement on `metric`). A value of 0 disables early stopping. Default is 0. :type patience: int, optional :param metric: Metric monitored by early stopping and checkpointing. The token 'all' is coerced internally to a single monitor ('loss' or 'val_loss'). Default is 'binary_accuracy'. :type metric: {'loss','val_loss','binary_accuracy','val_binary_accuracy','f1_score','val_f1_score','all'}, optional :param early_stop_callback: Additional callback (e.g., from an external optimizer) to signal pruning. Default is None. :type early_stop_callback: keras.callbacks.Callback or None, optional :param checkpoint: If True, save the best model weights to '~/checkpoint.hdf5' monitored by `metric`. Default is False. :type checkpoint: bool, optional :param weight: Class weight used by certain custom loss wrappers (see `get_loss_function`). Default is None. :type weight: float or None, optional :param verbose: Keras verbosity level (0=silent, 1=progress bar, 2=one line per epoch). Default is 1. :type verbose: {0,1,2}, optional :param save_training_data: If True, save the processed training/validation arrays to `path`. Default is False. :type save_training_data: bool, optional :param path: Directory used when saving training data. If None, the home directory is used. Default is None. :type path: str or None, optional :returns: * **model** (*tf.keras.Model*) -- The compiled and trained Keras model (single-neuron sigmoid output for binary classification). * **history** (*tf.keras.callbacks.History*) -- Keras history object containing per-epoch metrics. .. rubric:: Notes - Inputs are shuffled within each class before constructing the training set. - When validation data are provided, the same normalization/clipping is applied. - Batch Normalization can be unstable with very small `batch_size`; if training diverges (NaNs), try a larger batch size or a smaller learning rate. - `model_reg='local_response'` inserts LRN after pooling in accordance with the original AlexNet paper; `model_reg='batch_norm'` places BatchNorm after Conv2D and before activation. .. py:function:: VGG16(positive_class, negative_class, img_num_channels=1, normalize=True, min_pixel=0, max_pixel=100, val_positive=None, val_negative=None, epochs=100, batch_size=32, optimizer='sgd', lr=0.0001, momentum=0.9, decay=0.0, nesterov=False, rho=0.9, beta_1=0.9, beta_2=0.999, amsgrad=False, loss='binary_crossentropy', conv_init='uniform_scaling', dense_init='truncated_normal', activation_conv='relu', activation_dense='relu', conv_reg=0, dense_reg=0, padding='same', model_reg=None, filter_1=64, filter_size_1=3, strides_1=1, pooling_1='max', pool_size_1=2, pool_stride_1=2, filter_2=128, filter_size_2=3, strides_2=1, pooling_2='max', pool_size_2=2, pool_stride_2=2, filter_3=256, filter_size_3=3, strides_3=1, pooling_3='max', pool_size_3=2, pool_stride_3=2, filter_4=512, filter_size_4=3, strides_4=1, pooling_4='max', pool_size_4=2, pool_stride_4=2, filter_5=512, filter_size_5=3, strides_5=1, pooling_5='max', pool_size_5=2, pool_stride_5=2, dense_neurons_1=4096, dense_neurons_2=4096, dropout_1=0.5, dropout_2=0.5, patience=0, metric='binary_accuracy', early_stop_callback=None, checkpoint=False, weight=None, verbose=1, save_training_data=False, path=None) Build and train a VGG16-style CNN for binary classification of astronomical images. The model follows five convolutional blocks (with small 3×3 kernels) and two fully-connected layers, with configurable pooling and optional Batch Normalization or Local Response Normalization after pooling. Inputs can be min–max normalized prior to training. :param positive_class: Training images for the positive class. Shape (N, H, W) or (N, H, W, C). Required. :type positive_class: ndarray :param negative_class: Training images for the negative class. Shape (N, H, W) or (N, H, W, C). Required. :type negative_class: ndarray :param img_num_channels: Number of channels per image (C) for preprocessing/input shape. Default is 1. :type img_num_channels: int, optional :param normalize: If True, apply min–max normalization using `min_pixel`/`max_pixel`. Default is True. :type normalize: bool, optional :param min_pixel: Lower clip bound used during normalization when `normalize` is True. Default is 0. :type min_pixel: float, optional :param max_pixel: Upper clip bound used during normalization when `normalize` is True. Default is 100. :type max_pixel: float, optional :param val_positive: Validation images for the positive class, same shape convention as training. Default is None. :type val_positive: ndarray or None, optional :param val_negative: Validation images for the negative class, same shape convention as training. Default is None. :type val_negative: ndarray or None, optional :param epochs: Number of training epochs. Default is 100. :type epochs: int, optional :param batch_size: Mini-batch size. Default is 32. :type batch_size: int, optional :param optimizer: Optimizer identifier understood by `get_optimizer`. Default is 'sgd'. :type optimizer: {'sgd','adam','rmsprop','adadelta','adamw'} or str, optional :param lr: Base learning rate passed to the optimizer. Default is 1e-4. :type lr: float, optional :param momentum: Momentum for SGD-like optimizers. Default is 0.9. :type momentum: float, optional :param decay: Learning-rate decay per epoch (if supported by optimizer). Default is 0.0. :type decay: float, optional :param nesterov: If True, enable Nesterov momentum for SGD. Default is False. :type nesterov: bool, optional :param rho: Decay factor used by Adadelta/RMSprop-style optimizers. Default is 0.9. :type rho: float, optional :param beta_1: First-moment decay for Adam-style optimizers. Default is 0.9. :type beta_1: float, optional :param beta_2: Second-moment decay for Adam-style optimizers. Default is 0.999. :type beta_2: float, optional :param amsgrad: If True, use the AMSGrad variant of Adam. Default is False. :type amsgrad: bool, optional :param loss: Loss identifier passed to `get_loss_function` (supports class weighting via `weight`). Default is 'binary_crossentropy'. :type loss: str, optional :param conv_init: Convolution kernel initializer; 'uniform_scaling' maps to `VarianceScaling(...)`. Default is 'uniform_scaling'. :type conv_init: str or tf.keras.initializers.Initializer, optional :param dense_init: Dense kernel initializer; 'uniform_scaling' maps to `VarianceScaling(...)`. Default is 'truncated_normal'. :type dense_init: str or tf.keras.initializers.Initializer, optional :param activation_conv: Activation applied after each Conv2D (post-BN if enabled). Default is 'relu'. :type activation_conv: str, optional :param activation_dense: Activation applied in dense layers (post-BN if enabled). Default is 'relu'. :type activation_dense: str, optional :param conv_reg: L2 weight for convolution kernels. Default is 0. :type conv_reg: float, optional :param dense_reg: L2 weight for dense kernels. Default is 0. :type dense_reg: float, optional :param padding: Padding mode for Conv2D and pooling layers. Default is 'same'. :type padding: {'same','valid'}, optional :param model_reg: Block regularization: BatchNorm (after Conv2D), LRN (after pooling), or None. Default is None. :type model_reg: {'batch_norm','local_response',None}, optional :param filter_1: Number of filters in block-1 Conv2D layers. Default is 64. :type filter_1: int, optional :param filter_size_1: Kernel size (square) for block-1 Conv2D. Default is 3. :type filter_size_1: int, optional :param strides_1: Convolution stride for block-1. Default is 1. :type strides_1: int, optional :param pooling_1: Pooling type after block-1. Default is 'max'. :type pooling_1: {'max','average','min',None}, optional :param pool_size_1: Pooling window size for block-1. Default is 2. :type pool_size_1: int, optional :param pool_stride_1: Pooling stride for block-1. Default is 2. :type pool_stride_1: int, optional :param filter_2: Number of filters in block-2 Conv2D layers. Default is 128. :type filter_2: int, optional :param filter_size_2: Kernel size (square) for block-2 Conv2D. Default is 3. :type filter_size_2: int, optional :param strides_2: Convolution stride for block-2. Default is 1. :type strides_2: int, optional :param pooling_2: Pooling type after block-2. Default is 'max'. :type pooling_2: {'max','average','min',None}, optional :param pool_size_2: Pooling window size for block-2. Default is 2. :type pool_size_2: int, optional :param pool_stride_2: Pooling stride for block-2. Default is 2. :type pool_stride_2: int, optional :param filter_3: Number of filters in block-3 Conv2D layers. Default is 256. :type filter_3: int, optional :param filter_size_3: Kernel size (square) for block-3 Conv2D. Default is 3. :type filter_size_3: int, optional :param strides_3: Convolution stride for block-3. Default is 1. :type strides_3: int, optional :param pooling_3: Pooling type after block-3. Default is 'max'. :type pooling_3: {'max','average','min',None}, optional :param pool_size_3: Pooling window size for block-3. Default is 2. :type pool_size_3: int, optional :param pool_stride_3: Pooling stride for block-3. Default is 2. :type pool_stride_3: int, optional :param filter_4: Number of filters in block-4 Conv2D layers. Default is 512. :type filter_4: int, optional :param filter_size_4: Kernel size (square) for block-4 Conv2D. Default is 3. :type filter_size_4: int, optional :param strides_4: Convolution stride for block-4. Default is 1. :type strides_4: int, optional :param pooling_4: Pooling type after block-4. Default is 'max'. :type pooling_4: {'max','average','min',None}, optional :param pool_size_4: Pooling window size for block-4. Default is 2. :type pool_size_4: int, optional :param pool_stride_4: Pooling stride for block-4. Default is 2. :type pool_stride_4: int, optional :param filter_5: Number of filters in block-5 Conv2D layers. Default is 512. :type filter_5: int, optional :param filter_size_5: Kernel size (square) for block-5 Conv2D. Default is 3. :type filter_size_5: int, optional :param strides_5: Convolution stride for block-5. Default is 1. :type strides_5: int, optional :param pooling_5: Pooling type after block-5. Default is 'max'. :type pooling_5: {'max','average','min',None}, optional :param pool_size_5: Pooling window size for block-5. Default is 2. :type pool_size_5: int, optional :param pool_stride_5: Pooling stride for block-5. Default is 2. :type pool_stride_5: int, optional :param dense_neurons_1: Units in the first fully-connected (dense) layer. Default is 4096. :type dense_neurons_1: int, optional :param dense_neurons_2: Units in the second fully-connected (dense) layer. Default is 4096. :type dense_neurons_2: int, optional :param dropout_1: Dropout rate after the first dense layer (0–1). Default is 0.5. :type dropout_1: float, optional :param dropout_2: Dropout rate after the second dense layer (0–1). Default is 0.5. :type dropout_2: float, optional :param patience: Early-stopping patience (epochs without improvement on `metric`); 0 disables early stopping. Default is 0. :type patience: int, optional :param metric: Metric monitored by early stopping/checkpointing; 'all' is coerced internally to a single monitor. Default is 'binary_accuracy'. :type metric: {'loss','val_loss','binary_accuracy','val_binary_accuracy','f1_score','val_f1_score','all'}, optional :param early_stop_callback: Additional callback (e.g., for pruning within external HPO). Default is None. :type early_stop_callback: keras.callbacks.Callback or None, optional :param checkpoint: If True, save best model weights to '~/checkpoint.hdf5' monitored by `metric`. Default is False. :type checkpoint: bool, optional :param weight: Class weight used by certain custom loss wrappers (see `get_loss_function`). Default is None. :type weight: float or None, optional :param verbose: Keras verbosity level (0=silent, 1=progress bar, 2=one line/epoch). Default is 1. :type verbose: {0,1,2}, optional :param save_training_data: If True, save processed training/validation arrays to `path`. Default is False. :type save_training_data: bool, optional :param path: Directory used when saving training data; home directory is used if None. Default is None. :type path: str or None, optional :returns: * **model** (*tf.keras.Model*) -- The compiled and trained Keras model (single-neuron sigmoid output for binary classification). * **history** (*tf.keras.callbacks.History*) -- Keras history object with per-epoch metrics. .. rubric:: Notes - Inputs are shuffled within each class prior to constructing the training set. - When validation data are provided, the same normalization/clipping is applied. - Batch Normalization can be unstable with very small `batch_size`; if training diverges (NaNs), try a larger batch size or a smaller learning rate. .. py:function:: Resnet18(positive_class, negative_class, img_num_channels=1, normalize=True, min_pixel=0, max_pixel=100, val_positive=None, val_negative=None, epochs=100, batch_size=32, optimizer='sgd', lr=0.0001, momentum=0.9, decay=0.0, nesterov=False, rho=0.9, beta_1=0.9, beta_2=0.999, amsgrad=False, loss='binary_crossentropy', conv_init='uniform_scaling', dense_init='truncated_normal', activation_conv='relu', activation_dense='relu', conv_reg=0, dense_reg=0, padding='same', model_reg=None, filters=64, filter_size=7, strides=2, pooling='max', pool_size=3, pool_stride=2, block_filters_1=64, block_filters_2=128, block_filters_3=256, block_filters_4=512, block_filters_size=3, patience=0, metric='binary_accuracy', early_stop_callback=None, checkpoint=False, weight=None, verbose=1, save_training_data=False, path=None) Build and train a ResNet-18–style CNN with configurable stem, residual block widths, optimization hyperparameters, and optional Batch Normalization in the stem. :param positive_class: Training images for the positive class, shape (N, H, W) or (N, H, W, C). Default is required. :type positive_class: ndarray :param negative_class: Training images for the negative class, shape (N, H, W) or (N, H, W, C). Default is required. :type negative_class: ndarray :param img_num_channels: Number of channels per image (C) for preprocessing/input shape. Default is 1. :type img_num_channels: int, optional :param normalize: If True, apply min–max normalization using `min_pixel`/`max_pixel`. Default is True. :type normalize: bool, optional :param min_pixel: Lower clip bound used during normalization when `normalize` is True. Default is 0. :type min_pixel: float, optional :param max_pixel: Upper clip bound used during normalization when `normalize` is True. Default is 100. :type max_pixel: float, optional :param val_positive: Validation images for the positive class, same shape convention as training. Default is None. :type val_positive: ndarray or None, optional :param val_negative: Validation images for the negative class, same shape convention as training. Default is None. :type val_negative: ndarray or None, optional :param epochs: Number of training epochs. Default is 100. :type epochs: int, optional :param batch_size: Mini-batch size. Default is 32. :type batch_size: int, optional :param optimizer: Optimizer identifier understood by `get_optimizer`. Default is 'sgd'. :type optimizer: {'sgd','adam','rmsprop','adadelta','adamw'} or str, optional :param lr: Base learning rate passed to the optimizer. Default is 1e-4. :type lr: float, optional :param momentum: Momentum for SGD-like optimizers. Default is 0.9. :type momentum: float, optional :param decay: Learning-rate decay per epoch (if supported by optimizer). Default is 0.0. :type decay: float, optional :param nesterov: If True, enable Nesterov momentum for SGD. Default is False. :type nesterov: bool, optional :param rho: Decay factor used by Adadelta/RMSprop-style optimizers. Default is 0.9. :type rho: float, optional :param beta_1: First-moment decay for Adam-style optimizers. Default is 0.9. :type beta_1: float, optional :param beta_2: Second-moment decay for Adam-style optimizers. Default is 0.999. :type beta_2: float, optional :param amsgrad: If True, use the AMSGrad variant of Adam. Default is False. :type amsgrad: bool, optional :param loss: Loss identifier passed to `get_loss_function` (supports class weighting via `weight`). Default is 'binary_crossentropy'. :type loss: str, optional :param conv_init: Convolution kernel initializer; 'uniform_scaling' maps to `VarianceScaling(...)`. Default is 'uniform_scaling'. :type conv_init: str or tf.keras.initializers.Initializer, optional :param dense_init: Dense kernel initializer; 'truncated_normal' or initializer instance. Default is 'truncated_normal'. :type dense_init: str or tf.keras.initializers.Initializer, optional :param activation_conv: Activation used inside residual blocks and stem (post-BN if enabled). Default is 'relu'. :type activation_conv: str, optional :param activation_dense: Activation for dense layers (not used in standard ResNet-18 head). Default is 'relu'. :type activation_dense: str, optional :param conv_reg: L2 weight for convolution kernels. Default is 0. :type conv_reg: float, optional :param dense_reg: L2 weight for dense kernels (not used by the default single-neuron head). Default is 0. :type dense_reg: float, optional :param padding: Convolution padding mode within residual blocks. Default is 'same'. :type padding: {'same','valid'}, optional :param model_reg: If 'batch_norm', apply Batch Normalization in the stem and blocks; otherwise omit. Default is None. :type model_reg: {'batch_norm', None}, optional :param filters: Number of filters in the stem 7×7 convolution. Default is 64. :type filters: int, optional :param filter_size: Kernel size (square) of the stem convolution. Default is 7. :type filter_size: int, optional :param strides: Stride of the stem convolution. Default is 2. :type strides: int, optional :param pooling: Pooling type after the stem convolution. Default is 'max'. :type pooling: {'max','average','min'}, optional :param pool_size: Pooling window size for the stem pooling layer. Default is 3. :type pool_size: int, optional :param pool_stride: Stride for the stem pooling layer. Default is 2. :type pool_stride: int, optional :param block_filters_1: Filters in stage-1 residual blocks (two blocks, no downsample). Default is 64. :type block_filters_1: int, optional :param block_filters_2: Filters in stage-2 residual blocks (first block downsamples). Default is 128. :type block_filters_2: int, optional :param block_filters_3: Filters in stage-3 residual blocks (first block downsamples). Default is 256. :type block_filters_3: int, optional :param block_filters_4: Filters in stage-4 residual blocks (first block downsamples). Default is 512. :type block_filters_4: int, optional :param block_filters_size: Kernel size (square) for all residual block convolutions. Default is 3. :type block_filters_size: int, optional :param patience: Early-stopping patience (epochs without improvement on `metric`); 0 disables early stopping. Default is 0. :type patience: int, optional :param metric: Metric monitored by early stopping/checkpointing; 'all' is coerced internally to a single monitor. Default is 'binary_accuracy'. :type metric: {'loss','val_loss','binary_accuracy','val_binary_accuracy','f1_score','val_f1_score','all'}, optional :param early_stop_callback: Additional callback (e.g., for pruning within external HPO). Default is None. :type early_stop_callback: keras.callbacks.Callback or None, optional :param checkpoint: If True, save best model weights to '~/checkpoint.hdf5' monitored by `metric`. Default is False. :type checkpoint: bool, optional :param weight: Class weight used by certain custom loss wrappers (see `get_loss_function`). Default is None. :type weight: float or None, optional :param verbose: Keras verbosity level (0=silent, 1=progress bar, 2=one line/epoch). Default is 1. :type verbose: {0,1,2}, optional :param save_training_data: If True, save processed training/validation arrays to `path`. Default is False. :type save_training_data: bool, optional :param path: Directory used when saving training data; home directory is used if None. Default is None. :type path: str or None, optional :returns: * **model** (*tf.keras.Model*) -- The compiled and trained Keras model (global-average-pooling head with sigmoid output). * **history** (*tf.keras.callbacks.History*) -- Keras history object with per-epoch metrics. .. rubric:: Notes - Inputs are per-class shuffled prior to constructing the training set; optional validation arrays receive the same preprocessing and clipping when `normalize` is True. - The stem applies `ZeroPadding2D(3)` before the 7×7 stride-2 convolution, followed by pooling. - Four residual stages are built as (2, 2, 2, 2) basic blocks; stages 2–4 downsample in the first block. - Batch Normalization can be unstable with very small `batch_size`; if training diverges (NaNs), try a larger batch size or a smaller learning rate. .. py:function:: resnet_block(x, filters_in, filters_out, filter_size=3, activation='relu', stride=1, padding='same', kernel_initializer='he_normal', model_reg='batch_norm') Basic residual block with two conv layers and an identity/projection skip. :param x: Input feature map tensor to be transformed by the block. Default is required. :type x: tf.Tensor :param filters_in: Number of channels in the input tensor (used to decide if projection is needed). Default is required. :type filters_in: int :param filters_out: Number of output channels for both convolutions (and the projection, if used). Default is required. :type filters_out: int :param filter_size: Square kernel size for both convolutions in the block. Default is 3. :type filter_size: int, optional :param activation: Activation applied after BatchNorm (or directly after conv if BN is disabled). Default is 'relu'. :type activation: str, optional :param stride: Stride of the first convolution (and projection); controls downsampling. Default is 1. :type stride: int, optional :param padding: Convolution padding for both conv layers in the block. Default is 'same'. :type padding: {'same','valid'}, optional :param kernel_initializer: Kernel initializer for all conv layers and the projection. Default is 'he_normal'. :type kernel_initializer: str or tf.keras.initializers.Initializer, optional :param model_reg: If 'batch_norm', apply BatchNormalization after each conv; otherwise omit normalization. Default is 'batch_norm'. :type model_reg: {'batch_norm', None}, optional :returns: Output tensor after two convolutions and residual addition (with projection when shape/stride differs). :rtype: tf.Tensor .. rubric:: Notes - A 1×1 projection on the skip path is used when `stride != 1` or `filters_in != filters_out`. - The final activation is applied after the residual addition. .. py:function:: f1_score(y_true, y_pred) Binary F1 score (harmonic mean of precision and recall) for the current batch. :param y_true: Ground-truth binary labels with shape (N,) or (N, 1). Values are expected to be 0 or 1. :type y_true: tf.Tensor :param y_pred: Model outputs with shape matching `y_true`. Values are expected to be probabilities in [0, 1] (e.g., sigmoid outputs). A fixed threshold of 0.5 is applied internally via rounding. :type y_pred: tf.Tensor :returns: Scalar tensor containing the batch F1 score in [0, 1]. :rtype: tf.Tensor .. py:function:: calculate_tp_fp(model, sample, y_true) Compute batch true positives (TP) and false positives (FP) from model predictions. The model's predicted probabilities are thresholded at 0.5 (via rounding) to obtain binary predictions. Labels are clipped to [0, 1] and rounded. Sums are computed over the batch, returning scalar tensors. :param model: Trained model providing `predict(sample)` → probabilities for the positive class. :type model: tf.keras.Model or compatible :param sample: Input batch for inference, typically with shape (N, H, W, C) or (N, d). No default; must be provided. :type sample: ndarray or tf.Tensor :param y_true: Ground-truth labels for `sample`. Shape (N,) or (N, 1) with values in {0, 1}. One-hot labels must be preconverted to a single positive column. No default. :type y_true: ndarray or tf.Tensor :returns: * **tp** (*tf.Tensor*) -- Scalar tensor equal to the count of true positives in the batch. * **fp** (*tf.Tensor*) -- Scalar tensor equal to the count of false positives in the batch. .. py:function:: focal_loss(y_true, y_pred, gamma=2.0, alpha=0.25) Binary focal loss for imbalanced classification (Lin et al., 2017). Down-weights easy examples and focuses training on hard, misclassified ones. This implementation uses binary cross-entropy with `from_logits=True`, so `y_pred` must be raw logits (pre-sigmoid). :param y_true: Ground-truth binary labels in {0, 1}; shape broadcastable to `y_pred`. No default; must be provided. :type y_true: tf.Tensor :param y_pred: Model outputs **as logits** (before sigmoid); same shape as `y_true`. No default; must be provided. :type y_pred: tf.Tensor :param gamma: Focusing parameter; larger values increase down-weighting of easy examples. Default is 2.0. :type gamma: float, optional :param alpha: Global weighting factor for the loss (often the positive-class weight). Default is 0.25. :type alpha: float, optional :returns: Element-wise focal loss with the same shape as `y_true`. Reduce with `tf.reduce_mean` or `tf.reduce_sum` for a scalar loss. :rtype: tf.Tensor .. py:function:: dice_loss(y_true, y_pred, smooth=1e-07) Dice loss for binary segmentation. :param y_true: Ground-truth binary mask in {0, 1}; shape broadcastable to `y_pred`. No default; must be provided. :type y_true: tf.Tensor :param y_pred: Predicted mask as probabilities in [0, 1] (apply sigmoid if logits); same shape as `y_true`. No default; must be provided. :type y_pred: tf.Tensor :param smooth: Smoothing constant added to numerator and denominator for numerical stability. Default is 1e-7. :type smooth: float, optional :returns: Scalar Dice loss for the batch (1 − Dice coefficient). :rtype: tf.Tensor .. py:function:: jaccard_loss(y_true, y_pred, smooth=1e-07) Jaccard (IoU) loss for binary segmentation. :param y_true: Ground-truth binary mask in {0, 1}; shape broadcastable to `y_pred`. No default; must be provided. :type y_true: tf.Tensor :param y_pred: Predicted mask as probabilities in [0, 1] (apply sigmoid if logits); same shape as `y_true`. No default; must be provided. :type y_pred: tf.Tensor :param smooth: Smoothing constant added to numerator and denominator for numerical stability. Default is 1e-7. :type smooth: float, optional :returns: Scalar Jaccard loss for the batch (1 − IoU). :rtype: tf.Tensor .. py:function:: weighted_binary_crossentropy(weight) Weighted binary cross-entropy (positive-class scaling). Returns a Keras-compatible loss function that computes binary cross-entropy with the positive term multiplied by `weight`. Use this to counter class imbalance by up-weighting positives (weight > 1) or down-weighting them (0 < weight < 1). :param weight: Non-negative scalar applied to the positive class term. Values > 1 increase the penalty for false negatives; values in (0, 1) decrease it. No default; must be provided. :type weight: float :returns: A loss function `loss(y_true, y_pred)` that returns the mean weighted binary cross-entropy over the last axis. :rtype: Callable[[tf.Tensor, tf.Tensor], tf.Tensor] .. py:function:: get_optimizer(optimizer, lr, momentum=None, decay=None, rho=0.9, nesterov=False, beta_1=0.9, beta_2=0.999, amsgrad=False) Return a configured Keras optimizer instance. :param optimizer: Optimizer name to instantiate. No default. :type optimizer: {'sgd','adam','adamax','nadam','adadelta','rmsprop'} :param lr: Learning rate for the optimizer. No default. :type lr: float :param momentum: Momentum term for SGD (ignored by other optimizers). Default is None. :type momentum: float, optional :param decay: Learning-rate time decay (not used by this function). Default is None. :type decay: float, optional :param rho: Discounting factor for the moving average of squared grads (Adadelta/RMSprop). Default is 0.9. :type rho: float, optional :param nesterov: Use Nesterov momentum with SGD. Default is False. :type nesterov: bool, optional :param beta_1: Exponential decay rate for first-moment estimates (Adam-family). Default is 0.9. :type beta_1: float, optional :param beta_2: Exponential decay rate for second-moment estimates (Adam-family). Default is 0.999. :type beta_2: float, optional :param amsgrad: Use the AMSGrad variant of Adam. Default is False. :type amsgrad: bool, optional :returns: A compiled `tf.keras.optimizers.Optimizer` instance. :rtype: optimizer :raises ValueError: If `optimizer` is not one of the supported names. .. py:function:: get_loss_function(loss, weight=None) Return a Keras-compatible loss given a symbolic name. :param loss: Name of the loss to construct. No default. :type loss: {'binary_crossentropy','hinge','squared_hinge','kld','logcosh','focal_loss','dice_loss','jaccard_loss','weighted_binary_crossentropy'} :param weight: Positive-class weight used only when `loss='weighted_binary_crossentropy'`; ignored for all other losses. Default is None. :type weight: float or None, optional :returns: **loss_fn** -- Keras-compatible loss object. This may be a string identifier (for `'binary_crossentropy'`), a `tf.keras.losses.*` instance (e.g., `Hinge()`, `KLDivergence()`, `LogCosh()`), or a callable such as `focal_loss`, `dice_loss`, `jaccard_loss`, or the result of `weighted_binary_crossentropy(weight)`. :rtype: str or tf.keras.losses.Loss or callable .. py:function:: print_params(batch_size, lr, decay, momentum, nesterov, loss, optimizer, model_reg, conv_init, activation_conv, dense_init, activation_dense, filter1, filter2, filter3, filter4, filter5, filter_size_1, filter_size_2, filter_size_3, filter_size_4, filter_size_5, pooling_1, pooling_2, pooling_3, pooling_4, pooling_5, pool_size_1, pool_size_2, pool_size_3, pool_size_4, pool_size_5, conv_reg, dense_reg, dense_neurons_1, dense_neurons_2, dense_neurons_3, dropout_1, dropout_2, dropout_3, beta_1, beta_2, amsgrad, rho) Print a formatted summary of training hyperparameters and model architecture settings. :param batch_size: Number of samples per gradient update. No default. :type batch_size: int :param lr: Optimizer learning rate. No default. :type lr: float :param decay: Learning-rate time decay (per update/epoch, depending on optimizer). No default. :type decay: float :param momentum: SGD momentum coefficient. No default. :type momentum: float :param nesterov: Whether SGD uses Nesterov momentum. No default. :type nesterov: bool :param loss: Name of the loss function (e.g., 'binary_crossentropy'). No default. :type loss: str :param optimizer: Optimizer identifier (e.g., 'sgd','adam','rmsprop','adadelta','adamax','nadam'). No default. :type optimizer: str :param model_reg: Model-level regularization flag (e.g., 'batch_norm','local_response', or None). No default. :type model_reg: str or None :param conv_init: Convolutional kernel initializer (e.g., 'he_normal','glorot_uniform','uniform_scaling'). No default. :type conv_init: str or tf.keras.initializers.Initializer :param activation_conv: Activation function used after convolutional layers (e.g., 'relu'). No default. :type activation_conv: str :param dense_init: Dense layer kernel initializer. No default. :type dense_init: str or tf.keras.initializers.Initializer :param activation_dense: Activation function used in dense layers (e.g., 'relu','tanh'). No default. :type activation_dense: str :param filter1: Number of filters in convolutional layer/block 1; zero disables the layer. No default. :type filter1: int :param filter2: Number of filters in convolutional layer/block 2; zero disables the layer. No default. :type filter2: int :param filter3: Number of filters in convolutional layer/block 3; zero disables the layer. No default. :type filter3: int :param filter4: Number of filters in convolutional layer/block 4; zero disables the layer. No default. :type filter4: int :param filter5: Number of filters in convolutional layer/block 5; zero disables the layer. No default. :type filter5: int :param filter_size_1: Kernel size for convolutional layer/block 1. No default. :type filter_size_1: int :param filter_size_2: Kernel size for convolutional layer/block 2. No default. :type filter_size_2: int :param filter_size_3: Kernel size for convolutional layer/block 3. No default. :type filter_size_3: int :param filter_size_4: Kernel size for convolutional layer/block 4. No default. :type filter_size_4: int :param filter_size_5: Kernel size for convolutional layer/block 5. No default. :type filter_size_5: int :param pooling_1: Pooling mode after layer/block 1; None disables pooling. No default. :type pooling_1: {'max','average','min', None} :param pooling_2: Pooling mode after layer/block 2; None disables pooling. No default. :type pooling_2: {'max','average','min', None} :param pooling_3: Pooling mode after layer/block 3; None disables pooling. No default. :type pooling_3: {'max','average','min', None} :param pooling_4: Pooling mode after layer/block 4; None disables pooling. No default. :type pooling_4: {'max','average','min', None} :param pooling_5: Pooling mode after layer/block 5; None disables pooling. No default. :type pooling_5: {'max','average','min', None} :param pool_size_1: Pool window size after layer/block 1 (if pooling enabled). No default. :type pool_size_1: int :param pool_size_2: Pool window size after layer/block 2 (if pooling enabled). No default. :type pool_size_2: int :param pool_size_3: Pool window size after layer/block 3 (if pooling enabled). No default. :type pool_size_3: int :param pool_size_4: Pool window size after layer/block 4 (if pooling enabled). No default. :type pool_size_4: int :param pool_size_5: Pool window size after layer/block 5 (if pooling enabled). No default. :type pool_size_5: int :param conv_reg: L2 regularization coefficient applied to convolutional kernels. No default. :type conv_reg: float :param dense_reg: L2 regularization coefficient applied to dense kernels. No default. :type dense_reg: float :param dense_neurons_1: Number of units in dense layer 1. No default. :type dense_neurons_1: int :param dense_neurons_2: Number of units in dense layer 2; zero disables the layer. No default. :type dense_neurons_2: int :param dense_neurons_3: Number of units in dense layer 3; zero disables the layer. No default. :type dense_neurons_3: int :param dropout_1: Dropout rate applied after dense layer 1 (0–1). No default. :type dropout_1: float :param dropout_2: Dropout rate applied after dense layer 2 (0–1). No default. :type dropout_2: float :param dropout_3: Dropout rate after dense layer 3 (0–1); may be 'N/A' for models without this layer. No default. :type dropout_3: float or str :param beta_1: Adam/Nadam first-moment decay (β₁). No default. :type beta_1: float :param beta_2: Adam/Nadam second-moment decay (β₂). No default. :type beta_2: float :param amsgrad: Whether to use the AMSGrad variant of Adam. No default. :type amsgrad: bool :param rho: Exponential decay factor for Adadelta/RMSprop. No default. :type rho: float :returns: This function prints to stdout and returns nothing. :rtype: None .. py:function:: format_labels(labels: list) -> list Convert raw parameter keys into human-readable display labels. :param labels: Sequence of raw label strings to format. :type labels: list of str :returns: List of formatted labels (same order and length as input). :rtype: list of str .. rubric:: Notes This function applies a set of explicit replacements; if no rule matches, the label is converted by replacing underscores with spaces and applying title case.