biapy.engine.metrics

Metrics and loss functions for BiaPy.

This module provides a variety of metrics and loss functions for evaluating and training deep learning models in BiaPy. It includes implementations for Jaccard index (IoU), Dice loss, BCE, Cross-Entropy, contrastive losses, instance segmentation losses, detection metrics, and wrappers for SSIM, MSE, and MAE-based losses. Both PyTorch and NumPy-based metrics are supported for 2D and 3D biomedical image analysis.

biapy.engine.metrics.jaccard_index_numpy(y_true, y_pred)

Compute the Jaccard index (Intersection over Union) between ground truth and prediction.

Parameters:

• y_true (N dim Numpy array) – Ground truth masks. E.g. (num_of_images, x, y, channels) for 2D images or (volume_number, z, x, y, channels) for 3D volumes.

• y_pred (N dim Numpy array) – Predicted masks. E.g. (num_of_images, x, y, channels) for 2D images or (volume_number, z, x, y, channels) for 3D volumes.

Returns:

jac – Jaccard index value.

Return type:

float

biapy.engine.metrics.jaccard_index_numpy_without_background(y_true, y_pred)

Compute Jaccard index excluding the background class (first channel).

Parameters:

• y_true (N dim Numpy array) – Ground truth masks. E.g. (num_of_images, x, y, channels) for 2D images or (volume_number, z, x, y, channels) for 3D volumes.

• y_pred (N dim Numpy array) – Predicted masks. E.g. (num_of_images, x, y, channels) for 2D images or (volume_number, z, x, y, channels) for 3D volumes.

Returns:

jac – Jaccard index value.

Return type:

float

biapy.engine.metrics.weight_binary_ratio(target)

Compute a weight map to balance foreground and background pixels.

Parameters:

target (torch.Tensor) – Target tensor.

Returns:

weight – Weight map.

Return type:

torch.Tensor

class biapy.engine.metrics.jaccard_index(num_classes: int, device: device, t: float = 0.5, model_source: str = 'biapy', ndim: int = 2, ignore_index: int = -1)

Bases: object

Jaccard index (IoU) metric for PyTorch tensors.

Supports binary and multiclass segmentation, with optional thresholding and ignore index.

class biapy.engine.metrics.multiple_metrics(num_classes: int, metric_names: List[str], device: device, out_channels: List[str] | None = ['F'], channel_extra_opts: Dict | None = {}, ignore_index: int = -1, model_source: str = 'biapy', ndim: int = 2)

Bases: object

Compute multiple metrics for instance segmentation workflows.

Supports IoU, L1, and other metrics for multi-head or multi-channel outputs.

biapy.engine.metrics.scale_target(targets_: Tensor, scaled_size: Tuple[int, ...]) → Tensor

Scale the target masks to match the size of the predictions.

Parameters:

• targets_ (torch.Tensor) – Ground truth masks.

• scaled_size (tuple) – Size to scale the masks to.

Returns:

targets – Scaled ground truth masks.

Return type:

torch.Tensor

class biapy.engine.metrics.loss_encapsulation(loss)

Bases: Module

Just a wrapper to any other common loss deataching the prediction from the dict given by the model.

forward(inputs, targets)

Forward pass for the encapsulated loss.

Parameters:

• inputs (torch.Tensor or dict) – Model predictions. If a dict, expects the prediction under the “pred” key.

• targets (torch.Tensor) – Ground truth targets.

Returns:

loss – Computed loss value.

Return type:

torch.Tensor

class biapy.engine.metrics.CrossEntropyLoss_wrapper(num_classes: int, ndim: int = 2, class_rebalance: str = 'none', class_weights: List[float] = [], ignore_index: int = -1, device=None)

Bases: object

Wrapper for PyTorch’s CrossEntropyLoss and BCEWithLogitsLoss with support for class rebalancing.

class biapy.engine.metrics.detection_loss(ndim: int = 2, class_rebalance_within_channels: bool = True, separated_class_channel: bool = False, channel_weights=(1, 1), class_rebalance: str = 'none', class_weights: List[float] = [], ignore_index: int = -1, device=None)

Bases: object

Loss for detection models with separated_class_channel. Combines BCE for the foreground and CrossEntropy for the class channel, with optional class rebalancing and channel weighting.

class biapy.engine.metrics.DiceLoss(batch_dice: bool = True, smooth: float = 1e-05)

Bases: Module

forward(y_pred, y_true)

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

class biapy.engine.metrics.DiceCELoss(num_classes: int, ndim: int = 2, separated_class_channel: bool = False, batch_dice: bool = True, smooth: float = 1e-05, model_source: str = 'biapy', class_rebalance: str = 'none', class_weights: List[float] = [], channel_weights: Tuple[float, float] = (1.0, 1.0), w_ce: float = 1.0, w_dice: float = 1.0, ignore_index: int = -1, device=None)

Bases: Module

Combines Cross Entropy (or Binary Cross Entropy) and Dice Loss. Supports multi-head (separated_class_channel), deep supervision lists, class rebalancing, and channel weighting.

forward(y_pred: Tensor | dict | List, y_true: Tensor) → Tensor

Calculates Dice + CE Loss mimicking CrossEntropyLoss_wrapper structure.

Parameters:

• y_pred (torch.Tensor, dict, or list of Tensors) – Model predictions. Can be a single tensor, a dict with “pred” and optionally ” class” keys, or a list of tensors for deep supervision.

• y_true (torch.Tensor) – Ground truth masks.

Returns:

loss – Combined Dice + CE loss value.

Return type:

torch.Tensor

class biapy.engine.metrics.ContrastCELoss(main_loss: Module, ndim: int = 2, weight: float = 1.0, ignore_index: int = -1)

Bases: Module

Contrastive Cross Entropy Loss for semantic segmentation tasks. It mixes the main loss function and the constrastive loss.

Parameters:

• main_loss (nn.Module) – The main loss function to be used for the segmentation task.

• ndim (int, optional) – Number of dimensions of the input data. 2 for 2D images, 3 for 3D volumes. Default is 2.

• weight (float, optional) – Weight for the contrastive loss. Default is 1.0. This weight is used to balance the contribution of the contrastive loss in the final loss calculation and can be adjusted based on the specific requirements of the task.

• ignore_index (int, optional) – Label to ignore in the loss calculation. Default is -1.

forward(preds, target, with_embed=False)

Forward pass of the Contrastive Cross Entropy Loss.

Parameters:

• preds (dict) – Dictionary containing the predictions from the model. It should contain: - “pred”: Segmentation predictions. - “embed”: Embedding predictions. - “segment_queue”: Segment queues for contrastive learning. - “pixel_queue”: Pixel queues for contrastive learning.

• target (torch.Tensor) – Ground truth segmentation masks.

• with_embed (bool, optional) – Whether to include the embedding in the loss calculation. Default is False.

class biapy.engine.metrics.PixelContrastLoss(temperature: float = 0.07, base_temperature: float = 0.07, ignore_index: int = -1, max_samples: int = 1024, max_views: int = 1, ndim: int = 2)

Bases: Module

Pixel Contrastive Loss for semantic segmentation tasks.

Supports hard anchor sampling and negative sampling for contrastive learning.

forward(feats: Tensor, labels: Tensor, predict: Tensor, queue: Tensor | None = None)

Forward pass of the Pixel Contrastive Loss.

Parameters:

• feats (torch.Tensor) – Input features of shape (batch_size, feat_size, H, W) or (batch_size, feat_size, D, H, W). E.g. (2, 256, 128, 256) for a batch size of 2, 256 features and a spatial size of 128x256.

• labels (torch.Tensor) – Ground truth labels of shape (batch_size, C, H, W) or (batch_size, C, D, H, W). E.g. (2, 1, 128, 256) for a batch size of 2, 1 channel and a spatial size of 128x256.

• predict (torch.Tensor) – Predicted labels of shape (batch_size, H, W) or (batch_size, D, H, W). E.g. (2, 128, 256) for a batch size of 2 and a spatial size of 128x256.

• queue (torch.Tensor, optional) – Queue of negative examples of shape (class_num, cache_size, feat_size). E.g. (2, 60, 256) for 2 classes, 60 samples per class and 256 features. If not provided, the contrastive loss will be calculated using the anchor features only.

Returns:

loss – Contrastive loss value.

Return type:

torch.Tensor

class biapy.engine.metrics.instance_segmentation_loss(channel_weights=(1, 1), ndim: int = 2, class_rebalance_within_channels: bool = False, separated_class_channel: bool = False, out_channels=['F', 'C'], losses_to_use=[], channel_extra_opts={}, gt_channels_expected: int = 1, class_rebalance: str = 'none', class_weights: List[float] = [], ignore_index: int = -1, device=None)

Bases: object

Custom loss for instance segmentation tasks in BiaPy.

This loss combines different loss functions (e.g., BCE, L1, CrossEntropy) for multiple output channels, such as binary masks, contours, distances, and class channels. It supports class rebalancing, masking of distance channels, and different instance segmentation output types (e.g., “regular”, “synapses”). The loss is configurable for various output channel combinations and can handle multi-class and multi-head settings.

Parameters:

• channel_weights (tuple of float, optional) – Weights to be applied to each output channel loss. E.g. (1, 0.2).

• out_channels (List of str, optional) – String specifying the output channels (e.g., [“F”, “C”], [“B”, “C”, “P”], [“B”,”C”,”D”], etc.).

• losses_to_use (list of str, optional) – List of loss functions to use for each output channel (e.g., [“BCE”, “MSE”]).

• channel_extra_opts (dict, optional) – Additional options for each output channel (e.g., {“D”: {“mask_values”: True}}).

• gt_channels_expected (int, optional) – Number of channels expected in the ground truth (default: 1).

• class_rebalance (str, optional) – Whether to reweight classes (inside loss function) or not. Options are: “none” and “auto”.

• class_weights (List[float], optional) – Weights for each class to be used in the loss calculation (default: None).

• ignore_index (int, optional) – Value to ignore in the loss calculation (default: -1).

biapy.engine.metrics.detection_metrics(true_points, pred_points, true_classes=None, pred_classes=None, tolerance=10, resolution: List[float | int] = [1, 1, 1], bbox_to_consider=[], verbose=False) → Tuple[Dict[str, float], DataFrame, DataFrame]

Calculate detection metrics (precision, recall, F1) for point-based object detection.

Parameters:

• true_points (List of list) – List containing coordinates of ground truth points. E.g. [[5,3,2], [4,6,7]].

• pred_points (4D Tensor) – List containing coordinates of predicted points. E.g. [[5,3,2], [4,6,7]].

• true_classes (List of ints, optional) – Classes of each ground truth points.

• pred_classes (List of ints, optional) – Classes of each predicted points.

• tolerance (optional, int) – Maximum distance far away from a GT point to consider a point as a true positive.

• resolution (List of int/float) – Weights to be multiply by each axis. Useful when dealing with anysotropic data to reduce the distance value on the axis with less resolution. E.g. (1,1,0.5).

• bbox_to_consider (List of tuple/list, optional) – To not take into account during metric calculation to those points outside the bounding box defined with this variable. Order is: [[z_min, z_max], [y_min, y_max], [x_min, x_max]]. For example, using an image of 10x100x200 to not take into account points on the first/last slices and with a border of 15 pixel for x and y axes, this variable could be defined as follows: [[1, 9], [15, 85], [15, 185]].

• verbose (bool, optional) – To print extra information.

Returns:

metrics – List containing precision, accuracy and F1 between the predicted points and ground truth.

Return type:

List of strings

class biapy.engine.metrics.SSIM_loss(data_range, device)

Bases: Module

SSIM loss using torchmetrics StructuralSimilarityIndexMeasure.

forward(input, target)

Compute the SSIM loss.

Parameters:

• input (torch.Tensor or dict) – Predicted images. If a dict, expects the prediction under the “pred” key.

• target (torch.Tensor) – Ground truth images.

Returns:

loss – 1 minus the SSIM value (so that lower is better).

Return type:

torch.Tensor

class biapy.engine.metrics.W_MAE_SSIM_loss(data_range, device, w_mae=0.5, w_ssim=0.5)

Bases: Module

Weighted combination of MAE and SSIM loss.

This loss combines Mean Absolute Error (MAE) and Structural Similarity Index Measure (SSIM) for image regression tasks, allowing the user to balance pixel-wise and perceptual similarity.

forward(input, target)

Compute the weighted sum of MAE and SSIM loss.

Parameters:

• input (torch.Tensor or dict) – Predicted images. If a dict, expects the prediction under the “pred” key.

• target (torch.Tensor) – Ground truth images.

Returns:

loss – Weighted sum of MAE and (1 - SSIM) loss.

Return type:

torch.Tensor

class biapy.engine.metrics.W_MSE_SSIM_loss(data_range, device, w_mse=0.5, w_ssim=0.5)

Bases: Module

Weighted combination of MSE and SSIM loss.

This loss combines Mean Squared Error (MSE) and Structural Similarity Index Measure (SSIM) for image regression tasks, allowing the user to balance pixel-wise and perceptual similarity.

forward(input, target)

Compute the weighted sum of MSE and SSIM loss.

Parameters:

• input (torch.Tensor or dict) – Predicted images. If a dict, expects the prediction under the “pred” key.

• target (torch.Tensor) – Ground truth images.

Returns:

loss – Weighted sum of MSE and (1 - SSIM) loss.

Return type:

torch.Tensor

biapy.engine.metrics.n2v_loss_mse(y_pred, y_true)

Noise2Void MSE loss for self-supervised denoising.

Parameters:

• y_pred (torch.Tensor or dict) – Predicted output.

• y_true (torch.Tensor) – Ground truth and mask.

Returns:

loss – Loss value.

Return type:

torch.Tensor

class biapy.engine.metrics.SSIM_wrapper

Bases: object

Wrapper for SSIM loss using pytorch_msssim.

biapy.engine.metrics.lovasz_hinge(logits: Tensor, labels: Tensor, per_image: bool = True, ignore_index: int | None = None) → Tensor

Single-function binary Lovász hinge loss. - logits: unnormalized scores, same shape as labels (e.g. (1,H,W) or (1,D,H,W)) - labels: {0,1} or bool tensor, same shape as logits - per_image: average loss per-item if a batch dim exists - ignore_index: label value to ignore (optional)

class biapy.engine.metrics.SpatialEmbLoss(patch_size: List[int] = [32, 1024, 1024], anisotropy: List[float | int] = [1, 1, 1], ndims: int = 2, center_mode: str = 'centroid', medoid_max_points: int | None = 10000, channel_weights: List[float] = [1.0, 1.0, 1.0])

Bases: Module

Spatial Embedding Loss for 2D and 3D inspired by EmbedSeg.

Parameters:

• patch_size (List of int, optional) – Patch size used during training (used to build coordinate map buffer).

• anisotropy (List of float or int, optional) – Anisotropy factors for each axis (z,y,x).

• ndims (int, optional) – Number of spatial dimensions (2 or 3).

• center_mode (str, optional) – Method to compute object center: “centroid” or “medoid”.

• medoid_max_points (int, optional) – Maximum number of points to use when computing medoid (to avoid O(N^2) complexity).

• channel_weights (List of float, optional) – Weights for the different loss components: [foreground, instance, variance, seed].

forward(prediction: Tensor, instances: Tensor) → Tuple[Tensor, float, str]

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.