metrics Module

The metrics module provides tools for evaluating model performance, such as metrics computation.

class ucs.utils.metrics.CeDiceLoss(num_classes, alpha=0.7, weights=None, ignore_index=None, reduction='mean')

Bases: Module

A combined loss function that incorporates Cross-Entropy Loss (CE) and Dice Loss for semantic segmentation tasks. The CE loss accounts for class imbalance, while the Dice loss measures the overlap between predicted and ground truth masks, providing a robust metric for segmentation accuracy.

Parameters:

• num_classes (int) – The total number of classes in the segmentation task.

• alpha (float, optional) – Weight for Cross-Entropy Loss in the combined loss. Default is 0.8.

• beta (float, optional) – Weight for Dice Loss in the combined loss. Default is 0.2.

• weights (list, ndarray, Tensor, optional) – Class weights for handling imbalanced datasets. If provided, it must match the number of classes.

• ignore_index (int, optional) – Class index to ignore during loss computation. Pixels with this index are excluded from both CE and Dice loss calculations. Default is None.

• reduction (str, optional) – Specifies the reduction to apply to the output of the CE loss. Must be one of “none”, “mean” (default), or “sum”.

Variables:

• alpha (float) – Weight for the CE loss component.

• beta (float) – Weight for the Dice loss component.

• num_classes (int) – Number of classes in the segmentation task.

• ignore_index (int or None) – Class index to ignore during loss computation.

• weights (Tensor or None) – Tensor containing class weights for CE loss.

• ce_loss (CrossEntropyLoss) – Cross-Entropy loss module.

• dice_loss (Dice) – Dice loss for multi-class segmentation.

forward(inputs, targets)

Forward pass of the loss computation that combines Cross-Entropy loss and Dice loss.

This method computes the total loss by combining the Cross-Entropy loss (CE loss) and Dice loss. The Cross-Entropy loss is calculated using the inputs and targets, while the Dice loss is calculated by first applying a softmax function to the inputs to get the predicted probabilities. The Dice loss is computed by comparing the predicted probabilities with the target labels.

The total loss is a weighted sum of the CE loss and Dice loss, with the weights specified by the alpha and beta parameters.

Parameters:

• inputs (Tensor) – The model’s raw output logits (before softmax). Shape: (batch_size, num_classes, height, width) for 2D inputs.

• targets (Tensor) – The ground truth labels for comparison. Shape: (batch_size, height, width) for 2D inputs.

Returns:

The weighted sum of the Cross-Entropy loss and Dice loss.

A scalar value representing the total loss.

Return type:

Tensor

initialize_weights(weights, num_classes)

Initialize and validate weights for a loss function.

Parameters:

• weights (list, ndarray, Tensor, optional) – Weighting factor(s) for each class.

• num_classes (int) – The total number of classes for the loss function.

Returns:

A tensor of weights for all classes.

Return type:

Tensor

Raises:

• LossWeightsTypeError – If the weights argument is of an unsupported type.

• LossWeightsSizeError – If the size of weights does not match num_classes.

set_stage(alpha, beta)

class ucs.utils.metrics.DiceLoss(ignore_index=None, smooth=1e-06)

Bases: Module

forward(inputs, targets)

Parameters:

• inputs – Tensor of shape (B, C, H, W), probabilities

• target – Tensor of shape (B, H, W), class indices

class ucs.utils.metrics.FocalLoss(num_classes, gamma=2.0, alpha=None, ignore_index=None, reduction='mean')

Bases: CrossEntropyLoss

Focal Loss for addressing class imbalance in classification tasks.

Parameters:

• num_classes (int) – Number of classes.

• gamma (float, optional) – Focusing parameter. Defaults to 2.0.

• alpha (float, list, ndarray, Tensor, optional) – Weighting factor for each class. Defaults to None.

• ignore_index (int, optional) – Specifies a target value that is ignored. Defaults to None.

• reduction (str, optional) – Specifies the reduction to apply to the output. Defaults to ‘mean’.

forward(inputs, target)

Forward pass of the loss calculation.

Parameters:

• inputs (Tensor) – Predicted logits of shape (N, C, H, W) where C is the number of classes

• target (Tensor) – Ground truth labels of shape (N, H, W)

Returns:

Computed loss

Return type:

Tensor

class ucs.utils.metrics.SegMetrics(num_classes, device='cpu', ignore_index=None)

Bases: MetricCollection

A utility class to handle metrics for segmentation tasks. Provides functionality for IoU (Jaccard Index) and Dice coefficient calculation.

Parameters:

• num_classes (int) – Number of classes in the segmentation task.

• device (str, optional) – Device to run the metrics on. Default is “cpu”.

• ignore_index (int, optional) – Specifies a target value that is ignored and does not contribute to the inputs gradient. Default is None.

Variables:

• num_classes (int) – The number of classes.

• ignore_index (int) – The index to ignore in the target.

• metrics (dict) – Dictionary of metrics to compute.

update(predicted, targets)

Call update for each metric sequentially.

Positional arguments (args) will be passed to every metric in the collection, while keyword arguments (kwargs) will be filtered based on the signature of the individual metric.

Parameters:

• predicted (Tensor)

• targets (Tensor)

Return type:

None

class ucs.utils.metrics.TestMetrics(num_classes, device='cpu', ignore_index=None)

Bases: SegMetrics

A utility class to handle metrics for segmentation tasks. Provides functionality for IoU (Jaccard Index) and Dice coefficient calculation.

Parameters:

• num_classes (int) – Number of classes in the segmentation task.

• device (str, optional) – Device to run the metrics on. Default is “cpu”.

• ignore_index (int, optional) – Specifies a target value that is ignored and does not contribute to the inputs gradient. Default is None.

Variables:

• num_classes (int) – The number of classes.

• ignore_index (int) – The index to ignore in the target.

• metrics (dict) – Dictionary of metrics to compute.

ucs.utils.metrics.compute_class_weights(dataloader, num_classes, mask_key='labels', normalize='raw', ignore_index=None)

Compute class weights based on the frequencies of each class in the dataset.

Parameters:

• dataloader (DataLoader) – PyTorch DataLoader containing the dataset.

• num_classes (int) – Total number of classes.

• mask_key (str) – Key to access masks/labels in the dataloader’s batch.

• normalize (str) – Method to normalize weights: - “sum”: Scales weights to sum to 1. - “max”: Scales weights so the maximum weight is 1. - “raw”: Leaves weights unnormalized. - “balanced”: Ensures equal contribution from all classes.

• ignore_index (int, optional) – Class index to ignore in weight computation.

Returns:

Computed class weights of shape (num_classes,).

Return type:

Tensor

Raises:

NormalizeError – If the normalization method is unsupported.