TFHelper Module

Provides helper functions and utilities for working with TensorFlow models.

HMB.TFHelper.MCDropoutPredictions(model, genObj, steps, T=30)[source]

Run T stochastic forward passes with dropout enabled (model called with training=True). Returns a numpy array of shape (noSamples, noClasses, T).

Parameters:

  • model (tensorflow.keras.Model) – Trained model with Dropout layers.

  • genObj (tensorflow.keras.utils.Sequence) – Data generator.

  • steps (int) – Number of steps to cover the subset.

  • T (int) – Number of stochastic forward passes.

Returns:

Array of shape (noSamples, noClasses, T) with all predictions.

Return type:

numpy.ndarray

HMB.TFHelper.ComputeUncertaintyStats(predsAll, eps=1e-12)[source]

Given predsAll of shape (noSamples, noClasses, T), compute uncertainty metrics.

Parameters:

  • predsAll (numpy.ndarray) – Array of shape (noSamples, noClasses, T).

  • eps (float) – Small value to avoid log(0).

Returns:

Dictionary with computed statistics including entropy and mutual information.

Return type:

dict

HMB.TFHelper.SaveTopUncertainImages(testDf, meanProbs, mutualInfo, storePath, labelEncoder, topN=16, imgSize=(128, 128), dpi=720)[source]

Save a grid of the top-N images ranked by mutual information for inspection.

Parameters:

  • testDf (pandas.DataFrame) – DataFrame with test image paths and labels.

  • meanProbs (numpy.ndarray) – Array of shape (noSamples, noClasses) with mean probabilities.

  • mutualInfo (numpy.ndarray) – Array of shape (noSamples,) with mutual information values.

  • storePath (str) – File path to save the resulting figure (e.g., “TopUncertainImages.pdf”).

  • labelEncoder (sklearn.preprocessing.LabelEncoder) – Fitted label encoder.

  • topN (int) – Number of top uncertain images to save.

  • imgSize (tuple) – (height, width) for resizing images.

  • dpi (int) – Dots per inch for saved figure.

HMB.TFHelper.AggregateClasswiseUncertainty(exportDf, meanProbs, mutualInfo)[source]

Return a DataFrame with class-wise mean mutual information and mean confidence.

Parameters:

  • exportDf (pandas.DataFrame) – DataFrame with per-image predictions and uncertainties.

  • meanProbs (numpy.ndarray) – Array of shape (noSamples, noClasses) with mean probabilities.

  • mutualInfo (numpy.ndarray) – Array of shape (noSamples,) with mutual information values.

Returns:

DataFrame with class-wise aggregated uncertainty metrics.

Return type:

pandas.DataFrame

HMB.TFHelper.ComputeEnergyScore(logits)[source]

Compute energy score = -logsumexp(logits) per sample for OOD detection.

Parameters:

logits (numpy.ndarray) – Shape (N, C) logits from model.

Returns:

Shape (N,) energy scores (lower = more in-distribution).

Return type:

numpy.ndarray

HMB.TFHelper.FindGlobalPoolingLayer(model)[source]

Find global pooling layer. First look for standard Keras global pooling layers, then use name heuristics, then fallback to any layer with output rank 2.

Parameters:

model (keras.models.Model) – Keras model object.

Returns:

Keras model object.

Return type:

keras.models.Model

HMB.TFHelper.BuildPretrainedAttentionModel(baseModelString, attentionBlockStr, inputShape, numClasses, optimizer=None, compile=True, pretrained=True, freezeBackbone=True, isSparse=True)[source]

Reconstruct model architecture used in training so weights can be loaded. It supports various backbones and attention blocks, and can be configured for pretrained weights and freezing. It also compiles the model with appropriate loss and optimizer if requested. Furthermore, it prints the total and trainable parameter counts after applying the freeze configuration.

Parameters:

  • baseModelString (str) – backbone model name (e.g. “Xception”).

  • attentionBlockStr (str) – attention block name (e.g. “CBAM”).

  • inputShape (tuple) – input shape used for training (H, W, C).

  • numClasses (int) – number of target classes.

  • optimizer (tensorflow.keras.optimizers.Optimizer or None) – optional optimizer to use; if None, defaults to Adam with lr=1e-4.

  • compile (bool) – whether to compile the model; if False, returns uncompiled model.

  • pretrained (bool) – whether to load pretrained ImageNet weights (True) or initialize randomly (False).

  • freezeBackbone (bool) – whether to freeze the backbone layers (True) or keep them trainable (False).

  • isSparse (bool) – whether to use sparse categorical crossentropy (True) or binary crossentropy (False) for loss.

Returns:

compiled model ready to load weights and predict.

Return type:

model (tensorflow.keras.Model)

HMB.TFHelper.CreateFitPretrainedAttentionModel(trainGenNew, validGenNew, baseModelString, attentionBlockStr, inputShape, numClasses, callbacks, modelCheckpointPath=None, initialEpochs=10, fineTuneEpochs=20, fineTuneAt=100, optimizer=None, storageDir='History', verbose=1)[source]

Create a CNN model with a specified backbone and attention block.

Parameters:

  • trainGenNew (ImageDataGenerator) – Training data generator.

  • validGenNew (ImageDataGenerator) – Validation data generator.

  • baseModelString (str) – Backbone model name (e.g., “Xception”).

  • attentionBlockStr (str) – Attention block name (e.g., “CBAM”).

  • inputShape (tuple) – Input shape for the model.

  • numClasses (int) – Number of output classes.

  • callbacks (list) – List of Keras callbacks for training.

  • modelCheckpointPath (str or None) – Optional path to save the best model; if None, defaults to “BestModel.keras”.

  • initialEpochs (int) – Number of initial training epochs. If 0, skips initial training and goes directly to fine-tuning.

  • fineTuneEpochs (int) – Number of fine-tuning epochs.

  • fineTuneAt (int) – Layer index to start fine-tuning from (default: 100).

  • optimizer (tensorflow.keras.optimizers.Optimizer or None) – Optional optimizer to use; if None, defaults to Adam with lr=1e-3.

  • storageDir (str) – Directory to save the best model and history.

  • verbose (int) – Verbosity level for training (0 = silent, 1 = progress bar, 2 = one line per epoch).

Returns:

The trained Keras model. history (tensorflow.keras.callbacks.History): Training history for initial training. historyFine (tensorflow.keras.callbacks.History): Training history for fine-tuning. configs (dict): Dictionary of training configurations and parameters.

Return type:

model (tensorflow.keras.Model)

Examples

import tensorflow as tf
from HMB.TFHelper import CreateFitPretrainedAttentionModel
from HMB.DatasetsHelper import TFFolderBasedDataPipeline

trainGen = ...  # Create your training data generator.
validGen = ...  # Create your validation data generator.

# OR:
# You can also use TFFolderBasedDataPipeline to create generators from folder structure.
dataDir = "path/to/data"  # Directory with 'train' and 'val' subfolders.
batchSize = 32
imageSize = (256, 256)
# Instantiate the unified data pipeline.
pipeline = TFFolderBasedDataPipeline(
  dataDir=dataDir,
  batchSize=batchSize,
  imageSize=imageSize
)

# Access the training, validation, and test datasets.
trainDataset = pipeline.train
valDataset = pipeline.val
testDataset = pipeline.test

# Map the datasets to extract (x, y) pairs for training and validation.
# Because the pipeline datasets yield (x, y, f) where f is the file path, we map to get just (x, y).
trainGen = pipeline.train.map(lambda x, y, f: (x, y))
validGen = pipeline.val.map(lambda x, y, f: (x, y))

# Determine the number of classes from the pipeline's class names.
numOfClasses = len(pipeline.classNames)

optimizer = tf.keras.optimizers.Adam(learning_rate=1e-4)  # Optional: specify an optimizer.

model, history, historyFine, configs = CreateFitPretrainedAttentionModel(
  trainGenNew=trainGen,
  validGenNew=validGen,
  baseModelString="Xception",
  attentionBlockStr="CBAM",
  inputShape=imageSize + (3,),
  numClasses=numOfClasses,
  callbacks=callbacksList,
  modelCheckpointPath="BestModel.keras",
  initialEpochs=10,
  fineTuneEpochs=20,
  fineTuneAt=100,
  optimizer=optimizer,
  storageDir="History",
  verbose=1
)
HMB.TFHelper.TrainPretrainedAttentionModelFromDataFrame(dataFrame, columnsMap={'categoryEncoded': 'category_encoded', 'imagePath': 'image_path', 'split': 'split'}, labelEncoder=None, imgShape=(512, 512, 3), batchSize=32, baseModelString='Xception', attentionBlockStr='CBAM', initialEpochs=10, fineTuneEpochs=20, augmentationConfigs=None, monitor='val_loss', earlyStoppingPatience=10, ensureCUDA=True, storageDir='History', dpi=720, verbose=1)[source]

Perform training, evaluation, and reporting for the model. This function handles data preparation, model training with callbacks, evaluation on the test set, and saving of results including confusion matrix, classification report, performance metrics, and training history.

Parameters:

  • dataFrame (pandas.DataFrame) – DataFrame containing image paths and labels.

  • columnsMap (dict) – Mapping of required column names in the DataFrame.

  • labelEncoder (sklearn.preprocessing.LabelEncoder or None) – Optional label encoder for encoding string labels to integers; if None, a new LabelEncoder will be created and fitted on the “categoryEncoded” column.

  • imgShape (tuple) – Input shape for the model (height, width, channels).

  • batchSize (int) – Batch size for training and evaluation.

  • baseModelString (str) – Base model architecture (e.g., “Xception”).

  • attentionBlockStr (str) – Attention block type (e.g., “CBAM”).

  • initialEpochs (int) – Number of initial training epochs with the base model frozen.

  • fineTuneEpochs (int) – Number of fine-tuning epochs after unfreezing the base model.

  • augmentationConfigs (dict or None) – Optional dictionary of augmentation parameters for ImageDataGenerator.

  • monitor (str) – Metric to monitor for callbacks (e.g., “val_loss”).

  • earlyStoppingPatience (int) – Number of epochs with no improvement before early stopping.

  • ensureCUDA (bool) – Whether to check for CUDA availability and raise an error if not found.

  • storageDir (str) – Directory where training history and results will be saved.

  • dpi (int) – Dots per inch for saving figures.

  • verbose (int) – Verbosity level for training (0 = silent, 1 = progress bar, 2 = one line per epoch).

HMB.TFHelper.EvaluatePretrainedAttentionModelFromDataFrame(dataFrame, modelPath, columnsMap={'categoryEncoded': 'category_encoded', 'imagePath': 'image_path', 'split': 'split'}, labelEncoder=None, imgShape=(512, 512, 3), batchSize=32, storageDir='History', dpi=720, verbose=1, ensureCUDA=True, T=50)[source]

Evaluate a trained model on the test set and save results.

Parameters:

  • dataFrame (pandas.DataFrame) – DataFrame containing image paths and labels.

  • modelPath (str) – Path to the saved Keras model (.keras file).

  • columnsMap (dict) – Mapping of required column names in the DataFrame.

  • labelEncoder (sklearn.preprocessing.LabelEncoder or None) – Optional label encoder to decode class labels; if None, class labels will be taken from the generator’s class indices.

  • imgShape (tuple) – Input shape for the model (height, width, channels).

  • batchSize (int) – Batch size for evaluation.

  • storageDir (str) – Directory where evaluation results will be saved.

  • dpi (int) – Dots per inch for saving figures.

  • verbose (int) – Verbosity level for evaluation (0 = silent, 1 = progress bar, 2 = one line per epoch).

  • ensureCUDA (bool) – Whether to check for CUDA availability and raise an error if not found.

  • T (int) – Number of stochastic forward passes for MC-dropout uncertainty estimation (if applicable).

HMB.TFHelper.StatisticsPretrainedAttentionModelFromDataFrame(trialResultsPath, statisticsStoragePath, dpi=720, plotMetricsIndividual=False, plotMetricsOverall=False, includeAverageInPlots=False, whichSubset='test')[source]

Analyze the results from multiple trials of inference using a saved preprocessing + model objects bundle with the best parameters from a previous tuning run.

Parameters:

  • trialResultsPath (str) – Path to the directory containing the results of multiple trials.

  • statisticsStoragePath (str) – Directory where the aggregated performance plots and statistics will be saved.

  • dpi (int, optional) – DPI for saving the performance plots. Default is 720.

  • plotMetricsIndividual (bool, optional) – Whether to plot performance metrics for individual trials. Default is False.

  • plotMetricsOverall (bool, optional) – Whether to plot aggregated performance metrics across all trials. Default is False.

  • includeAverageInPlots (bool, optional) – Whether to include the average performance across trials in the plots. Default is False.

  • whichSubset (str, optional) – Which data subset’s results to analyze (e.g., “test”, “val”). Default is “test”.

Returns:

A dictionary containing the aggregated performance metrics and results from all trials.

Return type:

dict

HMB.TFHelper.ImageToViTPatches(image, noOfPatches, patchSize)[source]

Convert an image to flattened patch embeddings suitable for Vision Transformer input. This function takes a preprocessed image, extracts non-overlapping patches of a specified size, and flattens each patch into a vector. The output is a numpy array of shape (noOfPatches, patchSize*patchSize*3) containing the flattened patch embeddings for each image.

Parameters:

  • image (numpy.ndarray) – A preprocessed image array of shape (height, width, channels) that is compatible with the expected input shape of the Vision Transformer model.

  • noOfPatches (int) – The number of patches to extract from the image. This should match the expected number of patches for the Vision Transformer model architecture (e.g., 256 for ViT-Base with 16x16 patches on 224x224 images).

  • patchSize (int) – The size of each square patch (e.g., 16 for 16x16 patches). The function will extract non-overlapping patches of this size from the image.

Returns:

A numpy array of shape (noOfPatches, patchSize*patchSize*3) containing the flattened patch embeddings for each image. Each row corresponds to a patch, and the columns represent the pixel values of the patch flattened into a vector (patchSize*patchSize*3, where 3 is the number of color channels).

Return type:

numpy.ndarray

class HMB.TFHelper.ViTPatchDataGeneratorFromDataFrame(dataFrame, inputShape, batchSize, classMode='categorical', noOfPatches=256, patchSize=16, embedDimension=768, shuffle=False)[source]

Bases: PyDataset

Keras Sequence generator for Vision Transformer training using a pandas DataFrame. This generator loads images from file paths specified in a DataFrame, extracts non-overlapping patches, flattens them to embedding vectors, and yields batches compatible with the VisionTransformer model architecture.

Parameters:

  • dataFrame (pandas.DataFrame) – DataFrame containing at least ‘image_path’ and ‘label’ columns.

  • inputShape (tuple) – Expected input shape of the images (height, width, channels).

  • batchSize (int) – Number of samples per batch.

  • classMode (str) – “categorical” for one-hot encoded labels, “sparse” for integer labels.

  • noOfPatches (int) – Number of patches to extract from each image (default 256).

  • patchSize (int) – Size of each square patch (default 16, resulting in 16x16 patches).

  • embedDimension (int) – Dimension of the flattened patch embeddings (default 768 for ViT-Base).

  • shuffle (bool) – Whether to shuffle the data at the end of each epoch (default False).

Returns:

  • images: A numpy array of shape (batchSize, noOfPatches, embedDimension) containing the flattened patch embeddings for each image in the batch.

  • labels: A numpy array of shape (batchSize, numClasses) for “categorical” classMode or (batchSize, 1) for “sparse” classMode containing the corresponding labels for each image in the batch.

Return type:

A batch of data in the form (images, labels) where

__len__()[source]

Return number of batches per epoch.

__getitem__(index)[source]

Generate one batch of data.

Parameters:

index (int) – Index of the batch to generate.

on_epoch_end()[source]

Callback invoked at the end of each epoch for shuffling.

get_class_indices()[source]

Return the mapping from class names to integer indices.

class HMB.TFHelper.ViTPatchDataGeneratorFromFolder(folder, inputShape, batchSize, classMode='categorical', noOfPatches=256, patchSize=16, embedDimension=768, shuffle=False)[source]

Bases: PyDataset

Keras Sequence generator for Vision Transformer training using images from a folder structure. This generator loads images from a specified folder structure, extracts non-overlapping patches, flattens them to embedding vectors, and yields batches compatible with the VisionTransformer model architecture.

Initialize the data generator with the specified parameters.

Parameters:

  • folder (str) – Path to the root folder containing subfolders for each class, with images inside those subfolders.

  • inputShape (tuple) – Expected input shape of the images (height, width, channels).

  • batchSize (int) – Number of samples per batch.

  • classMode (str) – “categorical” for one-hot encoded labels, “sparse” for integer labels.

  • noOfPatches (int) – Number of patches to extract from each image (default 256).

  • patchSize (int) – Size of each square patch (default 16, resulting in 16x16 patches).

  • embedDimension (int) – Dimension of the flattened patch embeddings (default 768 for ViT-Base).

  • shuffle (bool) – Whether to shuffle the data at the end of each epoch (default False).

__init__(folder, inputShape, batchSize, classMode='categorical', noOfPatches=256, patchSize=16, embedDimension=768, shuffle=False)[source]

Initialize the data generator with the specified parameters.

Parameters:

  • folder (str) – Path to the root folder containing subfolders for each class, with images inside those subfolders.

  • inputShape (tuple) – Expected input shape of the images (height, width, channels).

  • batchSize (int) – Number of samples per batch.

  • classMode (str) – “categorical” for one-hot encoded labels, “sparse” for integer labels.

  • noOfPatches (int) – Number of patches to extract from each image (default 256).

  • patchSize (int) – Size of each square patch (default 16, resulting in 16x16 patches).

  • embedDimension (int) – Dimension of the flattened patch embeddings (default 768 for ViT-Base).

  • shuffle (bool) – Whether to shuffle the data at the end of each epoch (default False).

__getitem__(index)[source]

Generate one batch of data.

Parameters:

index (int) – Index of the batch to generate.

Returns:

A tuple (images, labels) where:

  • images: A numpy array of shape (batchSize, noOfPatches, embedDimension) containing the flattened patch embeddings for each image in the batch.

  • labels: A numpy array of shape (batchSize, numClasses) for “categorical” classMode or (batchSize, 1) for “sparse” classMode containing the corresponding labels for each image in the batch.

Return type:

tuple

on_epoch_end()[source]

Method called at the end of every epoch.

HMB.TFHelper.Conv2DBlock(inputLayer, filters, kernelSize=3, padding='same', strides=(1, 1), kernelInitializer='he_normal', activation='relu', applyBatchNorm=False, applyActivation=True)[source]

Shorthand helper to apply a Conv2D followed optionally by BatchNormalization and Activation.

Parameters:

  • inputLayer (tensorflow.keras.layers.Layer) – Input Keras tensor to the convolutional block.

  • filters (int) – Number of convolution filters.

  • kernelSize (int or tuple) – Convolution kernel size.

  • padding (str) – Padding mode, e.g. “same” or “valid”.

  • strides (tuple) – Stride of the convolution.

  • kernelInitializer (str) – Kernel initializer name.

  • activation (str or callable) – Activation to apply if applyActivation is True.

  • applyBatchNorm (bool) – If True, apply BatchNormalization after convolution.

  • applyActivation (bool) – If True, apply the activation after (optional) BatchNorm.

Returns:

Output Keras tensor after applying the convolutional block with the specified options.

Return type:

tensorflow.keras.layers.Layer

HMB.TFHelper.DropoutBlock(inputLayer, dropoutRatio, dropoutType='spatial')[source]

Apply either spatial or standard dropout according to the requested type.

Parameters:

  • inputLayer (tensorflow.keras.layers.Layer) – Input Keras tensor to the dropout block.

  • dropoutRatio (float) – Drop probability in (0, 1]. If 0.0 returns input unchanged.

  • dropoutType (str) – One of {“spatial”, “feature”}. “spatial” -> SpatialDropout2D, “feature” -> Dropout.

Returns:

Output Keras tensor after applying the specified dropout. If dropoutRatio is 0.0, returns inputLayer unchanged.

Return type:

tensorflow.keras.layers.Layer

HMB.TFHelper.DownSamplingBlock(inputLayer, filters, kernelSize=3, padding='same', kernelInitializer='he_normal', downsmaplingType='maxpooling')[source]

Generic downsampling block supporting different strategies.

Parameters:

  • inputLayer (tensorflow.keras.layers.Layer) – input to the downsampling block.

  • filters (int) – Number of filters for conv variants (ignored for max-pooling path).

  • kernelSize (int or tuple) – Kernel size for convolutional options.

  • padding (str) – Padding mode for conv variants.

  • kernelInitializer (str) – Kernel initializer for conv variants.

  • downsmaplingType (str) – One of {“maxpooling”, “stridedconvolution”, “dilatedconvolution”}.

Returns:

Keras tensor after applying the requested downsampling operation.

Return type:

tensorflow.keras.layers.Layer

class HMB.TFHelper.SubpixelConv2D(*args, **kwargs)[source]

Bases: Layer

Keras Layer implementing sub-pixel convolution upsampling via depth_to_space.

This layer expects the incoming channel dimension to be divisible by scale^2 and performs TensorFlow’s depth_to_space to rearrange depth into spatial dimensions.

Parameters:

scale (int) – Upscaling factor (e.g. 2).

Notes

The layer is registered in Keras custom objects for model (de)serialization.

Initialize the SubpixelConv2D layer.

Parameters:

  • scale (int) – Upscaling factor (default 2).

  • **kwargs – Additional keyword arguments for the base Layer class.

__init__(scale=2, **kwargs)[source]

Initialize the SubpixelConv2D layer.

Parameters:

  • scale (int) – Upscaling factor (default 2).

  • **kwargs – Additional keyword arguments for the base Layer class.

call(inputs)[source]

Forward pass of the SubpixelConv2D layer. See https://arxiv.org/abs/1609.05158 for details on sub-pixel convolution.

Parameters:

inputs (tf.Tensor) – Input tensor of shape (batch, height, width, channels).

Returns:

Output tensor after applying depth_to_space, with shape (batch, height*scale, width*scale, channels/(scale^2)).

Return type:

tensorflow.Tensor

compute_output_shape(inputShape)[source]

Compute the output shape of the SubpixelConv2D layer based on the input shape and the scaling factor.

Parameters:

inputShape (tuple) – Shape of the input tensor (batch, height, width, channels).

Returns:

Output shape after applying depth_to_space, with shape (batch, height*scale, width*scale, channels/(scale^2)).

Return type:

tuple

get_config()[source]

Return the configuration of the SubpixelConv2D layer for serialization.

Returns:

Configuration dictionary containing the scale factor and any additional parameters from the base Layer class.

Return type:

dict

HMB.TFHelper.UpSamplingBlock(inputLayer, filters, kernelSize=3, padding='same', kernelInitializer='he_normal', upsamplingType='upsampling', activation='relu', strides=(2, 2))[source]

Flexible upsampling block supporting standard Upsampling2D + Conv, Conv2DTranspose, or Subpixel conv.

Parameters:

  • inputLayer (tensorflow.keras.layers.Layer) – input to the upsampling block.

  • filters (int) – Number of filters for conv outputs (for subpixel, filters*4 is used before depth_to_space).

  • kernelSize (int or tuple) – Kernel size for convolutional layers.

  • padding (str) – Padding mode for conv variants.

  • kernelInitializer (str) – Kernel initializer name.

  • upsamplingType (str) – One of {“upsampling”, “transposedconvolution”, “subpixelconvolution”}.

  • activation (str or callable) – Activation applied in certain branches.

  • strides (tuple) – Strides for Conv2DTranspose when used.

Returns:

Keras tensor after applying the requested upsampling operation.

Return type:

tensorflow.keras.layers.Layer

HMB.TFHelper.AttentionLayer(input1, input2, filters, kernelSize=1, strides=(1, 1), padding='same', kernelInitializer='he_normal')[source]

Lightweight attention gating layer inspired by attention U-Net style blocks.

This block computes a gating mask between two inputs (e.g., encoder skip and decoder feature maps) by convolving both to a common number of filters, summing, applying ReLU then a 1-channel sigmoid to produce an attention map which is multiplied with input1.

Parameters:

  • input1 (tensorflow.keras.layers.Layer) – the tensor to be gated (e.g., skip connection features).

  • input2 (tensorflow.keras.layers.Layer) – the gating tensor (e.g., decoder features).

  • filters (int) – Number of filters used internally when projecting inputs to the same space.

  • kernelSize (int) – Kernel size for internal convolutions.

  • strides (tuple) – Stride for internal convolutions.

  • padding (str) – Padding mode for internal convolutions.

  • kernelInitializer (str) – Kernel initializer for internal convolutions.

Returns:

The result of applying the attention gating to input1, where input1 is multiplied by the attention mask computed from both inputs. The output has the same shape as input1 but with its features modulated by the attention mechanism.

Return type:

tensorflow.keras.layers.Layer

HMB.TFHelper.AttentionConcatenate(convLayer, skipConnection)[source]

Apply attention gating to the skipConnection and concatenate the gated features with convLayer.

Parameters:

  • convLayer (tensorflow.keras.layers.Layer) – the decoder/upsampled features.

  • skipConnection (tensorflow.keras.layers.Layer) – encoder skip connection to be gated and concatenated.

Returns:

The result of concatenating convLayer with the attention-gated version of skipConnection. This allows the model to focus on relevant features from the skip connection when merging with the decoder features.

Return type:

tensorflow.keras.layers.Layer

HMB.TFHelper.ConcatenateBlock(inputLayer, forwardLayer, concatenateType='concatenate')[source]

Concatenate helper that supports plain concatenation or attention-based concatenation.

Parameters:

  • inputLayer (tensorflow.keras.layers.Layer) – typically the upsampled/decoder features.

  • forwardLayer (tensorflow.keras.layers.Layer) – the skip/encoder features to merge.

  • concatenateType (str) – “concatenate” or “attention”.

Returns:

The result of merging inputLayer and forwardLayer using the specified concatenation strategy. If “concatenate”, it performs a simple concatenation along the channel axis. If “attention”, it applies attention gating to forwardLayer before concatenating with inputLayer, allowing the model to focus on relevant features from the skip connection.

Return type:

tensorflow.keras.layers.Layer

HMB.TFHelper.DownResidualBlock(inputLayer, stage=1, activation='relu', applyActivation=True, dropoutRatio=0.0, dropoutType='spatial', applyBatchNorm=True, kernelInitializer='he_normal')[source]

Residual block for the encoder (downsampling) path.

The block applies a small stack of convolutional layers (number controlled by stage), adds a residual connection to the input, optionally applies activation and dropout, then performs a downsampling convolution to reduce spatial resolution and increase filters.

Parameters:

  • inputLayer (tensorflow.keras.layers.Layer) – input to the residual block.

  • stage (int) – Controls number of internal convolutional layers and base filter count (16 * 2^(stage-1)).

  • activation (str or callable) – Activation function to use.

  • applyActivation (bool) – Whether to apply activation after the residual addition.

  • dropoutRatio (float) – Dropout rate applied after residual addition (0.0 disables dropout).

  • dropoutType (str) – “spatial” or “feature”: type of dropout used when dropoutRatio > 0.

  • applyBatchNorm (bool) – Whether to use BatchNormalization in each conv block.

  • kernelInitializer (str) – Kernel initializer name for conv layers.

Returns:

(downsampledOutput, outputBeforeDownSampling)

  • downsampledOutput: Keras tensor after residual + downsampling conv.

  • outputBeforeDownSampling: Keras tensor of the residual output prior to downsampling (for skip connections).

Return type:

tuple

HMB.TFHelper.UpResidualBlock(inputLayer, forwardLayer, stage=1, activation='relu', applyActivation=True, applyBatchNorm=True, kernelInitializer='he_normal', concatenateType='concatenate')[source]

Residual block for the decoder (upsampling) path.

The block merges the upsampled tensor with a skip connection (either plain concat or attention), applies a small stack of convolutions, adds a residual connection to the upsampled input, and optionally upsamples when stages > 1.

Parameters:

  • inputLayer (tensorflow.keras.layers.Layer) – the decoder/upsampled features.

  • forwardLayer (tensorflow.keras.layers.Layer) – encoder skip connection to be merged.

  • stage (int) – Controls number of internal convolutional layers and base filter count.

  • activation (str or callable) – Activation function to use.

  • applyActivation (bool) – Whether to apply activation after residual addition.

  • applyBatchNorm (bool) – Whether to use BatchNormalization after ConvTranspose/Upsampling.

  • kernelInitializer (str) – Kernel initializer for conv layers.

  • concatenateType (str) – “concatenate” or “attention” for merging.

Returns:

Keras tensor after applying the up residual block, which includes merging with the skip connection, convolutional processing, and optional upsampling. The output has enhanced features due to the residual connection and the merged skip features, and is ready for further processing in the decoder path.

Return type:

tensorflow.keras.layers.Layer

HMB.TFHelper.BuildOptimizer(optimizerSpec)[source]

Build a Keras optimizer instance from a flexible specification.

Parameters:

optimizerSpec – Can be one of the following: - An instance of a Keras optimizer (e.g., tensorflow.keras.optimizers.Adam()). A fresh instance will be created from its config. - A tuple of (optimizerClass, optimizerKwargs) where optimizerClass is a Keras optimizer class and optimizerKwargs is a dict of keyword arguments to instantiate it. - A Keras optimizer class (e.g., tensorflow.keras.optimizers.Adam) which will be instantiated with default parameters. - A callable that returns an instance of a Keras optimizer when called with no arguments.

Returns:

A new instance of the specified Keras optimizer.

Return type:

tensorflow.keras.optimizers.Optimizer

HMB.TFHelper.TFDataset(X, y, batchSize=8)[source]

Create a TensorFlow dataset from the given data and batch size, with shuffling, parsing, batching, prefetching, and repeating.

Parameters:

  • X (list or array-like) – List of input data (e.g., image paths).

  • y (list or array-like) – List of corresponding labels or masks.

  • batchSize (int) – Number of samples per batch.

Returns:

A TensorFlow dataset that yields batches of parsed data, shuffled and prefetched for optimized training. The dataset is set to repeat indefinitely, so it can be used directly in model training loops without needing to specify the number of epochs in the dataset itself.

Return type:

tensorflow.data.Dataset

HMB.TFHelper.CompileTrainTFUNetModel(model, trialNo, inputSize, imagesList, masksList, hyperparameters, pretrainedWeights=None, epochs=25, outputFolder=None, keyword=None, testSize=0.25, randomState=42, metrics=['accuracy'])[source]

Compile and train a TFUNet model with the given parameters, and store the results.

Parameters:

  • model (tensorflow.keras.Model) – The TFUNet model instance to be trained.

  • trialNo (int) – The trial number for this training run, used for organizing outputs.

  • inputSize (tuple) – The expected input size of the model (height, width, channels).

  • imagesList (str) – Path to the directory containing input images.

  • masksList (str) – Path to the directory containing corresponding segmentation masks.

  • hyperparameters (dict) – A dictionary of hyperparameters for training (e.g., optimizer, loss, batchSize).

  • pretrainedWeights (str, optional) – Path to pretrained weights to initialize the model, if any.

  • epochs (int) – Number of epochs to train the model.

  • outputFolder (str) – Path to the folder where training outputs (weights, logs, hyperparameters) will be stored.

  • keyword (str) – A keyword to uniquely identify this training run, used in naming output files and directories.

  • testSize (float) – Ratio of the dataset to be used as the test set when splitting the data. The remaining will be used for training and validation.

  • randomState (int) – Random state for reproducibility when splitting the dataset.

  • metrics (list) – List of metrics to evaluate during training and validation.