API Reference
This document is for developers of ivadomed
, it contains the API functions.
Loader API
loader.film
- normalize_metadata(ds_in: Union[BidsDataset, Bids3DDataset, MRI2DSegmentationDataset], clustering_models: dict, debugging: bool, metadata_type: str, train_set: bool = False) list, OneHotEncoder | list [source]
Categorize each metadata value using a KDE clustering method, then apply a one-hot-encoding.
- Parameters
ds_in (BidsDataset) – Dataset BidsDataset, Bids3D, MRI2D with metadata.
clustering_models (dict) – Pre-trained clustering model that has been trained on metadata of the training set.
debugging (bool) – If True, extended verbosity and intermediate outputs.
metadata_type (str) – Choice between ‘mri_params’, ‘constrasts’ or the name of a column from the participants.tsv file.
train_set (bool) – Indicates if the input dataset is the training dataset (True) or the validation or testing dataset (False).
- Returns
- Dataset with normalized metadata. If train_set is True, then the one-hot-encoder model is also
returned.
- Return type
BidsDataset
- class Kde_model[source]
Bases:
object
Kernel Density Estimation.
Apply this clustering method to metadata values, using (sklearn implementation.)
- Attributes
kde (sklearn.neighbors.KernelDensity)
minima (float) – Local minima.
- clustering_fit(dataset: list, key_lst: List[str]) dict [source]
This function creates clustering models for each metadata type, using Kernel Density Estimation algorithm.
- Parameters
dataset (list) – data
key_lst (list of str) – names of metadata to cluster
- Returns
Clustering model for each metadata type in a dictionary where the keys are the metadata names.
- Return type
dict
- check_isMRIparam(mri_param_type: str, mri_param: dict, subject: str, metadata: dict) bool [source]
Check if a given metadata belongs to the MRI parameters.
- Parameters
mri_param_type (str) – Metadata type name.
mri_param (dict) – List of MRI params names.
subject (str) – Current subject name.
metadata (dict) – Metadata.
- Returns
True if mri_param_type is part of mri_param.
- Return type
bool
- get_film_metadata_models(ds_train: MRI2DSegmentationDataset, metadata_type: str, debugging: bool = False)[source]
Get FiLM models.
This function pulls the clustering and one-hot encoder models that are used by FiLMedUnet. It also calls the normalization of metadata.
- Parameters
ds_train (MRI2DSegmentationDataset) – training dataset
metadata_type (string) – eg mri_params, contrasts
debugging (bool) –
- Returns
dataset, one-hot encoder and KDE model
- Return type
MRI2DSegmentationDataset, OneHotEncoder, KernelDensity
- store_film_params(gammas: dict, betas: dict, metadata_values: list, metadata: list, model: nn.Module, film_layers: list, depth: int, film_metadata: str)[source]
Store FiLM params.
- Parameters
gammas (dict) –
betas (dict) –
metadata_values (list) – list of the batch sample’s metadata values (e.g., T2w, astrocytoma)
metadata (list) –
model (nn.Module) –
film_layers (list) –
depth (int) –
film_metadata (str) – Metadata of interest used to modulate the network (e.g., contrast, tumor_type).
- Returns
gammas, betas, metadata_values
- Return type
dict, dict, list
- save_film_params(gammas: dict, betas: dict, metadata_values: list, depth: int, ofolder: str) None [source]
Save FiLM params as npy files.
These parameters can be further used for visualisation purposes. They are saved in the ofolder with .npy format.
- Parameters
gammas (dict) –
betas (dict) –
metadata_values (list) – list of the batch sample’s metadata values (eg T2w, T1w, if metadata type used is
contrast) –
depth (int) –
ofolder (str) –
loader.loader
- load_dataset(bids_df: ivadomed.loader.bids_dataframe.BidsDataframe, data_list: List[str], transforms_params: dict, model_params: dict, target_suffix: List[str], roi_params: dict, contrast_params: dict, slice_filter_params: dict, patch_filter_params: dict, slice_axis: str, multichannel: bool, dataset_type: str = 'training', requires_undo: bool = False, metadata_type: Optional[str] = None, object_detection_params: Optional[dict] = None, soft_gt: bool = False, device: Optional[torch.device] = None, cuda_available: Optional[bool] = None, is_input_dropout: bool = False, **kwargs) ivadomed.loader.bids3d_dataset.Bids3DDataset [source]
Get loader appropriate loader according to model type. Available loaders are Bids3DDataset for 3D data, BidsDataset for 2D data and HDF5Dataset for HeMIS.
- Parameters
bids_df (BidsDataframe) – Object containing dataframe with all BIDS image files and their metadata.
data_list (list) – Subject names list.
transforms_params (dict) – Dictionary containing transformations for “training”, “validation”, “testing” (keys), eg output of imed_transforms.get_subdatasets_transforms.
model_params (dict) – Dictionary containing model parameters.
target_suffix (list of str) – List of suffixes for target masks.
roi_params (dict) – Contains ROI related parameters.
contrast_params (dict) – Contains image contrasts related parameters.
slice_filter_params (dict) – Contains slice_filter_params, see Configuration File for more details.
patch_filter_params (dict) – Contains patch_filter_params, see Configuration File for more details.
slice_axis (string) – Choice between “axial”, “sagittal”, “coronal” ; controls the axis used to extract the 2D data from 3D NifTI files. 2D PNG/TIF/JPG files use default “axial.
multichannel (bool) – If True, the input contrasts are combined as input channels for the model. Otherwise, each contrast is processed individually (ie different sample / tensor).
metadata_type (str) – Choice between None, “mri_params”, “contrasts”.
dataset_type (str) – Choice between “training”, “validation” or “testing”.
requires_undo (bool) – If True, the transformations without undo_transform will be discarded.
object_detection_params (dict) – Object dection parameters.
soft_gt (bool) – If True, ground truths are not binarized before being fed to the network. Otherwise, ground
thresholded (truths are) –
device (torch.device) – Device to use for the model training.
cuda_available (bool) – If True, cuda is available.
is_input_dropout (bool) – Return input with missing modalities.
- Returns
BidsDataset
Note: For more details on the parameters transform_params, target_suffix, roi_params, contrast_params, slice_filter_params, patch_filter_params and object_detection_params see Configuration File.
loader.utils
- split_dataset(df: pd.DataFrame, split_method: str, data_testing: dict, random_seed: int, train_frac: float = 0.8, test_frac: float = 0.1)[source]
Splits dataset into training, validation and testing sets by applying train, test and validation fractions according to the split_method. The “data_testing” parameter can be used to specify the data_type and data_value to include in the testing set, the dataset is then split as not to mix the data_testing between the training/validation set and the testing set.
- Parameters
df (pd.DataFrame) – Dataframe containing all BIDS image files indexed and their metadata.
split_method (str) – Used to specify on which metadata to split the dataset (eg. “participant_id”, “sample_id”, etc.)
data_testing (dict) – Used to specify data_type and data_value to include in the testing set.
random_seed (int) – Random seed to ensure reproducible splits.
train_frac (float) – Between 0 and 1. Represents the train set proportion.
test_frac (float) – Between 0 and 1. Represents the test set proportion.
- Returns
Train, validation and test filenames lists.
- Return type
list, list, list
- get_new_subject_file_split(df: pd.DataFrame, split_method: str, data_testing: dict, random_seed: int, train_frac: float, test_frac: float, path_output: str, balance: str, subject_selection: dict = None)[source]
Randomly split dataset between training / validation / testing.
Randomly split dataset between training / validation / testing and save it in path_output + “/split_datasets.joblib”.
- Parameters
df (pd.DataFrame) – Dataframe containing all BIDS image files indexed and their metadata.
split_method (str) – Used to specify on which metadata to split the dataset (eg. “participant_id”, “sample_id”, etc.)
data_testing (dict) – Used to specify the data_type and data_value to include in the testing set.
random_seed (int) – Random seed.
train_frac (float) – Training dataset proportion, between 0 and 1.
test_frac (float) – Testing dataset proportionm between 0 and 1.
path_output (str) – Output folder.
balance (str) – Metadata contained in “participants.tsv” file with categorical values. Each category will be
training (evenly distributed in the) –
datasets. (validation and testing) –
subject_selection (dict) – Used to specify a custom subject selection from a dataset.
- Returns
Training, validation and testing filenames lists.
- Return type
list, list list
- get_subdatasets_subject_files_list(split_params: dict, df: pd.DataFrame, path_output: str, subject_selection: dict = None)[source]
Get lists of subject filenames for each sub-dataset between training / validation / testing.
- Parameters
split_params (dict) – Split parameters, see Configuration File for more details.
df (pd.DataFrame) – Dataframe containing all BIDS image files indexed and their metadata.
path_output (str) – Output folder.
subject_selection (dict) – Used to specify a custom subject selection from a dataset.
- Returns
Training, validation and testing filenames lists.
- Return type
list, list list
- imed_collate(batch: dict) dict | list | str | torch.Tensor [source]
Collates data to create batches
- Parameters
batch (dict) – Contains input and gt data with their corresponding metadata.
- Returns
Collated data.
- Return type
list or dict or str or tensor
- filter_roi(roi_data: numpy.ndarray, nb_nonzero_thr: int) bool [source]
Filter slices from dataset using ROI data.
This function filters slices (roi_data) where the number of non-zero voxels within the ROI slice (e.g. centerline, SC segmentation) is inferior or equal to a given threshold (nb_nonzero_thr).
- Parameters
roi_data (nd.array) – ROI slice.
nb_nonzero_thr (int) – Threshold.
- Returns
True if the slice needs to be filtered, False otherwise.
- Return type
bool
- orient_img_hwd(data: numpy.ndarray, slice_axis: int) numpy.ndarray [source]
Orient a given RAS image to height, width, depth according to slice axis.
- Parameters
data (ndarray) – RAS oriented data.
slice_axis (int) – Indicates the axis used for the 2D slice extraction: Sagittal: 0, Coronal: 1, Axial: 2.
- Returns
Array oriented with the following dimensions: (height, width, depth).
- Return type
ndarray
- orient_img_ras(data: numpy.ndarray, slice_axis: int) numpy.ndarray [source]
Orient a given array with dimensions (height, width, depth) to RAS orientation.
- Parameters
data (ndarray) – Data with following dimensions (Height, Width, Depth).
slice_axis (int) – Indicates the axis used for the 2D slice extraction: Sagittal: 0, Coronal: 1, Axial: 2.
- Returns
Array oriented in RAS.
- Return type
ndarray
- orient_shapes_hwd(data: list | tuple, slice_axis: int) numpy.ndarray [source]
Swap dimensions according to match the height, width, depth orientation.
- Parameters
data (list or tuple) – Shape or numbers associated with each image dimension (e.g. image resolution).
slice_axis (int) – Indicates the axis used for the 2D slice extraction: Sagittal: 0, Coronal: 1, Axial: 2.
- Returns
Reoriented vector.
- Return type
ndarray
- update_metadata(metadata_src_lst: list, metadata_dest_lst: list) list [source]
Update metadata keys with a reference metadata.
A given list of metadata keys will be changed and given the values of the reference metadata.
- Parameters
metadata_src_lst (list) – List of source metadata used as reference for the destination metadata.
metadata_dest_lst (list) – List of metadate that needs to be updated.
- Returns
updated metadata list.
- Return type
list
- reorient_image(arr: np.ndarray, slice_axis: int, nib_ref: nib, nib_ref_canonical: nib) nd.ndarray [source]
Reorient an image to match a reference image orientation.
It reorients a array to a given orientation and convert it to a nibabel object using the reference nibabel header.
- Parameters
arr (ndarray) – Input array, array to re orient.
slice_axis (int) – Indicates the axis used for the 2D slice extraction: Sagittal: 0, Coronal: 1, Axial: 2.
nib_ref (nibabel) – Reference nibabel object, whose header is used.
nib_ref_canonical (nibabel) – nib_ref that has been reoriented to canonical orientation (RAS).
- get_file_extension(filename: str) Optional[str] [source]
Get file extension if it is supported :param filename: Path of the file. :type filename: str
- Returns
File extension
- Return type
str
- update_filename_to_nifti(filename: str) str [source]
Update filename extension to ‘nii.gz’ if not a NifTI file.
This function is used to help make non-NifTI files (e.g. PNG/TIF/JPG) compatible with NifTI-only pipelines. The expectation is that a NifTI version of the file has been created alongside the original file, which allows the extension to be cleanly swapped for a .nii.gz extension.
- Parameters
filename (str) – Path of original file.
- Returns
Path of the corresponding NifTI file.
- Return type
str
- dropout_input(seg_pair: dict) dict [source]
Applies input-level dropout: zero to all channels minus one will be randomly set to zeros. This function verifies if some channels are already empty. Always at least one input channel will be kept.
- Parameters
seg_pair (dict) – Batch containing torch tensors (input and gt) and metadata.
- Returns
Batch containing torch tensors (input and gt) and metadata with channel(s) dropped.
- Return type
seg_pair (dict)
- create_temp_directory() str [source]
Creates a temporary directory and returns its path. This temporary directory is only deleted when explicitly requested.
- Returns
Path of the temporary directory.
- Return type
str
- get_obj_size(obj) int [source]
Returns the size of an object in bytes. Used to gauge whether storing object in memory vs write to disk.
Source: https://stackoverflow.com/a/53705610
- Parameters
obj –
Returns:
Object Detection API
object_detection.utils
- get_bounding_boxes(mask)[source]
Generates a 3D bounding box around a given mask. :param mask: Mask of the ROI. :type mask: Numpy array
- Returns
Bounding box coordinate (x_min, x_max, y_min, y_max, z_min, z_max).
- Return type
list
- adjust_bb_size(bounding_box, factor, resample=False)[source]
Modifies the bounding box dimensions according to a given factor.
- Parameters
bounding_box (list or tuple) – Coordinates of bounding box (x_min, x_max, y_min, y_max, z_min, z_max).
factor (list or tuple) – Multiplicative factor for each dimension (list or tuple of length 3).
resample (bool) – Boolean indicating if this resize is for resampling.
- Returns
New coordinates (x_min, x_max, y_min, y_max, z_min, z_max).
- Return type
list
- resize_to_multiple(shape, multiple, length)[source]
Modify a given shape so each dimension is a multiple of a given number. This is used to avoid dimension mismatch with patch training. The return shape is always larger then the initial shape (no cropping).
- Parameters
shape (tuple or list) – Initial shape to be modified.
multiple (tuple or list) – Multiple for each dimension.
length (tuple or list) – Patch length.
- Returns
New dimensions.
- Return type
list
- generate_bounding_box_file(subject_path_list, model_path, path_output, gpu_id=0, slice_axis=0, contrast_lst=None, keep_largest_only=True, safety_factor=None)[source]
Creates json file containing the bounding box dimension for each images. The file has the following format: {“path/to/img.nii.gz”: [[x1_min, x1_max, y1_min, y1_max, z1_min, z1_max], [x2_min, x2_max, y2_min, y2_max, z2_min, z2_max]]} where each list represents the coordinates of an object on the image (2 instance of a given object in this example).
- Parameters
subject_path_list (list) – List of all subjects in all the BIDS directories.
model_path (string) – Path to object detection model.
path_output (string) – Output path.
gpu_id (int) – If available, GPU number.
slice_axis (int) – Slice axis (0: sagittal, 1: coronal, 2: axial).
contrast_lst (list) – Contrasts.
keep_largest_only (bool) – Boolean representing if only the largest object of the prediction is kept.
safety_factor (list or tuple) – Factors to multiply each dimension of the bounding box.
- Returns
Dictionary containing bounding boxes related to their image.
- Return type
dict
- resample_bounding_box(metadata, transform)[source]
Resample bounding box.
- Parameters
metadata (dict) – Dictionary containing the metadata to be modified with the resampled coordinates.
transform (Compose) – Transformations possibly containing the resample params.
- adjust_transforms(transforms, seg_pair, length=None, stride=None)[source]
This function adapts the transforms by adding the BoundingBoxCrop transform according the specific parameters of an image. The dimensions of the crop are also adapted to fit the length and stride parameters if the 3D loader is used.
- adjust_undo_transforms(transforms, seg_pair, index=0)[source]
This function adapts the undo transforms by adding the BoundingBoxCrop to undo transform according the specific parameters of an image.
- Parameters
transforms (Compose) – Transforms.
seg_pair (dict) – Segmentation pair (input, gt and metadata).
index (int) – Batch index of the seg_pair.
- load_bounding_boxes(object_detection_params, subject_path_list, slice_axis, constrast_lst)[source]
Verifies if bounding_box.json exists in the output path, if so loads the data, else generates the file if a valid detection model path exists.
- Parameters
object_detection_params (dict) – Object detection parameters.
subject_path_list (list) – List of all subjects in all the BIDS directories.
slice_axis (int) – Slice axis (0: sagittal, 1: coronal, 2: axial).
constrast_lst (list) – Contrasts.
- Returns
bounding boxes for every subject in BIDS directory
- Return type
dict
- verify_metadata(metadata, has_bounding_box)[source]
Validates across all metadata that the ‘bounding_box’ param is present.
- Parameters
metadata (dict) – Image metadata.
has_bounding_box (bool) – If ‘bounding_box’ is present across all metadata, True, else False.
- Returns
Boolean indicating if ‘bounding_box’ is present across all metadata.
- Return type
bool
- bounding_box_prior(fname_mask, metadata, slice_axis, safety_factor=None)[source]
Computes prior steps to a model requiring bounding box crop. This includes loading a mask of the ROI, orienting the given mask into the following dimensions: (height, width, depth), extracting the bounding boxes and storing the information in the metadata.
- Parameters
fname_mask (str) – Filename containing the mask of the ROI
metadata (dict) – Dictionary containing the image metadata
slice_axis (int) – Slice axis (0: sagittal, 1: coronal, 2: axial)
safety_factor (list or tuple) – Factors to multiply each dimension of the bounding box.
Evaluation API
- evaluate(bids_df, path_output, target_suffix, eval_params)[source]
Evaluate predictions from inference step.
- Parameters
bids_df (BidsDataframe) – Object containing dataframe with all BIDS image files and their metadata.
path_output (str) – Folder where the output folder “results_eval” is be created.
target_suffix (list) – List of suffixes that indicates the target mask(s).
eval_params (dict) – Evaluation parameters.
- Returns
results for each image.
- Return type
pd.Dataframe
- class Evaluation3DMetrics(data_pred, data_gt, dim_lst, params=None)[source]
Bases:
object
Computes 3D evaluation metrics.
- Parameters
data_pred (ndarray) – Network prediction mask.
data_gt (ndarray) – Ground-truth mask.
dim_lst (list) – Resolution (mm) along each dimension.
params (dict) – Evaluation parameters.
- Attributes
data_pred (ndarray) – Network prediction mask.
data_gt (ndarray) – Ground-truth mask.
n_classes (int) – Number of classes.
px (float) – Resolution (mm) along the first axis.
py (float) – Resolution (mm) along the second axis.
pz (float) – Resolution (mm) along the third axis.
bin_struct (ndarray) – Binary structure.
size_min (int) – Minimum size of objects. Objects that are smaller than this limit can be removed if “removeSmall” is in params.
object_detection_metrics (bool) – Indicate if object detection metrics (lesions true positive and false detection rates) are computed or not.
overlap_vox (int) – A prediction and ground-truth are considered as overlapping if they overlap for at least this amount of voxels.
overlap_ratio (float) – A prediction and ground-truth are considered as overlapping if they overlap for at least this portion of their volumes.
data_pred_label (ndarray) – Network prediction mask that is labeled, ie each object is filled with a different value.
data_gt_label (ndarray) – Ground-truth mask that is labeled, ie each object is filled with a different value.
n_pred (int) – Number of objects in the network prediction mask.
n_gt (int) – Number of objects in the ground-truth mask.
data_painted (ndarray) – Mask where each predicted object is labeled depending on whether it is a TP or FP.
- label_per_size(data)[source]
Get data with labels corresponding to label size.
- Parameters
data (ndarray) – Input data.
- Returns
ndarray
- get_rvd()[source]
Relative volume difference.
The volume is here defined by the physical volume, in mm3, of the non-zero voxels of a given mask. Relative volume difference equals the difference between the ground-truth and prediction volumes, divided by the ground-truth volume. Optimal value is zero. Negative value indicates over-segmentation, while positive value indicates under-segmentation.
- get_avd()[source]
Absolute volume difference.
The volume is here defined by the physical volume, in mm3, of the non-zero voxels of a given mask. Absolute volume difference equals the absolute value of the Relative Volume Difference. Optimal value is zero.
- get_ltpr(label_size=None, class_idx=0)[source]
Lesion True Positive Rate / Recall / Sensitivity.
- Parameters
label_size (int) – Size of label.
class_idx (int) – Label index. If monolabel 0, else ranges from 0 to number of output channels - 1.
Note: computed only if n_obj >= 1 and “object_detection_metrics” evaluation parameter is True.
- get_lfdr(label_size=None, class_idx=0)[source]
Lesion False Detection Rate / 1 - Precision.
- Parameters
label_size (int) – Size of label.
class_idx (int) – Label index. If monolabel 0, else ranges from 0 to number of output channels - 1.
Note: computed only if n_obj >= 1 and “object_detection_metrics” evaluation parameter is True.
Losses API
- class MultiClassDiceLoss(classes_of_interest=None)[source]
Bases:
torch.nn.modules.module.Module
Multi-class Dice Loss.
Inspired from https://arxiv.org/pdf/1802.10508.
- Parameters
classes_of_interest (list) – List containing the index of a class which its dice will be added to the loss. If is None all classes are considered.
- Attributes
classes_of_interest (list) – List containing the index of a class which its dice will be added to the loss. If is None all classes are considered.
dice_loss (DiceLoss) – Class computing the Dice loss.
Initializes internal Module state, shared by both nn.Module and ScriptModule.
- __init__(classes_of_interest=None)[source]
Initializes internal Module state, shared by both nn.Module and ScriptModule.
- forward(prediction, target)[source]
Defines 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 DiceLoss(smooth=1.0)[source]
Bases:
torch.nn.modules.module.Module
DiceLoss.
See also
Milletari, Fausto, Nassir Navab, and Seyed-Ahmad Ahmadi. “V-net: Fully convolutional neural networks for volumetric medical image segmentation.” 2016 fourth international conference on 3D vision (3DV). IEEE, 2016.
- Parameters
smooth (float) – Value to avoid division by zero when images and predictions are empty.
- Attributes
smooth (float) – Value to avoid division by zero when images and predictions are empty.
Initializes internal Module state, shared by both nn.Module and ScriptModule.
- __init__(smooth=1.0)[source]
Initializes internal Module state, shared by both nn.Module and ScriptModule.
- forward(prediction, target)[source]
Defines 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 BinaryCrossEntropyLoss[source]
Bases:
torch.nn.modules.module.Module
- Attributes
loss_fct (BCELoss) – Binary cross entropy loss function from torch library.
Initializes internal Module state, shared by both nn.Module and ScriptModule.
- forward(prediction, target)[source]
Defines 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 FocalLoss(gamma=2, alpha=0.25, eps=1e-07)[source]
Bases:
torch.nn.modules.module.Module
FocalLoss.
See also
Lin, Tsung-Yi, et al. “Focal loss for dense object detection.” Proceedings of the IEEE international conference on computer vision. 2017.
- Parameters
gamma (float) – Value from 0 to 5, Control between easy background and hard ROI training examples. If set to 0, equivalent to cross-entropy.
alpha (float) – Value from 0 to 1, usually corresponding to the inverse of class frequency to address class imbalance.
eps (float) – Epsilon to avoid division by zero.
- Attributes
gamma (float) – Value from 0 to 5, Control between easy background and hard ROI training examples. If set to 0, equivalent to cross-entropy.
alpha (float) – Value from 0 to 1, usually corresponding to the inverse of class frequency to address class imbalance.
eps (float) – Epsilon to avoid division by zero.
Initializes internal Module state, shared by both nn.Module and ScriptModule.
- __init__(gamma=2, alpha=0.25, eps=1e-07)[source]
Initializes internal Module state, shared by both nn.Module and ScriptModule.
- forward(input, target)[source]
Defines 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 FocalDiceLoss(beta=1, gamma=2, alpha=0.25)[source]
Bases:
torch.nn.modules.module.Module
FocalDiceLoss.
See also
Wong, Ken CL, et al. “3D segmentation with exponential logarithmic loss for highly unbalanced object sizes.” International Conference on Medical Image Computing and Computer-Assisted Intervention. Springer, Cham, 2018.
- Parameters
beta (float) – Value from 0 to 1, indicating the weight of the dice loss.
gamma (float) – Value from 0 to 5, Control between easy background and hard ROI training examples. If set to 0, equivalent to cross-entropy.
alpha (float) – Value from 0 to 1, usually corresponding to the inverse of class frequency to address class imbalance.
- Attributes
beta (float) – Value from 0 to 1, indicating the weight of the dice loss.
gamma (float) – Value from 0 to 5, Control between easy background and hard ROI training examples. If set to 0, equivalent to cross-entropy.
alpha (float) – Value from 0 to 1, usually corresponding to the inverse of class frequency to address class imbalance.
Initializes internal Module state, shared by both nn.Module and ScriptModule.
- __init__(beta=1, gamma=2, alpha=0.25)[source]
Initializes internal Module state, shared by both nn.Module and ScriptModule.
- forward(input, target)[source]
Defines 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 GeneralizedDiceLoss(epsilon=1e-05, include_background=True)[source]
Bases:
torch.nn.modules.module.Module
GeneralizedDiceLoss.
See also
Sudre, Carole H., et al. “Generalised dice overlap as a deep learning loss function for highly unbalanced segmentations.” Deep learning in medical image analysis and multimodal learning for clinical decision support. Springer, Cham, 2017. 240-248.
- Parameters
epsilon (float) – Epsilon to avoid division by zero.
include_background (bool) – If True, then an extra channel is added, which represents the background class.
- Attributes
epsilon (float) – Epsilon to avoid division by zero.
include_background (bool) – If True, then an extra channel is added, which represents the background class.
Initializes internal Module state, shared by both nn.Module and ScriptModule.
- __init__(epsilon=1e-05, include_background=True)[source]
Initializes internal Module state, shared by both nn.Module and ScriptModule.
- forward(input, target)[source]
Defines 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 TverskyLoss(alpha=0.7, beta=0.3, smooth=1.0)[source]
Bases:
torch.nn.modules.module.Module
Tversky Loss.
See also
Salehi, Seyed Sadegh Mohseni, Deniz Erdogmus, and Ali Gholipour. “Tversky loss function for image segmentation using 3D fully convolutional deep networks.” International Workshop on Machine Learning in Medical Imaging. Springer, Cham, 2017.
- Parameters
alpha (float) – Weight of false positive voxels.
beta (float) – Weight of false negative voxels.
smooth (float) – Epsilon to avoid division by zero, when both Numerator and Denominator of Tversky are zeros.
- Attributes
alpha (float) – Weight of false positive voxels.
beta (float) – Weight of false negative voxels.
smooth (float) – Epsilon to avoid division by zero, when both Numerator and Denominator of Tversky are zeros.
Notes
setting alpha=beta=0.5: Equivalent to DiceLoss.
default parameters were suggested by https://arxiv.org/pdf/1706.05721.pdf .
Initializes internal Module state, shared by both nn.Module and ScriptModule.
- __init__(alpha=0.7, beta=0.3, smooth=1.0)[source]
Initializes internal Module state, shared by both nn.Module and ScriptModule.
- tversky_index(y_pred, y_true)[source]
Compute Tversky index.
- Parameters
y_pred (torch Tensor) – Prediction.
y_true (torch Tensor) – Target.
- Returns
Tversky index.
- Return type
float
- forward(input, target)[source]
Defines 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 FocalTverskyLoss(alpha=0.7, beta=0.3, gamma=1.33, smooth=1.0)[source]
Bases:
ivadomed.losses.TverskyLoss
Focal Tversky Loss.
See also
Abraham, Nabila, and Naimul Mefraz Khan. “A novel focal tversky loss function with improved attention u-net for lesion segmentation.” 2019 IEEE 16th International Symposium on Biomedical Imaging (ISBI 2019). IEEE, 2019.
- Parameters
alpha (float) – Weight of false positive voxels.
beta (float) – Weight of false negative voxels.
gamma (float) – Typically between 1 and 3. Control between easy background and hard ROI training examples.
smooth (float) – Epsilon to avoid division by zero, when both Numerator and Denominator of Tversky are zeros.
- Attributes
gamma (float) – Typically between 1 and 3. Control between easy background and hard ROI training examples.
Notes
setting alpha=beta=0.5 and gamma=1: Equivalent to DiceLoss.
default parameters were suggested by https://arxiv.org/pdf/1810.07842.pdf .
Initializes internal Module state, shared by both nn.Module and ScriptModule.
- __init__(alpha=0.7, beta=0.3, gamma=1.33, smooth=1.0)[source]
Initializes internal Module state, shared by both nn.Module and ScriptModule.
- forward(input, target)[source]
Defines 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 L2loss[source]
Bases:
torch.nn.modules.module.Module
Euclidean loss also known as L2 loss. Compute the sum of the squared difference between the two images.
Initializes internal Module state, shared by both nn.Module and ScriptModule.
- forward(input, target)[source]
Defines 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 AdapWingLoss(theta=0.5, alpha=2.1, omega=14, epsilon=1)[source]
Bases:
torch.nn.modules.module.Module
Adaptive Wing loss Used for heatmap ground truth.
See also
Wang, Xinyao, Liefeng Bo, and Li Fuxin. “Adaptive wing loss for robust face alignment via heatmap regression.” Proceedings of the IEEE International Conference on Computer Vision. 2019.
- Parameters
theta (float) – Threshold between linear and non linear loss.
alpha (float) – Used to adapt loss shape to input shape and make loss smooth at 0 (background).
properties. (It needs to be slightly above 2 to maintain ideal) –
omega (float) – Multiplicating factor for non linear part of the loss.
epsilon (float) – factor to avoid gradient explosion. It must not be too small
Initializes internal Module state, shared by both nn.Module and ScriptModule.
- __init__(theta=0.5, alpha=2.1, omega=14, epsilon=1)[source]
Initializes internal Module state, shared by both nn.Module and ScriptModule.
- forward(input, target)[source]
Defines 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 LossCombination(losses_list, params_list=None)[source]
Bases:
torch.nn.modules.module.Module
Loss that sums other implemented losses.
- Parameters
losses_list (list) – list of losses that will be summed. Elements should be string.
params_list (list) – list of params for the losses, contain None or dictionnary definition of params for the loss
used. (at same index. If no params list is given all default parameter will be) –
(e.g. – params_list = [None,{“param1:0.5”}])
["L2loss" (losses_list =) – params_list = [None,{“param1:0.5”}])
"DiceLoss"] – params_list = [None,{“param1:0.5”}])
- Returns
sum of losses computed on (input,target) with the params
- Return type
tensor
Initializes internal Module state, shared by both nn.Module and ScriptModule.
- __init__(losses_list, params_list=None)[source]
Initializes internal Module state, shared by both nn.Module and ScriptModule.
- forward(input, target)[source]
Defines 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.
Main API
- run_command(context, n_gif=0, thr_increment=None, resume_training=False, no_patch=False, overlap_2d=None)[source]
Run main command.
This function is central in the ivadomed project as training / testing / evaluation commands are run via this function. All the process parameters are defined in the config.
- Parameters
context (dict) – Dictionary containing all parameters that are needed for a given process. See Configuration File for more details.
n_gif (int) – Generates a GIF during training if larger than zero, one frame per epoch for a given slice. The parameter indicates the number of 2D slices used to generate GIFs, one GIF per slice. A GIF shows predictions of a given slice from the validation sub-dataset. They are saved within the output path.
thr_increment (float) – A threshold analysis is performed at the end of the training using the trained model and the training + validation sub-dataset to find the optimal binarization threshold. The specified value indicates the increment between 0 and 1 used during the ROC analysis (e.g. 0.1).
resume_training (bool) – Load a saved model (“checkpoint.pth.tar” in the output directory specified with flag “–path-output” or via the config file “output_path”. This training state is saved everytime a new best model is saved in the log argument) for resume training directory.
no_patch (bool) – If True, 2D patches are not used while segmenting with models trained with patches (command “–segment” only). Default: False (i.e. segment with patches). The “no_patch” option supersedes the “overlap_2D” option.
overlap_2d (list of int) – Custom overlap for 2D patches while segmenting (command “–segment” only). Default model overlap is used otherwise.
- Returns
If “train” command: Returns floats: best loss score for both training and validation.
If “test” command: Returns a pandas Dataframe: of metrics computed for each subject of the testing sub-dataset and return the prediction metrics before evaluation.
If “segment” command: No return value.
- Return type
float or pandas.DataFrame or None
Metrics API
- class MetricManager(metric_fns)[source]
Bases:
object
Computes specified metrics and stores them in a dictionary.
- Parameters
metric_fns (list) – List of metric functions.
- Attributes
metric_fns (list) – List of metric functions.
result_dict (dict) – Dictionary storing metrics.
num_samples (int) – Number of samples.
- numeric_score(prediction, groundtruth)[source]
Computation of statistical numerical scores:
FP = Soft False Positives
FN = Soft False Negatives
TP = Soft True Positives
TN = Soft True Negatives
- Robust to hard or soft input masks. For example::
prediction=np.asarray([0, 0.5, 1]) groundtruth=np.asarray([0, 1, 1]) Leads to FP = 1.5
Note: It assumes input values are between 0 and 1.
- Parameters
prediction (ndarray) – Binary prediction.
groundtruth (ndarray) – Binary groundtruth.
- Returns
FP, FN, TP, TN
- Return type
float, float, float, float
- dice_score(im1, im2, empty_score=nan)[source]
Computes the Dice coefficient between im1 and im2.
Compute a soft Dice coefficient between im1 and im2, ie equals twice the sum of the two masks product, divided by the sum of each mask sum. If both images are empty, then it returns empty_score.
- Parameters
im1 (ndarray) – First array.
im2 (ndarray) – Second array.
empty_score (float) – Returned value if both input array are empty.
- Returns
Dice coefficient.
- Return type
float
- mse(im1, im2)[source]
Compute the Mean Squared Error.
Compute the Mean Squared Error between the two images, i.e. sum of the squared difference.
- Parameters
im1 (ndarray) – First array.
im2 (ndarray) – Second array.
- Returns
Mean Squared Error.
- Return type
float
- hausdorff_score(prediction, groundtruth)[source]
Compute the directed Hausdorff distance between two N-D arrays.
- Parameters
prediction (ndarray) – First array.
groundtruth (ndarray) – Second array.
- Returns
Hausdorff distance.
- Return type
float
- precision_score(prediction, groundtruth, err_value=0.0)[source]
Positive predictive value (PPV).
Precision equals the number of true positive voxels divided by the sum of true and false positive voxels. True and false positives are computed on soft masks, see
"numeric_score"
.- Parameters
prediction (ndarray) – First array.
groundtruth (ndarray) – Second array.
err_value (float) – Value returned in case of error.
- Returns
Precision score.
- Return type
float
- recall_score(prediction, groundtruth, err_value=0.0)[source]
True positive rate (TPR).
Recall equals the number of true positive voxels divided by the sum of true positive and false negative voxels. True positive and false negative values are computed on soft masks, see
"numeric_score"
.- Parameters
prediction (ndarray) – First array.
groundtruth (ndarray) – Second array.
err_value (float) – Value returned in case of error.
- Returns
Recall score.
- Return type
float
- specificity_score(prediction, groundtruth, err_value=0.0)[source]
True negative rate (TNR).
Specificity equals the number of true negative voxels divided by the sum of true negative and false positive voxels. True negative and false positive values are computed on soft masks, see
"numeric_score"
.- Parameters
prediction (ndarray) – First array.
groundtruth (ndarray) – Second array.
err_value (float) – Value returned in case of error.
- Returns
Specificity score.
- Return type
float
- intersection_over_union(prediction, groundtruth, err_value=0.0)[source]
Intersection of two (soft) arrays over their union (IoU).
- Parameters
prediction (ndarray) – First array.
groundtruth (ndarray) – Second array.
err_value (float) – Value returned in case of error.
- Returns
IoU.
- Return type
float
- accuracy_score(prediction, groundtruth, err_value=0.0)[source]
Accuracy.
Accuracy equals the number of true positive and true negative voxels divided by the total number of voxels. True positive/negative and false positive/negative values are computed on soft masks, see
"numeric_score"
.- Parameters
prediction (ndarray) – First array.
groundtruth (ndarray) – Second array.
- Returns
Accuracy.
- Return type
float
- multi_class_dice_score(im1, im2)[source]
Dice score for multi-label images.
Multi-class Dice score equals the average of the Dice score for each class. The first dimension of the input arrays is assumed to represent the classes.
- Parameters
im1 (ndarray) – First array.
im2 (ndarray) – Second array.
- Returns
Multi-class dice.
- Return type
float
Postprocessing API
- nifti_capable(wrapped)[source]
Decorator to make a given function compatible with input being Nifti objects.
- Parameters
wrapped – Given function.
- Returns
Functions’ return.
- binarize_with_low_threshold(wrapped)[source]
Decorator to set low values (< 0.001) to 0.
- Parameters
wrapped – Given function.
- Returns
Functions’ return.
- multilabel_capable(wrapped)[source]
Decorator to make a given function compatible multilabel images.
- Parameters
wrapped – Given function.
- Returns
Functions’ return.
- threshold_predictions(predictions, thr=0.5)[source]
Threshold a soft (i.e. not binary) array of predictions given a threshold value, and returns a binary array.
- Parameters
predictions (ndarray or nibabel object) – Image to binarize.
thr (float) – Threshold value: voxels with a value < to thr are assigned 0 as value, 1 otherwise.
- Returns
ndarray or nibabel (same object as the input) containing only zeros or ones. Output type is int.
- Return type
ndarray
- keep_largest_object(predictions)[source]
Keep the largest connected object from the input array (2D or 3D).
- Parameters
predictions (ndarray or nibabel object) – Input segmentation. Image could be 2D or 3D.
- Returns
ndarray or nibabel (same object as the input).
- keep_largest_object_per_slice(predictions, axis=2)[source]
Keep the largest connected object for each 2D slice, along a specified axis.
- Parameters
predictions (ndarray or nibabel object) – Input segmentation. Image could be 2D or 3D.
axis (int) – 2D slices are extracted along this axis.
- Returns
ndarray or nibabel (same object as the input).
- fill_holes(predictions, structure=(3, 3, 3))[source]
Fill holes in the predictions using a given structuring element. Note: This function only works for binary segmentation.
- Parameters
predictions (ndarray or nibabel object) – Input binary segmentation. Image could be 2D or 3D.
structure (tuple of integers) – Structuring element, number of ints equals number of dimensions in the input array.
- Returns
ndrray or nibabel (same object as the input). Output type is int.
- mask_predictions(predictions, mask_binary)[source]
Mask predictions using a binary mask: sets everything outside the mask to zero.
- Parameters
predictions (ndarray or nibabel object) – Input binary segmentation. Image could be 2D or 3D.
mask_binary (ndarray) – Numpy array with the same shape as predictions, containing only zeros or ones.
- Returns
ndarray or nibabel (same object as the input).
- coordinate_from_heatmap(nifti_image, thresh=0.3)[source]
Retrieve coordinates of local maxima in a soft segmentation. :param nifti_image: nifti image of the soft segmentation. :type nifti_image: nibabel object :param thresh: Relative threshold for local maxima, i.e., after normalizing :type thresh: float :param the min and max between 0 and 1: :param respectively.:
- Returns
A list of computed coordinates found by local maximum. each element will be a list composed of [x, y, z]
- Return type
list
- label_file_from_coordinates(nifti_image, coord_list)[source]
Creates a nifti object with single-voxel labels. Each label has a value of 1. The nifti object as the same orientation as the input. :param nifti_image: Path to the image which affine matrix will be used to generate a new image with :type nifti_image: nibabel object :param labels.: :param coord_list: list of coordinates. Each element is [x, y, z]. Orientation should be the same as the image :type coord_list: list
- Returns
A nifti object containing the singe-voxel label of value 1. The matrix will be the same size as nifti_image.
- Return type
nib_pred
- remove_small_objects(data, bin_structure, size_min)[source]
Removes all unconnected objects smaller than the minimum specified size.
- Parameters
data (ndarray) – Input data.
bin_structure (ndarray) – Structuring element that defines feature connections.
size_min (int) – Minimal object size to keep in input data.
- Returns
Array with small objects.
- Return type
ndarray
- class Postprocessing(postprocessing_params, data_pred, dim_lst, filename_prefix)[source]
Bases:
object
Postprocessing steps manager
- Parameters
postprocessing_params (dict) – Indicates postprocessing steps (in the right order)
data_pred (ndarray) – Prediction from the model.
dim_lst (list) – Dimensions of a voxel in mm.
filename_prefix (str) – Path to prediction file without suffix.
- Attributes
postprocessing_params (dict) – Indicates postprocessing steps (in the right order)
data_pred (ndarray) – Prediction from the model.
px (float) – Resolution (mm) along the first axis.
py (float) – Resolution (mm) along the second axis.
pz (float) – Resolution (mm) along the third axis.
filename_prefix (str) – Path to prediction file without suffix.
n_classes (int) – Number of classes.
bin_struct (ndarray) – Binary structure.
- binarize_maxpooling()[source]
Binarize by setting to 1 the voxel having the max prediction across all classes.
- uncertainty(thr, suffix)[source]
Removes the most uncertain predictions.
- Parameters
thr (float) – Uncertainty threshold.
suffix (str) – Suffix of uncertainty filename.
Testing API
- test(model_params, dataset_test, testing_params, path_output, device, cuda_available=True, metric_fns=None, postprocessing=None)[source]
Main command to test the network.
- Parameters
model_params (dict) – Model’s parameters.
dataset_test (imed_loader) – Testing dataset.
testing_params (dict) – Testing parameters.
path_output (str) – Folder where predictions are saved.
device (torch.device) – Indicates the CPU or GPU ID.
cuda_available (bool) – If True, CUDA is available.
metric_fns (list) – List of metrics, see
ivadomed.metrics
.postprocessing (dict) – Contains postprocessing steps.
- Returns
result metrics.
- Return type
dict
- run_inference(test_loader, model, model_params, testing_params, ofolder, cuda_available, i_monte_carlo=None, postprocessing=None)[source]
Run inference on the test data and save results as nibabel files.
- Parameters
test_loader (torch DataLoader) –
model (nn.Module) –
model_params (dict) –
testing_params (dict) –
ofolder (str) – Folder where predictions are saved.
cuda_available (bool) – If True, CUDA is available.
i_monte_carlo (int) – i_th Monte Carlo iteration.
postprocessing (dict) – Indicates postprocessing steps.
- Returns
Prediction, Ground-truth of shape n_sample, n_label, h, w, d.
- Return type
ndarray, ndarray
- threshold_analysis(model_path, ds_lst, model_params, testing_params, metric='dice', increment=0.1, fname_out='thr.png', cuda_available=True)[source]
Run a threshold analysis to find the optimal threshold on a sub-dataset.
- Parameters
model_path (str) – Model path.
ds_lst (list) – List of loaders.
model_params (dict) – Model’s parameters.
testing_params (dict) – Testing parameters
metric (str) – Choice between “dice” and “recall_specificity”. If “recall_specificity”, then a ROC analysis is performed.
increment (float) – Increment between tested thresholds.
fname_out (str) – Plot output filename.
cuda_available (bool) – If True, CUDA is available.
- Returns
optimal threshold.
- Return type
float
Training API
- train(model_params, dataset_train, dataset_val, training_params, path_output, device, wandb_params=None, cuda_available=True, metric_fns=None, n_gif=0, resume_training=False, debugging=False)[source]
Main command to train the network.
- Parameters
model_params (dict) – Model’s parameters.
dataset_train (imed_loader) – Training dataset.
dataset_val (imed_loader) – Validation dataset.
training_params (dict) –
path_output (str) – Folder where log files, best and final models are saved.
device (str) – Indicates the CPU or GPU ID.
cuda_available (bool) – If True, CUDA is available.
metric_fns (list) – List of metrics, see
ivadomed.metrics
.n_gif (int) – Generates a GIF during training if larger than zero, one frame per epoch for a given slice. The parameter indicates the number of 2D slices used to generate GIFs, one GIF per slice. A GIF shows predictions of a given slice from the validation sub-dataset. They are saved within the output path.
resume_training (bool) – Load a saved model (“checkpoint.pth.tar” in the path_output) for resume training. This training state is saved everytime a new best model is saved in the log directory.
debugging (bool) – If True, extended verbosity and intermediate outputs.
- Returns
- best_training_dice, best_training_loss, best_validation_dice,
best_validation_loss.
- Return type
float, float, float, float
- get_sampler(ds, balance_bool, metadata)[source]
Get sampler.
- Parameters
ds (BidsDataset) – BidsDataset object.
balance_bool (bool) – If True, a sampler is generated that balance positive and negative samples.
- Returns
Returns BalancedSampler, Bool: Sampler and boolean for shuffling (set to False). Otherwise: Returns None and True.
- Return type
If balance_bool is True
- get_scheduler(params, optimizer, num_epochs=0)[source]
Get scheduler.
- Parameters
params (dict) – scheduler parameters, see PyTorch documentation
optimizer (torch optim) –
num_epochs (int) – number of epochs.
- Returns
torch.optim, bool, which indicates if the scheduler is updated for each batch (True), or for each epoch (False).
- get_loss_function(params)[source]
Get Loss function.
- Parameters
params (dict) – See
ivadomed.losses
.- Returns
imed_losses object.
- get_metadata(metadata, model_params)[source]
Get metadata during batch loop.
- Parameters
metadata (batch) –
model_params (dict) –
- Returns
If FiLMedUnet, Returns a list of metadata, that have been transformed by the One Hot Encoder. If HeMISUnet, Returns a numpy array where each row represents a sample and each column represents a contrast.
- load_checkpoint(model, optimizer, gif_dict, scheduler, fname)[source]
Load checkpoint.
This function check if a checkpoint is available. If so, it updates the state of the input objects.
- Parameters
model (nn.Module) – Init model.
optimizer (torch.optim) – Model’s optimizer.
gif_dict (dict) – Dictionary containing a GIF of the training.
scheduler (_LRScheduler) – Learning rate scheduler.
fname (str) – Checkpoint filename.
- Returns
nn.Module, torch, dict, int, float, _LRScheduler, int
Transformations API
- multichannel_capable(wrapped)[source]
Decorator to make a given function compatible multichannel images.
- Parameters
wrapped – Given function.
- Returns
Functions’ return.
- two_dim_compatible(wrapped)[source]
Decorator to make a given function compatible 2D or 3D images.
- Parameters
wrapped – Given function.
- Returns
Functions’ return.
- class Compose(dict_transforms, requires_undo=False)[source]
Bases:
object
Composes transforms together.
Composes transforms together and split between images, GT and ROI.
- self.transform is a dict:
keys: “im”, “gt” and “roi”
values torchvision_transform.Compose objects.
- Attributes
dict_transforms (dict) – Dictionary where the keys are the transform names and the value their parameters.
requires_undo (bool) – If True, does not include transforms which do not have an undo_transform implemented yet.
- Parameters
transform (dict) – Keys are “im”, “gt”, “roi” and values are torchvision_transforms.Compose of the transformations of interest.
- class UndoCompose(compose)[source]
Bases:
object
Undo the Compose transformations.
Call the undo transformations in the inverse order than the “do transformations”.
- Attributes
compose (torchvision_transforms.Compose)
- Parameters
transforms (torchvision_transforms.Compose) –
- class UndoTransform(transform)[source]
Bases:
object
Call undo transformation.
- Attributes
transform (ImedTransform)
- Parameters
transform (ImedTransform) –
- class NumpyToTensor[source]
Bases:
ivadomed.transforms.ImedTransform
Converts nd array to tensor object.
- class Resample(hspace, wspace, dspace=1.0)[source]
Bases:
ivadomed.transforms.ImedTransform
Resample image to a given resolution.
- Parameters
hspace (float) – Resolution along the first axis, in mm.
wspace (float) – Resolution along the second axis, in mm.
dspace (float) – Resolution along the third axis, in mm.
interpolation_order (int) – Order of spline interpolation. Set to 0 for label data. Default=2.
- class NormalizeInstance[source]
Bases:
ivadomed.transforms.ImedTransform
Normalize a tensor or an array image with mean and standard deviation estimated from the sample itself.
- class CroppableArray[source]
Bases:
numpy.ndarray
Zero padding slice past end of array in numpy.
Adapted From: https://stackoverflow.com/a/41155020/13306686
- class Crop(size)[source]
Bases:
ivadomed.transforms.ImedTransform
Crop data.
- Parameters
size (tuple of int) – Size of the output sample. Tuple of size 2 if dealing with 2D samples, 3 with 3D samples.
- Attributes
size (tuple of int) – Size of the output sample. Tuple of size 3.
- class CenterCrop(size)[source]
Bases:
ivadomed.transforms.Crop
Make a centered crop of a specified size.
- class ROICrop(size)[source]
Bases:
ivadomed.transforms.Crop
Make a crop of a specified size around a Region of Interest (ROI).
- class DilateGT(dilation_factor)[source]
Bases:
ivadomed.transforms.ImedTransform
Randomly dilate a ground-truth tensor.
- Parameters
dilation_factor (float) – Controls the number of dilation iterations. For each individual lesion, the number of
follows (dilation iterations is computed as) – nb_it = int(round(dilation_factor * sqrt(lesion_area)))
0 (If dilation_factor <=) –
performed. (then no dilation will be) –
- class BoundingBoxCrop(size)[source]
Bases:
ivadomed.transforms.Crop
Crops image according to given bounding box.
- class RandomAffine(degrees=0, translate=None, scale=None)[source]
Bases:
ivadomed.transforms.ImedTransform
Apply Random Affine transformation.
- Parameters
degrees (float) – Positive float or list (or tuple) of length two. Angles in degrees. If only a float is provided, then rotation angle is selected within the range [-degrees, degrees]. Otherwise, the list / tuple defines this range.
translate (list of float) – List of floats between 0 and 1, of length 2 or 3 depending on the sample shape (2D or 3D). These floats defines the maximum range of translation along each axis.
scale (list of float) – List of floats between 0 and 1, of length 2 or 3 depending on the sample shape (2D or 3D). These floats defines the maximum range of scaling along each axis.
- Attributes
degrees (tuple of floats)
translate (list of float)
scale (list of float)
- class RandomReverse[source]
Bases:
ivadomed.transforms.ImedTransform
Make a randomized symmetric inversion of the different values of each dimensions.
- class RandomShiftIntensity(shift_range, prob=0.1)[source]
Bases:
ivadomed.transforms.ImedTransform
Add a random intensity offset.
- Parameters
shift_range (tuple of floats) – Tuple of length two. Specifies the range where the offset that is applied is randomly selected from.
prob (float) – Between 0 and 1. Probability of occurence of this transformation.
- class ElasticTransform(alpha_range, sigma_range, p=0.1)[source]
Bases:
ivadomed.transforms.ImedTransform
Applies elastic transformation.
See also
Simard, Patrice Y., David Steinkraus, and John C. Platt. “Best practices for convolutional neural networks applied to visual document analysis.” Icdar. Vol. 3. No. 2003. 2003.
- Parameters
alpha_range (tuple of floats) – Deformation coefficient. Length equals 2.
sigma_range (tuple of floats) – Standard deviation. Length equals 2.
- class AdditiveGaussianNoise(mean=0.0, std=0.01)[source]
Bases:
ivadomed.transforms.ImedTransform
Adds Gaussian Noise to images.
- Parameters
mean (float) – Gaussian noise mean.
std (float) – Gaussian noise standard deviation.
- class Clahe(clip_limit=3.0, kernel_size=(8, 8))[source]
Bases:
ivadomed.transforms.ImedTransform
Applies Contrast Limited Adaptive Histogram Equalization for enhancing the local image contrast.
See also
Zuiderveld, Karel. “Contrast limited adaptive histogram equalization.” Graphics gems (1994): 474-485.
Default values are based on:
See also
Zheng, Qiao, et al. “3-D consistent and robust segmentation of cardiac images by deep learning with spatial propagation.” IEEE transactions on medical imaging 37.9 (2018): 2137-2148.
- Parameters
clip_limit (float) – Clipping limit, normalized between 0 and 1.
kernel_size (tuple of int) – Defines the shape of contextual regions used in the algorithm. Length equals image
dimension (ie 2 or 3 for 2D or 3D, respectively) –
- class HistogramClipping(min_percentile=5.0, max_percentile=95.0)[source]
Bases:
ivadomed.transforms.ImedTransform
Performs intensity clipping based on percentiles.
- Parameters
min_percentile (float) – Between 0 and 100. Lower clipping limit.
max_percentile (float) – Between 0 and 100. Higher clipping limit.
- class RandomGamma(log_gamma_range, p=0.5)[source]
Bases:
ivadomed.transforms.ImedTransform
Randomly changes the contrast of an image by gamma exponential
- Parameters
log_gamma_range (tuple of floats) – Log gamma range for changing contrast. Length equals 2.
p (float) – Probability of performing the gamma contrast
- class RandomBiasField(coefficients, order, p=0.5)[source]
Bases:
ivadomed.transforms.ImedTransform
Applies a random MRI bias field artifact to the image via torchio.RandomBiasField()
- Parameters
coefficients (float) – Maximum magnitude of polynomial coefficients
order – Order of the basis polynomial functions
p (float) – Probability of applying the bias field
- class RandomBlur(sigma_range, p=0.5)[source]
Bases:
ivadomed.transforms.ImedTransform
Applies a random blur to the image
- Parameters
sigma_range (tuple of floats) – Standard deviation range for the gaussian filter
p (float) – Probability of performing blur
- get_subdatasets_transforms(transform_params)[source]
Get transformation parameters for each subdataset: training, validation and testing.
- Parameters
transform_params (dict) –
- Returns
Training, Validation and Testing transformations.
- Return type
dict, dict, dict
- get_preprocessing_transforms(transforms)[source]
Checks the transformations parameters and selects the transformations which are done during preprocessing only.
- Parameters
transforms (dict) – Transformation dictionary.
- Returns
Preprocessing transforms.
- Return type
dict
- apply_preprocessing_transforms(transforms, seg_pair, roi_pair=None) Tuple[dict, dict] [source]
Applies preprocessing transforms to segmentation pair (input, gt and metadata).
- Parameters
transforms (Compose) – Preprocessing transforms.
seg_pair (dict) – Segmentation pair containing input and gt.
roi_pair (dict) – Segementation pair containing input and roi.
- Returns
Segmentation pair and roi pair.
- Return type
tuple
- prepare_transforms(transform_dict, requires_undo=True)[source]
This function separates the preprocessing transforms from the others and generates the undo transforms related.
- Parameters
transform_dict (dict) – Dictionary containing the transforms and there parameters.
requires_undo (bool) – Boolean indicating if transforms can be undone.
- Returns
- transform lst containing the preprocessing transforms and regular transforms, UndoCompose
object containing the transform to undo.
- Return type
list, UndoCompose
- tio_transform(x, transform)[source]
Applies TorchIO transformations to a given image and returns the transformed image and history.
- Parameters
x (np.ndarray) – input image
transform (tio.transforms.Transform) – TorchIO transform
- Returns
transformed image, history of parameters used for the applied transformation
- Return type
np.ndarray, list
Utils API
- class Metavar(value)[source]
Bases:
enum.Enum
This class is used to display intuitive input types via the metavar field of argparse.
- initialize_wandb(wandb_params)[source]
Initializes WandB and based upon the parameters sets it up or disables it for experimental tracking
- Parameters
wandb_params (dict) – wandb parameters
- Returns
True if wandb tracking is enabled
- Return type
bool, wandb_tracking
- cuda(input_var, cuda_available=True, non_blocking=False)[source]
Passes input_var to GPU.
- Parameters
input_var (Tensor) – either a tensor or a list of tensors.
cuda_available (bool) – If False, then return identity
non_blocking (bool) –
- Returns
Tensor
- unstack_tensors(sample)[source]
Unstack tensors.
- Parameters
sample (Tensor) –
- Returns
list of Tensors.
- Return type
list
- generate_sha_256(context: dict, df, file_lst: List[str]) None [source]
generate sha256 for a training file
- Parameters
context (dict) – configuration context.
df (pd.DataFrame) – Dataframe containing all BIDS image files indexed and their metadata.
file_lst (List[str]) – list of strings containing training files
- save_onnx_model(model, inputs, model_path)[source]
Convert PyTorch model to ONNX model and save it as model_path.
- Parameters
model (nn.Module) – PyTorch model.
inputs (Tensor) – Tensor, used to inform shape and axes.
model_path (str) – Output filename for the ONNX model.
- define_device(gpu_id)[source]
Define the device used for the process of interest.
- Parameters
gpu_id (int) – GPU ID.
- Returns
True if cuda is available.
- Return type
Bool, device
- display_selected_model_spec(params)[source]
Display in terminal the selected model and its parameters.
- Parameters
params (dict) – Keys are param names and values are param values.
- display_selected_transfoms(params, dataset_type)[source]
Display in terminal the selected transforms for a given dataset.
- Parameters
params (dict) –
dataset_type (list) – e.g. [‘testing’] or [‘training’, ‘validation’]
- plot_transformed_sample(before, after, list_title=None, fname_out='', cmap='jet')[source]
Utils tool to plot sample before and after transform, for debugging.
- Parameters
before (ndarray) – Sample before transform.
after (ndarray) – Sample after transform.
list_title (list of str) – Sub titles of before and after, resp.
fname_out (str) – Output filename where the plot is saved if provided.
cmap (str) – Matplotlib colour map.
- check_exe(name)[source]
Ensure that a program exists.
- Parameters
name (str) – Name or path to program.
- Returns
path of the program or None
- Return type
str or None
- get_arguments(parser, args)[source]
Get arguments from function input or command line.
- Parameters
parser (argparse.ArgumentParser) – ArgumentParser object
args (list) – either a list of arguments or None. The list should be formatted like this: [“-d”, “SOME_ARG”, “–model”, “SOME_ARG”]
- format_path_data(path_data)[source]
- Parameters
path_data (list or str) – Either a list of paths, or just one path.
- Returns
A list of paths
- Return type
list
- similarity_score(a: str, b: str) float [source]
use DiffLIb SequenceMatcher to resolve the similarity between text. Help make better choice in terms of derivatives. :param a: a string :param b: another string
Returns: a score indicative of the similarity between the sequence.
- get_timestamp() str [source]
Return a datetime string in the format YYYY-MM-DDTHHMMSS.(sub-precision) Returns:
- get_win_system_memory() float [source]
Obtain the amount of memory available on Windows system. Returns: memory in GB Source: https://stackoverflow.com/a/21589439
- get_linux_system_memory() float [source]
Obtain the amount of memory available on Linux system. Returns: memory in GB Source: https://stackoverflow.com/a/28161352
- get_mac_system_memory() float [source]
Obtain the amount of memory available on MacOS system. Returns: memory in GB Source: https://apple.stackexchange.com/a/4296
Visualize API
- overlap_im_seg(img, seg)[source]
Overlap image (background, greyscale) and segmentation (foreground, jet).
- class LoopingPillowWriter(fps=5, metadata=None, codec=None, bitrate=None)[source]
Bases:
matplotlib.animation.PillowWriter
- class AnimatedGif(size)[source]
Bases:
object
Generates GIF.
- Parameters
size (tuple) – Size of frames.
- Attributes
fig (plt)
size_x (int)
size_y (int)
images (list) – List of frames.
- save_color_labels(gt_data, binarize, gt_filename, output_filename, slice_axis)[source]
Saves labels encoded in RGB in specified output file.
- Parameters
gt_data (ndarray) – Input image with dimensions (Number of classes, height, width, depth).
binarize (bool) – If True binarizes gt_data to 0 and 1 values, else soft values are kept.
gt_filename (str) – GT path and filename.
output_filename (str) – Name of the output file where the colored labels are saved.
slice_axis (int) – Indicates the axis used to extract slices: “axial”: 2, “sagittal”: 0, “coronal”: 1.
- Returns
RGB labels.
- Return type
ndarray
- convert_labels_to_RGB(grid_img)[source]
Converts 2D images to RGB encoded images for display in tensorboard.
- Parameters
grid_img (Tensor) – GT or prediction tensor with dimensions (batch size, number of classes, height, width).
- Returns
RGB image with shape (height, width, 3).
- Return type
tensor
- save_img(writer, epoch, dataset_type, input_samples, gt_samples, preds, wandb_tracking=False, is_three_dim=False)[source]
Saves input images, gt and predictions in tensorboard (and wandb depending upon the inputs in the config file).
- Parameters
writer (SummaryWriter) – Tensorboard’s summary writer.
epoch (int) – Epoch number.
dataset_type (str) – Choice between Training or Validation.
input_samples (Tensor) – Input images with shape (batch size, number of channel, height, width, depth) if 3D else (batch size, number of channel, height, width)
gt_samples (Tensor) – GT images with shape (batch size, number of channel, height, width, depth) if 3D else (batch size, number of channel, height, width)
preds (Tensor) – Model’s prediction with shape (batch size, number of channel, height, width, depth) if 3D else (batch size, number of channel, height, width)
is_three_dim (bool) – True if 3D input, else False.
- save_feature_map(batch, layer_name, path_output, model, test_input, slice_axis)[source]
Save model feature maps.
- Parameters
batch (dict) –
layer_name (str) –
path_output (str) – Output folder.
model (nn.Module) – Network.
test_input (Tensor) –
slice_axis (int) – Indicates the axis used for the 2D slice extraction: Sagittal: 0, Coronal: 1, Axial: 2.
- class HookBasedFeatureExtractor(submodule, layername, upscale=False)[source]
Bases:
torch.nn.modules.module.Module
This function extracts feature maps from given layer. Helpful to observe where the attention of the network is focused.
https://github.com/ozan-oktay/Attention-Gated-Networks/tree/a96edb72622274f6705097d70cfaa7f2bf818a5a
- Parameters
submodule (nn.Module) – Trained model.
layername (str) – Name of the layer where features need to be extracted (layer of interest).
upscale (bool) – If True output is rescaled to initial size.
- Attributes
submodule (nn.Module) – Trained model.
layername (str) – Name of the layer where features need to be extracted (layer of interest).
outputs_size (list) – List of output sizes.
outputs (list) – List of outputs containing the features of the given layer.
inputs (list) – List of inputs.
inputs_size (list) – List of input sizes.
Initializes internal Module state, shared by both nn.Module and ScriptModule.
- __init__(submodule, layername, upscale=False)[source]
Initializes internal Module state, shared by both nn.Module and ScriptModule.
- forward(x)[source]
Defines 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.
Inference API
- tensor(data, *, dtype=None, device=None, requires_grad=False, pin_memory=False) Tensor
Constructs a tensor with no autograd history (also known as a “leaf tensor”, see /notes/autograd) by copying
data
.Warning
When working with tensors prefer using
torch.Tensor.clone()
,torch.Tensor.detach()
, andtorch.Tensor.requires_grad_()
for readability. Letting t be a tensor,torch.tensor(t)
is equivalent tot.clone().detach()
, andtorch.tensor(t, requires_grad=True)
is equivalent tot.clone().detach().requires_grad_(True)
.See also
torch.as_tensor()
preserves autograd history and avoids copies where possible.torch.from_numpy()
creates a tensor that shares storage with a NumPy array.- Parameters
data (array_like) – Initial data for the tensor. Can be a list, tuple, NumPy
ndarray
, scalar, and other types.- Keyword Arguments
dtype (
torch.dtype
, optional) – the desired data type of returned tensor. Default: ifNone
, infers data type fromdata
.device (
torch.device
, optional) – the device of the constructed tensor. If None and data is a tensor then the device of data is used. If None and data is not a tensor then the result tensor is constructed on the CPU.requires_grad (bool, optional) – If autograd should record operations on the returned tensor. Default:
False
.pin_memory (bool, optional) – If set, returned tensor would be allocated in the pinned memory. Works only for CPU tensors. Default:
False
.
Example:
>>> torch.tensor([[0.1, 1.2], [2.2, 3.1], [4.9, 5.2]]) tensor([[ 0.1000, 1.2000], [ 2.2000, 3.1000], [ 4.9000, 5.2000]]) >>> torch.tensor([0, 1]) # Type inference on data tensor([ 0, 1]) >>> torch.tensor([[0.11111, 0.222222, 0.3333333]], ... dtype=torch.float64, ... device=torch.device('cuda:0')) # creates a double tensor on a CUDA device tensor([[ 0.1111, 0.2222, 0.3333]], dtype=torch.float64, device='cuda:0') >>> torch.tensor(3.14159) # Create a zero-dimensional (scalar) tensor tensor(3.1416) >>> torch.tensor([]) # Create an empty tensor (of size (0,)) tensor([])
- onnx_inference(model_path: str, inputs: None._VariableFunctionsClass.tensor) None._VariableFunctionsClass.tensor [source]
Run ONNX inference
- Parameters
model_path (str) – Path to the ONNX model.
inputs (Tensor) – Batch of input image.
- Returns
Network output.
- Return type
Tensor
- get_preds(context: dict, fname_model: str, model_params: dict, cuda_available: bool, device: torch.device, batch: dict) None._VariableFunctionsClass.tensor [source]
Returns the predictions from the given model.
- Parameters
context (dict) – configuration dict.
fname_model (str) – name of file containing model.
model_params (dict) – dictionary containing model parameters.
cuda_available (bool) – True if cuda is available.
device (torch.device) – Device used for prediction.
batch (dict) – dictionary containing input, gt and metadata
- Returns
predictions from the model.
- Return type
tensor
- get_onehotencoder(context: dict, folder_model: str, options: dict, ds: torch.utils.data.dataset.Dataset) dict [source]
Returns one hot encoder which is needed to update the model parameters when FiLMedUnet is applied.
- Parameters
context (dict) – Configuration dict.
folder_model (str) – Foldername which contains trained model and its configuration file.
options (dict) – Contains film metadata information.
ds (Dataset) – Dataset used for the segmentation.
- Returns
onehotencoder used in the model params.
- Return type
dict
- pred_to_nib(data_lst: List[numpy.ndarray], z_lst: List[int], fname_ref: str, fname_out: str, slice_axis: int, debug: bool = False, kernel_dim: str = '2d', bin_thr: float = 0.5, discard_noise: bool = True, postprocessing: Optional[dict] = None) nibabel.nifti1.Nifti1Image [source]
Save the network predictions as nibabel object.
Based on the header of fname_ref image, it creates a nibabel object from the Network predictions (data_lst).
- Parameters
data_lst (list of np arrays) – Predictions, either 2D slices either 3D patches.
z_lst (list of ints) – Slice indexes to reconstruct a 3D volume for 2D slices.
fname_ref (str) – Filename of the input image: its header is copied to the output nibabel object.
fname_out (str) – If not None, then the generated nibabel object is saved with this filename.
slice_axis (int) – Indicates the axis used for the 2D slice extraction: Sagittal: 0, Coronal: 1, Axial: 2.
debug (bool) – If True, extended verbosity and intermediate outputs.
kernel_dim (str) – Indicates whether the predictions were done on 2D or 3D patches. Choices: ‘2d’, ‘3d’.
bin_thr (float) – If positive, then the segmentation is binarized with this given threshold. Otherwise, a soft segmentation is output.
discard_noise (bool) – If True, predictions that are lower than 0.01 are set to zero.
postprocessing (dict) – Contains postprocessing steps to be applied.
- Returns
NiBabel object containing the Network prediction.
- Return type
nibabel.Nifti1Image
- pred_to_png(pred_list: list, target_list: list, subj_path: str, suffix: str = '', max_value: int = 1)[source]
Save the network predictions as PNG files with suffix “_target_pred”.
- Parameters
pred_list (list of np arrays) – list of 2D predictions.
target_list (list of str) – list of target suffixes.
subj_path (str) – Path of the subject filename in output folder without extension (e.g. “path_output/pred_masks/sub-01_sample-01_SEM”).
suffix (str) – additional suffix to append to the filename (e.g. “_pred.png”)
max_value (int) – Maximum mask value of the float mask to use during the conversion to uint8.
- process_transformations(context: dict, fname_roi: str, fname_prior: str, metadata: dict, slice_axis: int, fname_images: list) dict [source]
Sets the transformation based on context parameters. When ROI is not provided center-cropping is applied.
If there is an object_detection_path, then we modify the metadata to store transformation data.
- Parameters
context (dict) – configuration dictionary.
fname_roi (str) – filename containing region for cropping image prior to segmentation.
fname_prior (str) – prior image filename.
metadata (dict) – metadata used in setting bounding box when we have object_detection_params.
slice_axis (int) – Indicates the axis used for the 2D slice extraction: Sagittal: 0, Coronal: 1, Axial: 2.
fname_images (list) – list of image filenames (e.g. .nii.gz) to segment.
- Returns
metadata.
- Return type
dict
- set_option(options: dict, postpro: dict, context: dict, key: str)[source]
Generalized function that sets postprocessing option based on given list of options.
When given key already exists in options, we initialize the key value for the postprocessing dictionary Otherwise, when the key is already found in the postprocessing attritute of the context, we remove it
- Parameters
options (dict) – Contains postprocessing steps information.
postpro (dict) – Postprocessing settings.
context (dict) – Configuration dict.
key (str) – The key of the postprocessing option we wish to set.
- Returns
postprocessing settings.
- Return type
dict
- set_postprocessing_options(options: dict, context: dict)[source]
Updates the postprocessing options based on existing settings found in options.
- Parameters
options (dict) – Contains postprocessing steps information.
context (dict) – Configuration dict.
- segment_volume(folder_model: str, fname_images: list, gpu_id: int = 0, options: Optional[dict] = None)[source]
Segment an image.
Segment an image (fname_image) using a pre-trained model (folder_model). If provided, a region of interest (fname_roi) is used to crop the image prior to segment it.
- Parameters
folder_model (str) – foldername which contains (1) the model (‘folder_model/folder_model.pt’) to use (2) its configuration file (‘folder_model/folder_model.json’) used for the training, see https://github.com/neuropoly/ivadomed/wiki/configuration-file
fname_images (list) – list of image filenames (e.g. .nii.gz) to segment. Multichannel models require multiple images to segment, e.i., len(fname_images) > 1.
gpu_id (int) – Number representing gpu number if available. Currently does NOT support multiple GPU segmentation.
options (dict) –
This can optionally contain any of the following key-value pairs:
’binarize_prediction’: (float) Binarize segmentation with specified threshold. Predictions below the threshold become 0, and predictions above or equal to threshold become 1. Set to -1 for no thresholding (i.e., soft segmentation).
’binarize_maxpooling’: (bool) Binarize by setting to 1 the voxel having the maximum prediction across all classes. Useful for multiclass models.
’fill_holes’: (bool) Fill small holes in the segmentation.
’keep_largest’: (bool) Keep the largest connected-object for each class from the output segmentation.
’remove_small’: (list of str) Minimal object size to keep with unit (mm3 or vox). A single value can be provided or one value per prediction class. Single value example: [“1mm3”], [“5vox”]. Multiple values example: [“10”, “20”, “10vox”] (remove objects smaller than 10 voxels for class 1 and 3, and smaller than 20 voxels for class 2).
’pixel_size’: (list of float) List of microscopy pixel size in micrometers. Length equals 2 [PixelSizeX, PixelSizeY] for 2D or 3 [PixelSizeX, PixelSizeY, PixelSizeZ] for 3D, where X is the width, Y the height and Z the depth of the image.
’pixel_size_units’: (str) Units of pixel size (Must be either “mm”, “um” or “nm”)
’no_patch’: (bool) 2D patches are not used while segmenting with models trained with patches. The “no_patch” option supersedes the “overlap_2D” option. This option may not be suitable with large images depending on computer RAM capacity.
’overlap_2D’: (list of int) List of overlaps in pixels for 2D patching. Length equals 2 [OverlapX, OverlapY], where X is the width and Y the height of the image.
’metadata’: (str) Film metadata.
’fname_prior’: (str) An image filename (e.g., .nii.gz) containing processing information (e.g., spinal cord segmentation, spinal location or MS lesion classification, spinal cord centerline), used to crop the image prior to segment it if provided. The segmentation is not performed on the slices that are empty in this image.
- Returns
List of nibabel objects containing the soft segmentation(s), one per prediction class, List of target suffix associated with each prediction in pred_list
- Return type
list, list
- split_classes(nib_prediction)[source]
Split a 4D nibabel multi-class segmentation file in multiple 3D nibabel binary segmentation files.
- Parameters
nib_prediction (nibabelObject) – 4D nibabel object.
- Returns
list of nibabelObject.
- reconstruct_3d_object(context: dict, batch: dict, undo_transforms: ivadomed.transforms.UndoCompose, preds: None._VariableFunctionsClass.tensor, preds_list: list, kernel_3D: bool, is_2d_patch: bool, slice_axis: int, slice_idx_list: list, data_loader: torch.utils.data.dataloader.DataLoader, fname_images: list, i_batch: int, last_sample_bool: bool, weight_matrix: None._VariableFunctionsClass.tensor, volume: None._VariableFunctionsClass.tensor, image: None._VariableFunctionsClass.tensor)[source]
Reconstructs the 3D object from the current batch, and returns the list of predictions and targets.
- Parameters
context (dict) – configuration dict.
batch (dict) – Dictionary containing input, gt and metadata
undo_transforms (UndoCompose) – Undo transforms so prediction match original image resolution and shape
preds (tensor) – Subvolume predictions
preds_list (list of tensor) – list of subvolume predictions.
kernel_3D (bool) – true when using 3D kernel.
is_2d_patch (bool) – Indicates if 2d patching is used.
slice_axis (int) – Indicates the axis used for the 2D slice extraction: Sagittal: 0, Coronal: 1, Axial: 2.
slice_idx_list (list of int) – list of indices for the axis slices.
data_loader (DataLoader) – DataLoader object containing batches using in object construction.
fname_images (list) – list of image filenames (e.g. .nii.gz) to segment.
i_batch (int) – index of current batch.
last_sample_bool (bool) – flag to indicate whether this is the last sample in the 3D volume
weight_matrix (tensor) – the weight matrix
volume (tensor) – the volume tensor that is being partially reconstructed through the loop
image (tensor) – the image tensor that is being partially reconstructed through the loop
- Returns
list of predictions target_list (list): list of targets last_sample_bool (bool): flag to indicate whether this is the last sample in the 3D volume weight_matrix (tensor): the weight matrix. Must be returned as passing tensor by reference is NOT reliable. volume (tensor): the volume tensor that is being partially reconstructed through the loop. Must be returned as passing tensor by reference is NOT reliable. image (tensor): the vimage tensor that is being partially reconstructed through the loop. Must be returned as passing tensor by reference is NOT reliable.
- Return type
pred_list (list)
- volume_reconstruction(batch: dict, pred: None._VariableFunctionsClass.tensor, undo_transforms: ivadomed.transforms.UndoCompose, smp_idx: int, volume: Optional[None._VariableFunctionsClass.tensor] = None, weight_matrix: Optional[None._VariableFunctionsClass.tensor] = None)[source]
Reconstructs volume prediction from subvolumes used during training :param batch: Dictionary containing input, gt and metadata :type batch: dict :param pred: Subvolume prediction :type pred: tensor :param undo_transforms: Undo transforms so prediction match original image resolution and shap :type undo_transforms: UndoCompose :param smp_idx: Batch index :type smp_idx: int :param volume: Reconstructed volume :type volume: tensor :param weight_matrix: Weights containing the number of predictions for each voxel :type weight_matrix: tensor
- Returns
undone subvolume, metadata (dict): metadata, last_sample_bool (bool): boolean representing if its the last sample of the volume volume (tensor): representing the volume reconstructed weight_matrix (tensor): weight matrix
- Return type
pred_undo (tensor)
- image_reconstruction(batch: dict, pred: None._VariableFunctionsClass.tensor, undo_transforms: ivadomed.transforms.UndoCompose, smp_idx: int, image: Optional[None._VariableFunctionsClass.tensor] = None, weight_matrix: Optional[None._VariableFunctionsClass.tensor] = None)[source]
Reconstructs image prediction from patches used during training :param batch: Dictionary containing input, gt and metadata :type batch: dict :param pred: Patch prediction :type pred: tensor :param undo_transforms: Undo transforms so prediction match original image resolution and shape :type undo_transforms: UndoCompose :param smp_idx: Batch index :type smp_idx: int :param image: Reconstructed image :type image: tensor :param weight_matrix: Weights containing the number of predictions for each pixel :type weight_matrix: tensor
- Returns
undone image metadata (dict): metadata last_patch_bool (bool): boolean representing if its the last patch of the image image (tensor): representing the image reconstructed weight_matrix (tensor): weight matrix
- Return type
pred_undo (tensor)
Mixup API
- mixup(data, targets, alpha, debugging=False, ofolder=None)[source]
Compute the mixup data.
See also
Zhang, Hongyi, et al. “mixup: Beyond empirical risk minimization.” arXiv preprint arXiv:1710.09412 (2017).
- Parameters
data (Tensor) – Input images.
targets (Tensor) – Input masks.
alpha (float) – MixUp parameter.
debugging (Bool) – If True, then samples of mixup are saved as png files.
ofolder (str) – If debugging, output folder where “mixup” folder is created and samples are saved.
- Returns
Mixed image, Mixed mask.
- Return type
Tensor, Tensor
- save_mixup_sample(ofolder, input_data, labeled_data, lambda_tensor)[source]
Save mixup samples as png files in a “mixup” folder.
- Parameters
ofolder (str) – Output folder where “mixup” folder is created and samples are saved.
input_data (Tensor) – Input image.
labeled_data (Tensor) – Input masks.
lambda_tensor (Tensor) –
Uncertainty API
- run_uncertainty(image_folder)[source]
Compute uncertainty from model prediction.
This function loops across the model predictions (nifti masks) and estimates the uncertainty from the Monte Carlo samples. Both voxel-wise and structure-wise uncertainty are estimates.
- Parameters
image_folder (str) – Folder containing the Monte Carlo samples.
- combine_predictions(fname_lst, fname_hard, fname_prob, thr=0.5)[source]
Combine predictions from Monte Carlo simulations.
- Combine predictions from Monte Carlo simulations and save the resulting as:
fname_prob, a soft segmentation obtained by averaging the Monte Carlo samples.
fname_hard, a hard segmentation obtained thresholding with thr.
- Parameters
fname_lst (list of str) – List of the Monte Carlo samples.
fname_hard (str) – Filename for the output hard segmentation.
fname_prob (str) – Filename for the output soft segmentation.
thr (float) – Between 0 and 1. Used to threshold the soft segmentation and generate the hard segmentation.
- voxelwise_uncertainty(fname_lst, fname_out, eps=1e-05)[source]
Estimate voxel wise uncertainty.
Voxel-wise uncertainty is estimated as entropy over all N MC probability maps, and saved in fname_out.
- Parameters
fname_lst (list of str) – List of the Monte Carlo samples.
fname_out (str) – Output filename.
eps (float) – Epsilon value to deal with np.log(0).
- structurewise_uncertainty(fname_lst, fname_hard, fname_unc_vox, fname_out)[source]
Estimate structure wise uncertainty.
Structure-wise uncertainty from N MC probability maps (fname_lst) and saved in fname_out with the following suffixes:
‘-cv.nii.gz’: coefficient of variation
‘-iou.nii.gz’: intersection over union
‘-avgUnc.nii.gz’: average voxel-wise uncertainty within the structure.
- Parameters
fname_lst (list of str) – List of the Monte Carlo samples.
fname_hard (str) – Filename of the hard segmentation, which is used to compute the avgUnc by providing a mask of the structures.
fname_unc_vox (str) – Filename of the voxel-wise uncertainty, which is used to compute the avgUnc.
fname_out (str) – Output filename.
Maths API
- rescale_values_array(arr, minv=0.0, maxv=1.0, dtype=<class 'numpy.float32'>)[source]
Rescale the values of numpy array arr to be from minv to maxv.
- Parameters
arr (ndarry) – Array whose values will be rescaled.
minv (float) – Minimum value of the output array.
maxv (float) – Maximum value of the output array.
dtype (type) – Cast array to this type before performing the rescaling.
- gaussian_kernel(kernlen=10)[source]
Create a 2D gaussian kernel with user-defined size.
- Parameters
kernlen (int) – size of kernel
- Returns
a 2D array of size (kernlen,kernlen)
- Return type
ndarray
- heatmap_generation(image, kernel_size)[source]
Generate heatmap from image containing sing voxel label using convolution with gaussian kernel :param image: 2D array containing single voxel label :type image: ndarray :param kernel_size: size of gaussian kernel :type kernel_size: int
- Returns
2D array heatmap matching the label.
- Return type
ndarray