functional package

Submodules

functional.interpretation module

Module to generate heat maps for trained model

class functional.interpretation.HeatMaps(model)

Bases: object

Generates heat maps for a trained model with respect to given layers. SegGradCam (Gradient Based Activation Methods) are used to calculate relevance values of individual pixels. Details can be found here .

Parameters

model (PytorchModel) – A trained segmentation model.

generate_grayscale_cam(input_tensor, target_category, target_layers)

Calculates the grayscale representation of the relevance of individual pixel values using GradCam.

Parameters

• input_tensor (torch.Tensor) – The tensor to calculate the desired values for.

• target_category (int) – The category or class of the predicted mask.

• target_layers (List[torch.nn.Module]) – A list of layers of the given model architecture. Used for calculating the gradient of the GradCam method.

Returns

An array with the grayscale pixel importance values.

generate_grayscale_logits(input_tensor, target_category)

Calculates the grayscale representation of the relevance of individual pixel values using the model prediction.

Parameters

• input_tensor (torch.Tensor) – The tensor to calculate the desired values for.

• target_category (int) – The category or class of the predicted mask.

Returns

An array with the grayscale pixel importance values.

static show_grayscale_heatmap_on_image(image, grayscale_heatmap)

Maps the calculated grayscale relevance values to a given image.

Parameters

• image (np.ndarray) – The image to map the pixel relevance values against.

• grayscale_heatmap (np.ndarray) – The calculated relevance values in grayscale format.

Returns

The input image in RGB format with mapped heatmap.

class functional.interpretation.SemanticSegmentationTarget(category, mask)

Bases: object

Wraps the target for generating heat maps. All pixels belonging to the given prediction of the category will be summed up. More details can be found here .

Parameters

• category (int) – The category or class of the predicted mask.

• mask (np.ndarray) – The predicted mask as numpy array.

functional.losses module

Module containing segmentation losses

class functional.losses.AbstractDiceLoss(ignore_index=None, include_background=True, reduction='mean', epsilon=1e-10)

Bases: functional.losses.SegmentationLoss, abc.ABC

Base class for implementation of Dice loss and Generalized Dice loss.

Parameters

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

• include_background (bool, optional) – if False, class channel index 0 (background class) is excluded from the calculation (default = True).

• reduction (str, optional) – Specifies the reduction to aggregate the loss values over the images of a batch and multiple classes: “none” | “mean” | “sum”. “none”: no reduction will be applied, “mean”: the mean of the output is taken, “sum”: the output will be summed (default = “mean”).

• epsilon (float, optional) – Laplacian smoothing term to avoid divisions by zero (default = 1e-10).

forward(prediction, target)

Parameters

• prediction (Tensor) – Predicted segmentation mask which is either the output of a softmax or a sigmoid layer.

• target (Tensor) – Target segmentation mask which is either label encoded, one-hot encoded or multi-hot encoded.

Returns

Dice loss.

Return type

Tensor

Shape:

• Prediction: \((N, C, X, Y, ...)\), where N = batch size, C = number of classes and each value is

  in \([0, 1]\)
• Target: \((N, X, Y, ...)\) where each value is in \(\{0, ..., C - 1\}\) in case of label

  encoding or \((N, C, X, Y, ...)\), where each value is in \(\{0, 1\}\) in case of one-hot or

  multi-hot encoding.

• Output: If reduction is “none”, shape \((N, C)\). Otherwise, scalar.

abstract get_dice_loss_module()

Returns

Dice loss module.

Return type

Module

training

class functional.losses.CrossEntropyDiceLoss(multi_label=False, ignore_index=None, include_background=True, reduction='mean', epsilon=1e-10)

Bases: functional.losses.SegmentationLoss

Implements a loss function that combines the Dice loss with the binary cross-entropy (negative log-likelihood) loss.

Parameters

• multi_label (bool, optional) – Determines if data is multilabel or not (default = False).

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

• include_background (bool, optional) – if False, class channel index 0 (background class) is excluded from the Dice loss calculation, but not from the Cross-entropy loss calculation (default = True).

• reduction (str, optional) – Specifies the reduction to aggregate the loss values over the images of a batch and multiple classes: “none” | “mean” | “sum”. “none”: no reduction will be applied, “mean”: the mean of the output is taken, “sum”: the output will be summed (default = “mean”).

• epsilon (float, optional) – Laplacian smoothing term to avoid divisions by zero (default = 1e-10).

forward(prediction, target, weight=None)

Parameters

• prediction (Tensor) – Predicted segmentation mask which is either the output of a softmax or a sigmoid layer.

• target (Tensor) – Target segmentation mask which is either label encoded, one-hot encoded or multi-hot encoded.

• weight (Tensor, optional) – Manual weight given to the loss of each image / slice. Defaults to None, which means that all images are weighted equally.

Returns

Combined loss.

Return type

Tensor

Shape:

• Prediction: \((N, C, X, Y, ...)\), where N = batch size, C = number of classes and each value is

  in \([0, 1]\)
• Target: \((N, X, Y, ...)\) where each value is in \(\{0, ..., C - 1\}\) in case of label

  encoding and \((N, C, X, Y, ...)\), where each value is in \(\{0, 1\}\) in case of one-hot or

  multi-hot encoding.

• Weight: \((N)\) where N = batch size.

• Output: If reduction is “none”, shape \((N, C)\). Otherwise, scalar.

training

class functional.losses.CrossEntropyLoss(multi_label=False, ignore_index=None, reduction='mean', epsilon=1e-10)

Bases: functional.losses.SegmentationLoss

Wrapper for the PyTorch implementation of BCE loss / NLLLoss to ensure uniform reduction behaviour for all losses.

Parameters

• multi_label (bool, optional) – Determines if data is multilabel or not (default = False).

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

• reduction (str, optional) – Specifies the reduction to aggregate the loss values over the images of a batch and multiple classes: “none” | “mean” | “sum”. “none”: no reduction will be applied, “mean”: the mean of the output is taken, “sum”: the output will be summed (default = “mean”).

• epsilon (float, optional) – Laplacian smoothing term to avoid divisions by zero (default = 1e-10).

forward(prediction, target, weight=None)

Parameters

• prediction (Tensor) – Predicted segmentation mask which is either the output of a softmax or a sigmoid layer.

• target (Tensor) – Target segmentation mask which is either label encoded, one-hot encoded or multi-hot

• encoded. –

• weight (Tensor, optional) – Manual weight given to the loss of each image / slice. Defaults to None, which means that all images are weighted equally.

Returns

Cross-entropy loss.

Return type

Tensor

Shape:

• Prediction: \((N, C, X, Y, ...)\), where N = batch size, C = number of classes and each value is

  in \([0, 1]\)
• Target: \((N, X, Y, ...)\) where each value is in \(\{0, ..., C - 1\}\) in case of label

  encoding and \((N, C, X, Y, ...)\), where each value is in \(\{0, 1\}\) in case of one-hot or

  multi-hot encoding.

• Weight: \((N)\) where N = batch size.

• Output: If reduction is “none”, shape \((N, C)\). Otherwise, scalar.

training

class functional.losses.DiceLoss(ignore_index=None, include_background=True, reduction='mean', epsilon=1e-10)

Bases: functional.losses.AbstractDiceLoss

Implementation of the Dice loss for segmentation tasks. The Dice loss for binary segmentation tasks originally was formulated in:

Fausto Milletari, Nassir Navab, and Seyed-Ahmad Ahmadi. V-net: Fully convolutional neural networks for volumetric medical image segmentation, 2016.

In this implementation an adapted version of the Dice loss is used that a includes an epsilon term :math:`epsilon`to avoid divisions by zero and does not square the terms in the denominator. Additionally, the loss formulation is generalized to multi-class classification tasks by averaging dice losses over the class and batch dimension:

\[DL = 1 - \frac{1}{N \cdot L} \cdot \sum_{n=1}^N \sum_{l=1}^L 2 \cdot \frac{\sum_{i} r_{nli} p_{nli} + \epsilon}{\sum_{n=1}^N \sum_{l=1}^L \sum_{i} (r_{nli} + p_{nli}) + \epsilon} \]

where \(N\) is the batch size, \(L\) is the number of classes, \(r_{nli}\) are the ground-truth labels for class \(l\) in the \(i\)-th voxel of the \(n\)-th image. Analogously, \(p\) is the predicted probability for class \(l\) in the \(i\)-th voxel of the \(n\)-th image.

This implementation is a wrapper of the Dice loss implementation from the MONAI package that adapts the reduction behaviour. It supports both single-label and multi-label segmentation tasks. For a discussion on different dice loss implementations, see https://github.com/pytorch/pytorch/issues/1249.

Parameters

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

• include_background (bool, optional) – if False, class channel index 0 (background class) is excluded from the calculation (default = True).

• reduction (str, optional) – Specifies the reduction to aggregate the loss values over the images of a batch and multiple classes: “none” | “mean” | “sum”. “none”: no reduction will be applied, “mean”: the mean of the output is taken, “sum”: the output will be summed (default = “mean”).

• epsilon (float, optional) – Laplacian smoothing term to avoid divisions by zero (default = 1e-10).

forward(prediction, target, weight=None)

Parameters

• prediction (Tensor) – Predicted segmentation mask which is either the output of a softmax or a sigmoid layer.

• target (Tensor) – Target segmentation mask which is either label encoded, one-hot encoded or multi-hot encoded.

• weight (Tensor, optional) – Manual weight given to the loss of each image / slice. Defaults to None, which means that all images are weighted equally.

Returns

Dice loss.

Return type

Tensor

Shape:

• Prediction: \((N, C, X, Y, ...)\), where N = batch size, C = number of classes and each value is

  in \([0, 1]\)
• Target: \((N, X, Y, ...)\) where each value is in \(\{0, ..., C - 1\}\) in case of label

  encoding and \((N, C, X, Y, ...)\), where each value is in \(\{0, 1\}\) in case of one-hot or

  multi-hot encoding.

• Weight: \((N)\) where N = batch size.

• Output: If reduction is “none”, shape \((N, C)\). Otherwise, scalar.

get_dice_loss_module()

Returns

Dice loss module.

Return type

Module

training

class functional.losses.FalsePositiveDiceLoss(ignore_index=None, include_background=True, reduction='mean', epsilon=1e-10)

Bases: functional.losses.SegmentationLoss

Implements a loss function that combines the Dice loss with the false positive loss.

Parameters

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

• include_background (bool, optional) – if False, class channel index 0 (background class) is excluded from the calculation (default = True).

• reduction (str, optional) – Specifies the reduction to aggregate the loss values over the images of a batch and multiple classes: “none” | “mean” | “sum”. “none”: no reduction will be applied, “mean”: the mean of the output is taken, “sum”: the output will be summed (default = “mean”).

• epsilon (float, optional) – Laplacian smoothing term to avoid divisions by zero (default = 1e-10).

forward(prediction, target, weight=None)

Parameters

• prediction (Tensor) – Predicted segmentation mask which is either the output of a softmax or a sigmoid layer.

• target (Tensor) – Target segmentation mask which is either label encoded, one-hot encoded or multi-hot encoded.

• weight (Tensor, optional) – Manual weight given to the loss of each image / slice. Defaults to None, which means that all images are weighted equally.

Returns

Combined loss.

Return type

Tensor

Shape:

• Prediction: \((N, C, X, Y, ...)\), where N = batch size, C = number of classes and each value is

  in \([0, 1]\)
• Target: \((N, X, Y, ...)\) where each value is in \(\{0, ..., C - 1\}\) in case of label

  encoding and \((N, C, X, Y, ...)\), where each value is in \(\{0, 1\}\) in case of one-hot or

  multi-hot encoding.

• Weight: \((N)\) where N = batch size.

• Output: If reduction is “none”, shape \((N, C)\). Otherwise, scalar.

training

class functional.losses.FalsePositiveLoss(ignore_index=None, include_background=True, reduction='mean', epsilon=1e-10)

Bases: functional.losses.SegmentationLoss

Implementation of false positive loss.

Parameters

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

• include_background (bool, optional) – if False, class channel index 0 (background class) is excluded from the calculation (default = True).

• reduction (str, optional) – Specifies the reduction to aggregate the loss values over the images of a batch and multiple classes: “none” | “mean” | “sum”. “none”: no reduction will be applied, “mean”: the mean of the output is taken, “sum”: the output will be summed (default = “mean”).

• epsilon (float, optional) – Laplacian smoothing term to avoid divisions by zero (default = 1e-10).

forward(prediction, target, weight=None)

Parameters

• prediction (Tensor) – Predicted segmentation mask which is either the output of a softmax or a sigmoid layer.

• target (Tensor) – Target segmentation mask which is either label encoded, one-hot encoded or multi-hot

• encoded. –

• weight (Tensor, optional) – Manual weight given to the loss of each image / slice. Defaults to None, which means that all images are weighted equally.

Returns

False positive loss.

Return type

Tensor

Shape:

• Prediction: \((N, C, X, Y, ...)\), where N = batch size, C = number of classes and each value is

  in \([0, 1]\)
• Target: \((N, X, Y, ...)\) where each value is in \(\{0, ..., C - 1\}\) in case of label

  encoding and \((N, C, X, Y, ...)\), where each value is in \(\{0, 1\}\) in case of one-hot or

  multi-hot encoding.

• Weight: \((N)\) where N = batch size.

• Output: If reduction is “none”, shape \((N, C)\). Otherwise, scalar.

training

class functional.losses.FocalLoss(multi_label=False, ignore_index=None, reduction='mean', epsilon=1e-10, gamma=5)

Bases: functional.losses.CrossEntropyLoss

Wrapper for the CrossEntropyLoss to perform some additional computations to turn it into focal loss.

Parameters

• multi_label (bool, optional) – Determines if data is multilabel or not (default = False).

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

• reduction (str, optional) – Specifies the reduction to aggregate the loss values over the images of a batch and multiple classes: “none” | “mean” | “sum”. “none”: no reduction will be applied, “mean”: the mean of the output is taken, “sum”: the output will be summed (default = “mean”).

• epsilon (float, optional) – Laplacian smoothing term to avoid divisions by zero (default = 1e-10).

• gamma (float, optional) – Specifies how far the loss of well-classified examples is down-weighed (default = 5)

training

class functional.losses.GeneralizedDiceLoss(ignore_index=None, include_background=True, weight_type='square', reduction='mean', epsilon=1e-10)

Bases: functional.losses.AbstractDiceLoss

Implementation of Generalized Dice loss for segmentation tasks. The Generalized Dice loss was formulated in:

Carole H. Sudre, Wenqi Li, Tom Vercauteren, Sebastien Ourselin, and M. Jorge Cardoso: Generalised Dice overlap as a deep learning loss function for highly unbalanced segmentations, 2017.

It is formulated as:

\[GDL = \frac{1}{N} \cdot \sum_{n=1}^N (1 - 2 \frac{\sum_{l=1}^L w_l \cdot \sum_{i} r_{nli} p_{nli} + \epsilon}{\sum_{l=1}^L w_l \cdot \sum_{i} (r_{nli} + p_{nli}) + \epsilon}) \]

where \(N\) is the batch size, \(L\) is the number of classes, \(w_l\) is a class weight, \(r_{nli}\) are the ground-truth labels for class \(l\) in the \(i\)-th voxel of the \(n\)-th image. Analogously, \(p\) is the predicted probability for class \(l\) in the \(i\)-th voxel of the \(n\)-th image.

This implementation is a wrapper of the Generalized Dice loss implementation from the MONAI package that adapts the reduction behaviour. It supports both single-label and multi-label segmentation tasks.

Parameters

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

• include_background (bool, optional) – if False, class channel index 0 (background class) is excluded from the calculation (default = True).

• weight_type (string, optional) – Type of function to transform ground truth volume to a weight factor: “square” | “simple” | “uniform”. Defaults to “square”.

• reduction (str, optional) – Specifies the reduction to aggregate the loss values over the images of a batch and multiple classes: “none” | “mean” | “sum”. “none”: no reduction will be applied, “mean”: the mean of the output is taken, “sum”: the output will be summed (default = “mean”).

• epsilon (float, optional) – Laplacian smoothing term to avoid divisions by zero (default = 1e-10).

forward(prediction, target, weight=None)

Parameters

• prediction (Tensor) – Predicted segmentation mask which is either the output of a softmax or a sigmoid layer.

• target (Tensor) – Target segmentation mask which is either label encoded, one-hot encoded or multi-hot encoded.

• weight (Tensor, optional) – Manual weight given to the loss of each image / slice. Defaults to None, which means that all images are weighted equally.

Returns

Generalized dice loss.

Return type

Tensor

Shape:

• Prediction: \((N, C, X, Y, ...)\), where N = batch size, C = number of classes and each value is

  in \([0, 1]\)
• Target: \((N, X, Y, ...)\) where each value is in \(\{0, ..., C - 1\}\) in case of label

  encoding and \((N, C, X, Y, ...)\), where each value is in \(\{0, 1\}\) in case of one-hot or

  multi-hot encoding.

• Weight: \((N)\) where N = batch size.

• Output: If reduction is “none”, shape \((N, C)\). Otherwise, scalar.

get_dice_loss_module()

Returns

Dice loss module.

Return type

Module

training

class functional.losses.SegmentationLoss(ignore_index=None, include_background=True, reduction='mean', epsilon=1e-10)

Bases: torch.nn.modules.module.Module, abc.ABC

Base class for implementation of segmentation losses.

Parameters

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

• include_background (bool, optional) – if False, class channel index 0 (background class) is excluded from the calculation (default = True).

• reduction (str, optional) – Specifies the reduction to aggregate the loss values over the images of a batch and multiple classes: “none” | “mean” | “sum”. “none”: no reduction will be applied, “mean”: the mean of the output is taken, “sum”: the output will be summed (default = “mean”).

• epsilon (float, optional) – Laplacian smoothing term to avoid divisions by zero (default = 1e-10).

training

functional.metrics module

Module containing model evaluation metrics.

The metric implementations are based on the TorchMetrics framework. For instructions on how to implement custom metrics with this framework, see https://torchmetrics.readthedocs.io/en/latest/pages/implement.html.

class functional.metrics.DiceScore(num_classes, convert_to_one_hot=True, epsilon=0, ignore_index=None, include_background=True, reduction='none')

Bases: functional.metrics.SegmentationMetric

Computes the Dice similarity coefficient (DSC). Can be used for 3D images whose slices are scattered over multiple batches.

Parameters

• num_classes (int) – Number of classes (for single-label segmentation tasks including the background class).

• convert_to_one_hot (bool, optional) – Determines if data is label encoded and needs to be converted to one-hot encoding or not (default = True).

• epsilon (float, optional) – Laplacian smoothing term to avoid divisions by zero (default = 0).

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

• include_background (bool, optional) – if False, class channel index 0 (background class) is excluded from the calculation (default = True).

• reduction (string, optional) –

  A method to reduce metric scores of multiple classes.

  • "none": no reduction will be applied (default)

  • "mean": takes the mean

  • "min": takes the minimum

  • "max": takes the maximum

compute()

Computes the DSC over all slices that were registered using the update method.

Returns

Dice similarity coefficient.

Return type

Tensor

Shape:

• Output: If reduction is “none”, shape \((C)\). Otherwise, scalar.

update(prediction, target)

Updates metric using the provided prediction.

Parameters

• prediction (Tensor) – The prediction tensor.

• target (Tensor) – The target tensor.

Shape:

• Prediction: \((X, Y, ...)\) where each value is in \(\{0, ..., C - 1\}\) in case of label

  encoding and \((C, X, Y, ...)\), where each value is in \(\{0, 1\}\) in case of one-hot or

  multi-hot encoding (C = number of classes).

• Target: Same shape and type as prediction.

class functional.metrics.HausdorffDistance(num_classes, slices_per_image, convert_to_one_hot=True, ignore_index=None, include_background=True, normalize=False, percentile=0.95, reduction='none')

Bases: functional.metrics.SegmentationMetric

Computes the Hausdorff distance. Can be used for 3D images whose slices are scattered over multiple batches.

Parameters

• num_classes (int) – Number of classes (for single-label segmentation tasks including the background class).

• slices_per_image (int) – Number of slices per 3d image.

• convert_to_one_hot (bool, optional) – Determines if data is label encoded and needs to be converted to one-hot encoding or not (default = True).

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

• include_background (bool, optional) – if False, class channel index 0 (background class) is excluded from the calculation (default = True).

• normalize (bool, optional) – Whether the Hausdorff distance should be normalized by dividing it by the diagonal distance.

• percentile (float, optional) – Percentile for which the Hausdorff distance is to be calculated, must be in \(\[0, 1\]\).

• reduction (string, optional) –

  A method to reduce metric scores of multiple classes (default = “none”).

  • "none": no reduction will be applied (default)

  • "mean": takes the mean

  • "min": takes the minimum

  • "max": takes the maximum

compute()

Computes the Hausdorff distance over all slices that were registered using the update method as the maximum per slice-distance.

Returns

Hausdorff distance.

Return type

Tensor

Shape:

• Output: If reduction is “none”, shape \((C)\). Otherwise, scalar.

reset()

Resets the metric state.

update(prediction, target, slice_ids=None)

Updates metric using the provided prediction.

Parameters

• prediction (Tensor) – The prediction tensor.

• target (Tensor) – The target tensor.

• slice_ids (Union[int, List[int]]) – Indices of the image slices represented by prediction and target. Must be provided if target is a single slice or a subset of slices taken from a 3d image.

Shape:

• Prediction: \((X, Y, ...)\) where each value is in \(\{0, ..., C - 1\}\) in case of label

  encoding and \((C, X, Y, ...)\), where each value is in \(\{0, 1\}\) in case of one-hot or

  multi-hot encoding (C = number of classes).

• Target: Same shape and type as prediction.

class functional.metrics.SegmentationMetric(num_classes, convert_to_one_hot=True, ignore_index=None, ignore_value=0, include_background=True, reduction='none')

Bases: torchmetrics.metric.Metric, abc.ABC

Base class for segmentation metrics.

Parameters

• num_classes (int) – Number of classes (for single-label segmentation tasks including the background class).

• convert_to_one_hot (bool, optional) – Determines if data is label encoded and needs to be converted to one-hot encoding or not (default = True).

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

• include_background (bool, optional) – if False, class channel index 0 (background class) is excluded from the calculation (default = True).

• ignore_value (float, optional) – Value that should be inserted at the positions where the target is equal to ignore_index. Defaults to 0.

• reduction (string, optional) –

  A method to reduce metric scores of multiple classes.

  • "none": no reduction will be applied (default)

  • "mean": takes the mean

  • "min": takes the minimum

  • "max": takes the maximum

class functional.metrics.Sensitivity(num_classes, convert_to_one_hot=True, epsilon=0, ignore_index=None, include_background=True, reduction='none')

Bases: functional.metrics.SegmentationMetric

Computes the sensitivity. Can be used for 3D images whose slices are scattered over multiple batches.

Parameters

• num_classes (int) – Number of classes (for single-label segmentation tasks including the background class).

• convert_to_one_hot (bool, optional) – Determines if data is label encoded and needs to be converted to one-hot encoding or not (default = True).

• epsilon (float, optional) – Laplacian smoothing term to avoid divisions by zero (default = 0).

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

• include_background (bool, optional) – if False, class channel index 0 (background class) is excluded from the calculation (default = True).

• reduction (string, optional) –

  A method to reduce metric scores of multiple classes.

  • "none": no reduction will be applied (default)

  • "mean": takes the mean

  • "min": takes the minimum

  • "max": takes the maximum

compute()

Computes the sensitivity over all slices that were registered using the update method.

Returns

Sensitivity.

Return type

Tensor

Shape:

• Output: If reduction is “none”, shape \((C)\). Otherwise, scalar.

update(prediction, target)

Updates metric using the provided prediction.

Parameters

• prediction (Tensor) – The prediction tensor.

• target (Tensor) – The target tensor.

Shape:

• Prediction: \((X, Y, ...)\) where each value is in \(\{0, ..., C - 1\}\) in case of label

  encoding and \((C, X, Y, ...)\), where each value is in \(\{0, 1\}\) in case of one-hot or

  multi-hot encoding (C = number of classes).

• Target: Same shape and type as prediction.

class functional.metrics.Specificity(num_classes, convert_to_one_hot=True, epsilon=0, ignore_index=None, include_background=True, reduction='none')

Bases: functional.metrics.SegmentationMetric

Computes the specificity. Can be used for 3D images whose slices are scattered over multiple batches.

Parameters

• num_classes (int) – Number of classes (for single-label segmentation tasks including the background class).

• convert_to_one_hot (bool, optional) – Determines if data is label encoded and needs to be converted to one-hot encoding or not (default = True).

• epsilon (float, optional) – Laplacian smoothing term to avoid divisions by zero (default = 0).

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

• include_background (bool, optional) – if False, class channel index 0 (background class) is excluded from the calculation (default = True).

• reduction (string, optional) –

  A method to reduce metric scores of multiple classes (default = “none”).

  • "none": no reduction will be applied (default)

  • "mean": takes the mean

  • "min": takes the minimum

  • "max": takes the maximum

compute()

Computes the sensitivity over all slices that were registered using the update method.

Returns

Sensitivity.

Return type

Tensor

Shape:

• Output: If reduction is “none”, shape \((C)\). Otherwise, scalar.

update(prediction, target)

Updates metric using the provided prediction.

Parameters

• prediction (Tensor) – The prediction tensor.

• target (Tensor) – The target tensor.

Shape:

• Prediction: \((X, Y, ...)\) where each value is in \(\{0, ..., C - 1\}\) in case of label

  encoding and \((C, X, Y, ...)\), where each value is in \(\{0, 1\}\) in case of one-hot or

  multi-hot encoding (C = number of classes).

• Target: Same shape and type as prediction.

functional.metrics.dice_score(prediction, target, num_classes, convert_to_one_hot=True, epsilon=0, ignore_index=None, include_background=True, reduction='none')

Computes the Dice similarity coefficient (DSC) between a predicted segmentation mask and the target mask:

\(DSC = \frac{2 \cdot TP}{2 \cdot TP + FP + FN}\)

Using the epsilon parameter, Laplacian smoothing can be applied:

\(DSC = \frac{2 \cdot TP + \lambda}{2 \cdot TP + FP + FN + \lambda}\)

This metric supports both single-label and multi-label segmentation tasks.

Parameters

• prediction (Tensor) – The prediction tensor.

• target (Tensor) – The target tensor.

• num_classes (int) – Number of classes (for single-label segmentation tasks including the background class).

• convert_to_one_hot (bool, optional) – Determines if data is label encoded and needs to be converted to one-hot encoding or not (default = True).

• epsilon (float, optional) – Laplacian smoothing factor (default = 0).

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

• include_background (bool, optional) – if False, class channel index 0 (background class) is excluded from the calculation (default = True).

• reduction (string) – A method to reduce metric scores of multiple classes. - "none": no reduction will be applied (default) - "mean": takes the mean - "min": takes the minimum - "max": takes the maximum

Returns

Dice similarity coefficient.

Return type

Tensor

Shape:

• Prediction: \((X, Y, ...)\) where each value is in \(\{0, ..., C - 1\}\) in case of label encoding

  and \((C, X, Y, ...)\), where each value is in \(\{0, 1\}\) in case of one-hot or multi-hot encoding

  (C = number of classes).

• Target: Same shape and type as prediction.

• Output: If reduction is “none”, shape \((C)\). Otherwise, scalar.

functional.metrics.hausdorff_distance(prediction, target, num_classes, all_image_locations=None, convert_to_one_hot=True, ignore_index=None, include_background=True, normalize=False, percentile=0.95, reduction='none')

Computes the Hausdorff distance between a predicted segmentation mask and the target mask.

This metric supports both single-label and multi-label segmentation tasks.

Parameters

• prediction (Tensor) – The prediction tensor.

• target (Tensor) – The target tensor.

• num_classes (int) – Number of classes (for single-label segmentation tasks including the background class).

• all_image_locations (Tensor, optional) – A pre-computed tensor containing one point for each pixel in the prediction representing the pixel’s location in 2d or 3d Euclidean space. Passing a pre-computed tensor to this parameter can be used to speed up computation.

• convert_to_one_hot (bool, optional) – Determines if data is label encoded and needs to be converted to one-hot encoding or not (default = True).

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

• include_background (bool, optional) – if False, class channel index 0 (background class) is excluded from the calculation (default = True).

• normalize (bool, optional) – Whether the Hausdorff distance should be normalized by dividing it by the diagonal distance.

• percentile (float, optional) – Percentile for which the Hausdorff distance is to be calculated, must be in \(\[0, 1\]\).

• reduction (string) – A method to reduce metric scores of multiple classes. - "none": no reduction will be applied (default) - "mean": takes the mean - "min": takes the minimum - "max": takes the maximum

Returns

Hausdorff distance.

Return type

Tensor

Shape:

• Prediction: \((X, Y, ...)\) where each value is in \(\{0, ..., C - 1\}\) in case of label encoding

  and \((C, X, Y, ...)\), where each value is in \(\{0, 1\}\) in case of one-hot or multi-hot encoding

  (C = number of classes).

• Target: Same shape and type as prediction.

• Output: If reduction is “none”, shape \((C)\). Otherwise, scalar.

functional.metrics.sensitivity(prediction, target, num_classes, convert_to_one_hot=True, epsilon=0, ignore_index=None, include_background=True, reduction='none')

Computes the sensitivity from a predicted segmentation mask and the target mask:

\(Sensitivity = \frac{TP}{TP + FN}\)

Using the epsilon parameter, Laplacian smoothing can be applied:

\(Sensitivity = \frac{TP + \lambda}{TP + FN + \lambda}\)

This metric supports both single-label and multi-label segmentation tasks.

Parameters

• prediction (Tensor) – The prediction tensor.

• target (Tensor) – The target tensor.

• num_classes (int) – Number of classes (for single-label segmentation tasks including the background class).

• convert_to_one_hot (bool, optional) – Determines if data is label encoded and needs to be converted to one-hot encoding or not (default = True).

• epsilon (float, optional) – Laplacian smoothing factor (default = 0).

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

• include_background (bool, optional) – if False, class channel index 0 (background class) is excluded from the calculation (default = True).

• reduction (string) – A method to reduce metric scores of multiple classes. - "none": no reduction will be applied (default) - "mean": takes the mean - "min": takes the minimum - "max": takes the maximum

Returns

Sensitivity.

Return type

Tensor

Shape:

• Prediction: \((X, Y, ...)\) where each value is in \(\{0, ..., C - 1\}\) in case of label encoding

  and \((C, X, Y, ...)\), where each value is in \(\{0, 1\}\) in case of one-hot or multi-hot encoding

  (C = number of classes).

• Target: Same shape and type as prediction.

• Output: If reduction is “none”, shape \((C)\). Otherwise, scalar.

functional.metrics.single_class_hausdorff_distance(prediction, target, normalize=False, percentile=0.95, all_image_locations=None)

Computes the Hausdorff distance between a predicted segmentation mask and the target mask.

Note

In this method, the prediction tensor is considered as a segmentation mask of a single 2D or 3D image for a given class and thus the distances are calculated over all channels and dimensions. As this method is implemented using the scipy package, the returned value is not differentiable in PyTorch and can therefore not be used in loss functions.

Parameters

• prediction (Tensor) – The predicted segmentation mask, where each value is in \(\{0, 1\}\).

• target (Tensor) – The target segmentation mask, where each value is in \(\{0, 1\}\).

• normalize (bool, optional) – Whether the Hausdorff distance should be normalized by dividing it by the diagonal distance.

• percentile (float, optional) – Percentile for which the Hausdorff distance is to be calculated, must be in \(\[0, 1\]\).

• all_image_locations (Tensor, optional) – A pre-computed tensor containing one point for each pixel in the prediction representing the pixel’s location in 2d or 3d Euclidean space. Passing a pre-computed tensor to this parameter can be used to speed up computation.

Returns

Hausdorff distance.

Return type

Tensor

Shape:

• Prediction: Can have arbitrary dimensions. Typically \((S, height, width)\), where

  S = number of slices, or (height, width) for single image segmentation tasks.

• Target: Must have the same dimensions as the prediction.

• All_image_locations: Must contain one element per-pixel in the prediction. Each element represents an

  n-dimensional point. Typically \((S \cdot height \cdot width, 3)\), where S = number of slices, or

  \((height \cdot width, 2)\)

• Output: Scalar.

functional.metrics.specificity(prediction, target, num_classes, convert_to_one_hot=True, epsilon=0, ignore_index=None, include_background=True, reduction='none')

Computes the specificity from a predicted segmentation mask and the target mask:

\(Specificity = \frac{TN}{TN + FP}\)

Using the epsilon parameter, Laplacian smoothing can be applied:

\(Specificity = \frac{TN + \lambda}{TN + FP + \lambda}\)

This metric supports both single-label and multi-label segmentation tasks.

Parameters

• prediction (Tensor) – The prediction tensor.

• target (Tensor) – The target tensor.

• num_classes (int) – Number of classes (for single-label segmentation tasks including the background class).

• convert_to_one_hot (bool, optional) – Determines if data is label encoded and needs to be converted to one-hot encoding or not (default = True).

• epsilon (float, optional) – Laplacian smoothing factor (default = 0).

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

• include_background (bool, optional) – if False, class channel index 0 (background class) is excluded from the calculation (default = True).

• reduction (string) – A method to reduce metric scores of multiple classes. - "none": no reduction will be applied (default) - "mean": takes the mean - "min": takes the minimum - "max": takes the maximum

Returns

Specificity.

Return type

Tensor

Shape:

• Prediction: \((X, Y, ...)\) where each value is in \(\{0, ..., C - 1\}\) in case of label encoding

  and \((C, X, Y, ...)\), where each value is in \(\{0, 1\}\) in case of one-hot or multi-hot encoding

  (C = number of classes).

• Target: Same shape and type as prediction.

• Output: If reduction is “none”, shape \((C)\). Otherwise, scalar.

functional.utils module

Utilities for metric and loss computations.

functional.utils.flatten_tensors(prediction, target, include_background=True)

Reshapes and flattens prediction and target tensors except for the first dimension (class dimension).

Parameters

• prediction (Tensor) – The prediction tensor (one-hot encoded or multi-hot encoded).

• target (Tensor) – The target tensor (one-hot encoded or multi-hot encoded).

• include_background (bool, optional) – if False, class channel index 0 (background class) is excluded from the calculation (default = True).

Returns

Flattened prediction and target tensors (one-hot or multi-hot encoded).

Return type

Tuple[Tensor]

Shape:

• Prediction: \((C, X, Y, ...)\), where C = number of classes and each value is in \(\{0, 1\}\).

• Target: Must have same shape and type as prediction.

• Output: \((C, X * Y * ...)\) where each element is in \(\{0, 1\}\) indicating the absence /

  presence of the respective class (one-hot or multi-hot encoding).

functional.utils.is_binary(tensor_to_check)

Checks whether the input contains only zeros and ones.

Parameters

tensor_to_check (Tensor) – tensor to check.

Returns

True if contains only zeros and ones, False otherwise.

Return type

bool

functional.utils.mask_tensor(tensor, mask, ignore_index=None, mask_value=0)

Replaces the tensor’s values in the positions where the mask is equal to ignore_index with mask_value.

Parameters

• tensor (Tensor) – A tensor in which is to be masked.

• mask (Tensor) – A mask tensor containing the ignore_index at the positions to be masked.

• ignore_index (int, optional) – Label index indicating the positions to be masked.

• mask_value (float, optional) – Value that should be inserted at the masked positions. Defaults to 0.

Returns

Masked tensor.

Return type

Tensor

Shape:

• Tensor: \((N, C, X, Y, ...)\) or \((C, X, Y, ...)\).

• Mask: \((N, 1, X, Y, ...)\) / \((N, C, X, Y, ...)\) or \((1, X, Y, ...)\) /

  \((C, X, Y, ...)\).

• Output: Same shape as input.

functional.utils.one_hot_encode(tensor, dim, num_classes, ignore_index=None)

Converts a label encoded tensor to a one-hot encoded tensor.

Parameters

• tensor (Tensor) – Label encoded tensor that is to be converted to one-hot encoding.

• dim (int) – Dimensionality of the input. Either 2 or 3.

• num_classes (int) – Number of classes (excluding the class labeled with ignore_label).

• ignore_index (int, optional) – Class value for which no one-hot encoded channel should be created in the output.

Returns

One-hot encoded tensor.

Return type

Tensor

Shape:

• Tensor: \((N, X, Y, ...)\) or \((X, Y, ...)\) where each element represents a class index of integer

  type and N = batch size.
• Output: \((N, C, X, Y, ...)\) or \((C, X, Y, ...)\) where each element represent a binary class

  label and \(C\) is the number of classes (excluding the ignored class labeled with

  ignore_label).

functional.utils.preprocess_metric_inputs(prediction, target, num_classes, convert_to_one_hot=True, ignore_index=None, ignore_value=0)

This method implements preprocessing steps that are needed for most segmentation metrics:

1. Validation of input shape and type

2. Conversion from label encoding to one-hot encoding if necessary

3. Mapping of pixels/voxels labeled with the ignore_index to true negatives or true positives

Parameters

• prediction (Tensor) – The prediction tensor to be preprocessed.

• target (Tensor) – The target tensor to be preprocessed.

• num_classes (int) – Number of classes (for single-label segmentation tasks including the background class).

• convert_to_one_hot (bool, optional) – Determines if data is label encoded and needs to be converted to one-hot encoding or not (default = True).

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

• ignore_value (float, optional) – Value that should be inserted at the positions where the target is equal to ignore_index. Defaults to 0.

Returns

The preprocessed prediction and target tensors.

Return type

Tuple[Tensor, Tensor]

functional.utils.reduce_metric(metric, reduction)

Aggregates the metric values of the different classes.

Parameters

• metric (Tensor) – Metrics to be aggregated.

• reduction (string) – A method to reduce metric scores of multiple classes. - "none": no reduction will be applied - "mean": takes the mean - "min": takes the minimum - "max": takes the maximum

Returns

Aggregated metric value.

Return type

Tensor

Shape:

• Metric: \((C)\), where C = number of classes.

• Output: If reduction is “none”, shape \((C)\). Otherwise, scalar.

functional.utils.remove_padding(prediction, target, ignore_index, is_label_encoded)

Removes padding from prediction and target tensor. For this purpose, the areas where the target tensor is equal to ignore_index are removed from both tensors. It is assumed that whole rows or columns are padded always.

Parameters

• prediction (Tensor) – A prediction tensor (label-encoded, one-hot encoded, or multi-hot encoded).

• target (Tensor) – A target tensor (with same encoding as prediction tensor).

• ignore_index (int) – Specifies the target value that is used as label for padded areas.

• is_label_encoded (bool) – Whether the input data are label encoded or one-hot / multi-hot encoded.

Returns

Prediction and target tensors without padding areas.

Return type

Tuple[Tensor, Tensor]

Shape:

• Prediction: \((X, Y, ...)\) in case of label encoding and \((C, X, Y, ...)\), in case of one-hot

  or multi-hot encoding (C = number of classes).

• Target: Same shape as prediction.

• Output: \((X - P_x, Y - P_y, ...)\) in case of label encoding and \((C, X - P_x, Y - P_y, ...)\),

  in case of one-hot or multi-hot encoding (C = number of classes, P_x = padding width on x-axis).

functional.utils.validate_metric_inputs(prediction, target, convert_to_one_hot)

Validates the inputs for segmentation metric computations:

• Checks that prediction and target are both on the same device.

• Checks that prediction and target have the correct shape and type.

Parameters

• prediction (Tensor) – The prediction tensor to be validated.

• target (Tensor) – The target tensor to be validated.

• convert_to_one_hot (bool, optional) – Determines if data is label encoded and is intended to be converted to one-hot encoding or not (default = True).

Raises

AssertionError – if input tensors violate any of the validation criteria.

Module contents