API Reference

This document is for developers of ivadomed, it contains the API functions.

Loader API

loader.adaptative

class Bids_to_hdf5(root_dir, subject_lst, target_suffix, contrast_lst, hdf5_name, contrast_balance=None, slice_axis=2, metadata_choice=False, slice_filter_fn=None, roi_params=None, transform=None, object_detection_params=None, soft_gt=False)[source]

Bases: object

Converts a BIDS dataset to a HDF5 file.

Parameters:
  • root_dir (str) – Path to the BIDS dataset.
  • subject_lst (list) – Subject names list.
  • target_suffix (list) – List of suffixes for target masks.
  • roi_params (dict) – Dictionary containing parameters related to ROI image processing.
  • contrast_lst (list) – List of the contrasts.
  • hdf5_name (str) – Path and name of the hdf5 file.
  • contrast_balance (dict) – Dictionary controlling image contrasts balance.
  • slice_axis (int) – Indicates the axis used to extract slices: “axial”: 2, “sagittal”: 0, “coronal”: 1.
  • metadata_choice (str) – Choice between “mri_params”, “contrasts”, None or False, related to FiLM.
  • slice_filter_fn (SliceFilter) – Class that filters slices according to their content.
  • transform (Compose) – Transformations.
  • object_detection_params (dict) – Object detection parameters.
Attributes:
  • bids_ds (BIDS) – BIDS dataset.
  • dt (dtype) – hdf5 special dtype.
  • hdf5_file (hdf5) – hdf5 file containing dataset information.
  • filename_pairs (list) – A list of tuples in the format (input filename list containing all modalities,ground truth filename, ROI filename, metadata).
  • metadata (dict) – Dictionary containing metadata of input and gt.
  • prepro_transforms (Compose) – Transforms to be applied before training.
  • transform (Compose) – Transforms to be applied during training.
  • has_bounding_box (bool) – True if all metadata contains bounding box coordinates, else False.
  • slice_axis (int) – Indicates the axis used to extract slices: “axial”: 2, “sagittal”: 0, “coronal”: 1.
  • slice_filter_fn (SliceFilter) – Object that filters slices according to their content.
__init__(root_dir, subject_lst, target_suffix, contrast_lst, hdf5_name, contrast_balance=None, slice_axis=2, metadata_choice=False, slice_filter_fn=None, roi_params=None, transform=None, object_detection_params=None, soft_gt=False)[source]

Initialize self. See help(type(self)) for accurate signature.

class Dataframe(hdf5, contrasts, path, target_suffix=None, roi_suffix=None, filter_slices=False, dim=2)[source]

Bases: object

This class aims to create a dataset using an HDF5 file, which can be used by an adapative loader to perform curriculum learning, Active Learning or any other strategy that needs to load samples in a specific way. It works on RAM or on the fly and can be saved for later.

Parameters:
  • hdf5 (hdf5) – hdf5 file containing dataset information
  • contrasts (list of str) – List of the contrasts of interest.
  • path (str) – Dataframe path.
  • target_suffix (list of str) – List of suffix of targetted structures.
  • roi_suffix (str) – List of suffix of ROI masks.
  • filter_slices (SliceFilter) – Object that filters slices according to their content.
  • dim (int) – Choice 2 or 3, for 2D or 3D data respectively.
Attributes:
  • dim (int) – Choice 2 or 3, for 2D or 3D data respectively.
  • contrasts (list of str) – List of the contrasts of interest.
  • filter_slices (SliceFilter) – Object that filters slices according to their content.
  • df (pd.Dataframe) – Dataframe containing dataset information
__init__(hdf5, contrasts, path, target_suffix=None, roi_suffix=None, filter_slices=False, dim=2)[source]

Initialize self. See help(type(self)) for accurate signature.

clean(contrasts)[source]

Aims to remove lines where one of the contrasts in not available.

Agrs:
contrasts (list of str): List of contrasts.
create_df(hdf5)[source]

Generate the Data frame using the hdf5 file.

Parameters:hdf5 (hdf5) – File containing dataset information
load_dataframe(path)[source]

Load the dataframe from a csv file.

Parameters:path (str) – Path to hdf5 file.
save(path)[source]

Save the dataframe into a csv file.

Parameters:path (str) – Path to hdf5 file.
shuffle()[source]

Shuffle the whole data frame.

class HDF5Dataset(root_dir, subject_lst, model_params, target_suffix, contrast_params, slice_axis=2, transform=None, metadata_choice=False, dim=2, complet=True, slice_filter_fn=None, roi_params=None, object_detection_params=None, soft_gt=False)[source]

Bases: object

HDF5 dataset object.

Parameters:
  • root_dir (path) – Path of bids and data.
  • subject_lst (list of str) – List of subjects.
  • model_params (dict) – Dictionary containing model parameters.
  • target_suffix (list of str) – List of suffixes of the target structures.
  • contrast_params (dict) – Dictionary containing contrast parameters.
  • slice_axis (int) – Indicates the axis used to extract slices: “axial”: 2, “sagittal”: 0, “coronal”: 1.
  • transform (Compose) – Transformations.
  • metadata_choice (str) – Choice between “mri_params”, “contrasts”, None or False, related to FiLM.
  • dim (int) – Choice 2 or 3, for 2D or 3D data respectively.
  • complet (bool) – If True removes lines where contrasts is not available.
  • slice_filter_fn (SliceFilter) – Object that filters slices according to their content.
  • roi_params (dict) – Dictionary containing parameters related to ROI image processing.
  • object_detection_params (dict) – Object detection parameters.
Attributes:
  • cst_lst (list) – Contrast list.
  • gt_lst (list) – Contrast label used for ground truth.
  • roi_lst (list) – Contrast label used for ROI cropping.
  • dim (int) – Choice 2 or 3, for 2D or 3D data respectively.
  • filter_slices (SliceFilter) – Object that filters slices according to their content.
  • prepro_transforms (Compose) – Transforms to be applied before training.
  • transform (Compose) – Transforms to be applied during training.
  • df_object (pd.Dataframe) – Dataframe containing dataset information.
__getitem__(index)[source]

Get samples.

Warning: For now, this method only supports one gt / roi.

Parameters:index (int) – Sample index.
Returns:Dictionary containing image and label tensors as well as metadata.
Return type:dict
__init__(root_dir, subject_lst, model_params, target_suffix, contrast_params, slice_axis=2, transform=None, metadata_choice=False, dim=2, complet=True, slice_filter_fn=None, roi_params=None, object_detection_params=None, soft_gt=False)[source]

Initialize self. See help(type(self)) for accurate signature.

__len__()[source]

Get the dataset size, ie he number of subvolumes.

load_into_ram(contrast_lst=None)[source]

Aims to load into RAM the contrasts from the list.

Parameters:contrast_lst (list of str) – List of contrasts of interest.
set_transform(transform)[source]

Set the transforms.

update(strategy='Missing', p=0.0001)[source]

Update the Dataframe itself.

Parameters:
  • p (float) – Float between 0 and 1, probability of the contrast to be missing.
  • strategy (str) – Update the dataframe using the corresponding strategy. For now the only the strategy implemented is the one used by HeMIS (i.e. by removing contrasts with a certain probability.) Other strategies that could be implemented are Active Learning, Curriculum Learning, …
HDF5_to_Bids(HDF5, subjects, path_dir)[source]

Convert HDF5 file to BIDS dataset.

Parameters:
  • HDF5 (str) – Path to the HDF5 file.
  • subjects (list) – List of subject names.
  • path_dir (str) – Output folder path, already existing.

loader.film

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.
__init__()[source]

Initialize self. See help(type(self)) for accurate signature.

check_isMRIparam(mri_param_type, mri_param, subject, metadata)[source]

Check if a given metadata belongs to the MRI parameters.

Parameters:
  • mri_param_type (str) – Metadata type name.
  • mri_param (list) – 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

clustering_fit(dataset, key_lst)[source]

This function creates clustering models for each metadata type, using Kernel Density Estimation algorithm.

Parameters:
  • datasets (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

get_film_metadata_models(ds_train, metadata_type, debugging=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

normalize_metadata(ds_in, clustering_models, debugging, metadata_type, train_set=False)[source]

Categorize each metadata value using a KDE clustering method, then apply a one-hot-encoding.

Parameters:
  • ds_in (BidsDataset) – Dataset with metadata.
  • clustering_models – 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

loader.loader

class Bids3DDataset(root_dir, subject_lst, target_suffix, model_params, contrast_params, slice_axis=2, cache=True, transform=None, metadata_choice=False, roi_params=None, multichannel=False, object_detection_params=None, task='segmentation', soft_gt=False)[source]

Bases: ivadomed.loader.loader.MRI3DSubVolumeSegmentationDataset

BIDS specific dataset loader for 3D dataset.

Parameters:
  • root_dir (str) – Path to the BIDS dataset.
  • subject_lst (list) – Subject names list.
  • target_suffix (list) – List of suffixes for target masks.
  • model_params (dict) – Dictionary containing model parameters.
  • contrast_params (dict) – Contains image contrasts related parameters.
  • slice_axis (int) – Indicates the axis used to extract slices: “axial”: 2, “sagittal”: 0, “coronal”: 1.
  • cache (bool) – If the data should be cached in memory or not.
  • transform (list) – Transformation list (length 2) composed of preprocessing transforms (Compose) and transforms to apply during training (Compose).
  • metadata_choice – Choice between “mri_params”, “contrasts”, None or False, related to FiLM.
  • roi_params (dict) – Dictionary containing parameters related to ROI image processing.
  • 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).
  • object_detection_params (dict) – Object dection parameters.
__init__(root_dir, subject_lst, target_suffix, model_params, contrast_params, slice_axis=2, cache=True, transform=None, metadata_choice=False, roi_params=None, multichannel=False, object_detection_params=None, task='segmentation', soft_gt=False)[source]

Initialize self. See help(type(self)) for accurate signature.

class BidsDataset(root_dir, subject_lst, target_suffix, contrast_params, slice_axis=2, cache=True, transform=None, metadata_choice=False, slice_filter_fn=None, roi_params=None, multichannel=False, object_detection_params=None, task='segmentation', soft_gt=False)[source]

Bases: ivadomed.loader.loader.MRI2DSegmentationDataset

BIDS specific dataset loader.

Parameters:
  • root_dir (str) – Path to the BIDS dataset.
  • subject_lst (list) – Subject names list.
  • target_suffix (list) – List of suffixes for target masks.
  • contrast_params (dict) – Contains image contrasts related parameters.
  • slice_axis (int) – Indicates the axis used to extract slices: “axial”: 2, “sagittal”: 0, “coronal”: 1.
  • cache (bool) – If the data should be cached in memory or not.
  • transform (list) – Transformation list (length 2) composed of preprocessing transforms (Compose) and transforms to apply during training (Compose).
  • metadata_choice (str) – Choice between “mri_params”, “contrasts”, the name of a column from the participants.tsv file, None or False, related to FiLM.
  • slice_filter_fn (SliceFilter) – Class that filters slices according to their content.
  • roi_params (dict) – Dictionary containing parameters related to ROI image processing.
  • 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).
  • object_detection_params (dict) – Object dection parameters.
  • task (str) – Choice between segmentation or classification. If classification: GT is discrete values, If segmentation: GT is binary mask.
  • soft_gt (bool) – If True, ground truths will be converted to float32, otherwise to uint8 and binarized (to save memory).
Attributes:
  • bids_ds (BIDS) – BIDS dataset.
  • filename_pairs (list) – A list of tuples in the format (input filename list containing all modalities,ground truth filename, ROI filename, metadata).
  • metadata (dict) – Dictionary containing FiLM metadata.
__init__(root_dir, subject_lst, target_suffix, contrast_params, slice_axis=2, cache=True, transform=None, metadata_choice=False, slice_filter_fn=None, roi_params=None, multichannel=False, object_detection_params=None, task='segmentation', soft_gt=False)[source]

Initialize self. See help(type(self)) for accurate signature.

class MRI2DSegmentationDataset(filename_pairs, slice_axis=2, cache=True, transform=None, slice_filter_fn=None, task='segmentation', roi_params=None, soft_gt=False)[source]

Bases: torch.utils.data.dataset.Dataset

Generic class for 2D (slice-wise) segmentation dataset.

Parameters:
  • filename_pairs (list) – a list of tuples in the format (input filename list containing all modalities,ground truth filename, ROI filename, metadata).
  • slice_axis (int) – axis to make the slicing (default axial).
  • cache (bool) – if the data should be cached in memory or not.
  • transform (torchvision.Compose) – transformations to apply.
  • slice_filter_fn (dict) – Slice filter parameters, see Configuration File for more details.
  • task (str) – choice between segmentation or classification. If classification: GT is discrete values, If segmentation: GT is binary mask.
  • roi_params (dict) – Dictionary containing parameters related to ROI image processing.
  • soft_gt (bool) – If True, ground truths are expected to be non-binarized images encoded in float32 and will be fed as is to the network. Otherwise, ground truths are converted to uint8 and binarized to save memory space.
Attributes:
  • indexes (list) – List of indices corresponding to each slice or subvolume in the dataset.
  • filename_pairs (list) – List of tuples in the format (input filename list containing all modalities,ground truth filename, ROI filename, metadata).
  • prepro_transforms (Compose) – Transformations to apply before training.
  • transform (Compose) – Transformations to apply during training.
  • cache (bool) – Tf the data should be cached in memory or not.
  • slice_axis (int) – Indicates the axis used to extract slices: “axial”: 2, “sagittal”: 0, “coronal”: 1.
  • slice_filter_fn (dict) – Slice filter parameters, see Configuration File for more details.
  • n_contrasts (int) – Number of input contrasts.
  • has_bounding_box (bool) – True if bounding box in all metadata, else False.
  • task (str) – Choice between segmentation or classification. If classification: GT is discrete values, If segmentation: GT is binary mask.
  • soft_gt (bool) – If True, ground truths are expected to be non-binarized images encoded in float32 and will be fed as is to the network. Otherwise, ground truths are converted to uint8 and binarized to save memory space.
  • slice_filter_roi (bool) – Indicates whether a slice filtering is done based on ROI data.
  • roi_thr (int) – If the ROI mask contains less than this number of non-zero voxels, the slice will be discarded from the dataset.
__getitem__(index)[source]

Return the specific processed data corresponding to index (input, ground truth, roi and metadata).

Parameters:index (int) – Slice index.
__init__(filename_pairs, slice_axis=2, cache=True, transform=None, slice_filter_fn=None, task='segmentation', roi_params=None, soft_gt=False)[source]

Initialize self. See help(type(self)) for accurate signature.

load_filenames()[source]

Load preprocessed pair data (input and gt) in handler.

class MRI3DSubVolumeSegmentationDataset(filename_pairs, transform=None, length=(64, 64, 64), stride=(0, 0, 0), slice_axis=0, task='segmentation', soft_gt=False)[source]

Bases: torch.utils.data.dataset.Dataset

This is a class for 3D segmentation dataset. This class splits the initials volumes in several subvolumes. Each subvolumes will be of the sizes of the length parameter.

This class also implement a stride parameter corresponding to the amount of voxels subvolumes are translated in each dimension at every iteration.

Be careful, the input’s dimensions should be compatible with the given lengths and strides. This class doesn’t handle missing dimensions.

Parameters:
  • filename_pairs (list) – A list of tuples in the format (input filename, ground truth filename).
  • transform (Compose) – Transformations to apply.
  • length (tuple) – Size of each dimensions of the subvolumes, length equals 3.
  • stride (tuple) – Size of the overlapping per subvolume and dimensions, length equals 3.
  • slice_axis (int) – Indicates the axis used to extract slices: “axial”: 2, “sagittal”: 0, “coronal”: 1.
  • soft_gt (bool) – If True, ground truths are expected to be non-binarized images encoded in float32 and will be fed as is to the network. Otherwise, ground truths are converted to uint8 and binarized to save memory space.
__getitem__(index)[source]

Return the specific index pair subvolume (input, ground truth).

Parameters:index (int) – Subvolume index.
__init__(filename_pairs, transform=None, length=(64, 64, 64), stride=(0, 0, 0), slice_axis=0, task='segmentation', soft_gt=False)[source]

Initialize self. See help(type(self)) for accurate signature.

__len__()[source]

Return the dataset size. The number of subvolumes.

class SegmentationPair(input_filenames, gt_filenames, metadata=None, slice_axis=2, cache=True, prepro_transforms=None, soft_gt=False)[source]

Bases: object

This class is used to build segmentation datasets. It represents a pair of of two data volumes (the input data and the ground truth data).

Parameters:
  • input_filenames (list of str) – The input filename list (supported by nibabel). For single channel, the list will contain 1 input filename.
  • gt_filenames (list of str) – The ground-truth filenames list.
  • metadata (list) – Metadata list with each item corresponding to an image (contrast) in input_filenames. For single channel, the list will contain metadata related to one image.
  • cache (bool) – If the data should be cached in memory or not.
  • slice_axis (int) – Indicates the axis used to extract slices: “axial”: 2, “sagittal”: 0, “coronal”: 1.
  • prepro_transforms (dict) – Output of get_preprocessing_transforms.
  • soft_gt (bool) – If True, ground truths will be converted to float32, otherwise to uint8 and binarized (to save memory).
Attributes:
  • input_filenames (list) – List of input filenames.
  • gt_filenames (list) – List of ground truth filenames.
  • metadata (dict) – Dictionary containing metadata of input and gt.
  • cache (bool) – If the data should be cached in memory or not.
  • slice_axis (int) – Indicates the axis used to extract slices: “axial”: 2, “sagittal”: 0, “coronal”: 1.
  • prepro_transforms (dict) – Transforms to be applied before training.
  • input_handle (list) – List of input nifty data.
  • gt_handle (list) – List of gt nifty data.
__init__(input_filenames, gt_filenames, metadata=None, slice_axis=2, cache=True, prepro_transforms=None, soft_gt=False)[source]

Initialize self. See help(type(self)) for accurate signature.

get_pair_data()[source]

Return the tuple (input, ground truth) with the data content in numpy array.

get_pair_metadata(slice_index=0, coord=None)[source]

Return dictionary containing input and gt metadata.

Parameters:
  • slice_index (int) – Index of 2D slice if 2D model is used, else 0.
  • coord (tuple or list) – Coordinates of subvolume in volume if 3D model is used, else None.
Returns:

Input and gt metadata.

Return type:

dict

get_pair_shapes()[source]

Return the tuple (input, ground truth) representing both the input and ground truth shapes.

get_pair_slice(slice_index, gt_type='segmentation')[source]

Return the specified slice from (input, ground truth).

Parameters:
  • slice_index (int) – Slice number.
  • gt_type (str) – Choice between segmentation or classification, returns mask (array) or label (int) resp. for the ground truth.
load_dataset(data_list, bids_path, transforms_params, model_params, target_suffix, roi_params, contrast_params, slice_filter_params, slice_axis, multichannel, dataset_type='training', requires_undo=False, metadata_type=None, object_detection_params=None, soft_gt=False, device=None, cuda_available=None, **kwargs)[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:
  • data_list (list) – Subject names list.
  • bids_path (str) – Path to the BIDS dataset.
  • 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 parameters, see Configuration File for more details.
  • slice_axis (string) – Choice between “axial”, “sagittal”, “coronal” ; controls the axis used to extract the 2D data.
  • 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 will be converted to float32, otherwise to uint8 and binarized (to save memory).
Returns:

BidsDataset

Note: For more details on the parameters transform_params, target_suffix, roi_params, contrast_params, slice_filter_params and object_detection_params see Configuration File.

loader.utils

class BalancedSampler(dataset)[source]

Bases: torch.utils.data.sampler.Sampler

Estimate sampling weights in order to rebalance the class distributions from an imbalanced dataset.

Parameters:

dataset (BidsDataset) – Dataset containing input, gt and metadata.

Attributes:
  • indices (list) – List from 0 to length of dataset (number of elements in the dataset).
  • nb_samples (int) – Number of elements in the dataset.
  • weights (Tensor) – Weight of each dataset element equal to 1 over the frequency of a given label (inverse of the frequency).
__init__(dataset)[source]

Initialize self. See help(type(self)) for accurate signature.

class SampleMetadata(d=None)[source]

Bases: object

Metadata class to help update, get and set metadata values.

Parameters:d (dict) – Initial metadata.
Attributes:metadata (dict) – Image metadata.
__init__(d=None)[source]

Initialize self. See help(type(self)) for accurate signature.

clean_metadata(metadata_lst)[source]

Remove keys from metadata. The keys to be deleted are stored in a list.

Parameters:metadata_lst (list) – List of SampleMetadata.
Returns:List of SampleMetadata with removed keys.
Return type:list
filter_roi(roi_data, nb_nonzero_thr)[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

get_new_subject_split(path_folder, center_test, split_method, random_seed, train_frac, test_frac, log_directory, balance)[source]

Randomly split dataset between training / validation / testing.

Randomly split dataset between training / validation / testing and save it in log_directory + “/split_datasets.joblib”.

Parameters:
  • path_folder (string) – Dataset folder.
  • center_test (list) – List of centers to include in the testing set.
  • split_method (string) – See imed_loader_utils.split_dataset.
  • 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.
  • log_directory (string) – Output folder.
  • balance (string) – Metadata contained in “participants.tsv” file with categorical values. Each category will be
  • distributed in the training, validation and testing datasets. (evenly) –
Returns:

Training, validation and testing subjects lists.

Return type:

list, list list

get_subdatasets_subjects_list(split_params, bids_path, log_directory)[source]

Get lists of subjects for each sub-dataset between training / validation / testing.

Parameters:
  • split_params (dict) – Split parameters, see Configuration File for more details.
  • bids_path (str) – Path to the BIDS dataset.
  • log_directory (str) – Output folder.
Returns:

Training, validation and testing subjects lists.

Return type:

list, list list

imed_collate(batch)[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
orient_img_hwd(data, slice_axis)[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, slice_axis)[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, slice_axis)[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.i. 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

split_dataset(df, center_test_lst, split_method, random_seed, train_frac=0.8, test_frac=0.1)[source]

Splits list of subject into training, validation and testing datasets either according to their center or per patient. In the ‘per_center’ option the centers associated the subjects are split according the train, test and validation fraction whereas in the ‘per_patient’, the patients are directly separated according to these fractions.

Parameters:
  • df (pd.DataFrame) – Dataframe containing “participants.tsv” file information.
  • center_test_lst (list) – list of centers to include in the testing set.
  • split_method (str) – Between ‘per_center’ or ‘per_person’. If ‘per_center’ the separation fraction are applied to centers, if ‘per_person’ they are applied to the subject list.
  • 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 subjects list.

Return type:

list, list, list

update_metadata(metadata_src_lst, metadata_dest_lst)[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

Object Detection API

object_detection.utils

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

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.

Parameters:
  • transforms (Compose) – Prepreocessing transforms.
  • seg_pair (dict) – Segmentation pair (input, gt and metadata).
  • length (list or tuple) – Patch size of the 3D loader.
  • stride (list or tuple) – Stride value of the 3D loader.
Returns:

Modified transforms.

Return type:

Compose

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.
bounding_box_prior(fname_mask, metadata, slice_axis)[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)
compute_bb_statistics(bounding_box_path)[source]

Measures min, max and average, height, width, depth and volume of bounding boxes from a json file

Parameters:bounding_box_path (string) – Path to json file.
generate_bounding_box_file(subject_list, model_path, log_dir, gpu_number=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_list (list) – List of all subjects in the BIDS directory.
  • model_path (string) – Path to object detection model.
  • log_dir (string) – Log directory.
  • gpu_number (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

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
load_bounding_boxes(object_detection_params, subjects, slice_axis, constrast_lst)[source]

Verifies if bounding_box.json exists in the log directory, if so loads the data, else generates the file if a valid detection model path exists.

Parameters:
  • object_detection_params (dict) – Object detection parameters.
  • subjects (list) – List of all subjects in the BIDS directory.
  • 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

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.
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

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

Evaluation API

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.
  • 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.
__init__(data_pred, data_gt, dim_lst, params=None)[source]

Initialize self. See help(type(self)) for accurate signature.

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_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.

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.

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_vol(data)[source]

Get volume.

label_per_size(data)[source]

Get data with labels corresponding to label size.

Parameters:data (ndarray) – Input data.
Returns:ndarray
run_eval()[source]

Stores evaluation results in dictionary

Returns:dictionary containing evaluation results, data with each object painted a different color
Return type:dict, ndarray
evaluate(bids_path, log_directory, target_suffix, eval_params)[source]

Evaluate predictions from inference step.

Parameters:
  • bids_path (str) – Folder where raw data is stored.
  • log_directory (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

Losses API

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).
  • needs to be slightly above 2 to maintain ideal properties. (It) –
  • omega (float) – Multiplicating factor for non linear part of the loss.
  • epsilon (float) – factor to avoid gradient explosion. It must not be too small
__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 BinaryCrossEntropyLoss[source]

Bases: torch.nn.modules.module.Module

(BinaryCrossEntropyLoss).

Attributes:loss_fct (BCELoss) – Binary cross entropy loss function from torch library.
__init__()[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.
__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 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.
__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 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.
__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 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

__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 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 (float) – If True, then an extra channel is added, which represents the background class.
Attributes:
  • epsilon (float) – Epsilon to avoid division by zero.
  • include_background (float) – If True, then an extra channel is added, which represents the background class.
__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 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.

__init__()[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
  • same index. If no params list is given all default parameter will be used. (at) –
  • losses_list = ["L2loss","DiceLoss"] ((e.g.,) – params_list = [None,{“param1:0.5”}])
Returns:

sum of losses computed on (input,target) with the params

Return type:

tensor

__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.

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.
__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 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

__init__(alpha=0.7, beta=0.3, 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.

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

Main API

run_command(context, n_gif=0, thr_increment=None, resume_training=False)[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 log directory.
  • 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 log_directory) for resume training. This training state is saved everytime a new best model is saved in the log directory.
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.

Return type:

Float or pandas Dataframe

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.
__call__(prediction, ground_truth)[source]

Call self as a function.

__init__(metric_fns)[source]

Initialize self. See help(type(self)) for accurate signature.

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

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

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

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

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

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

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

plot_dice_thr(thr_list, dice_list, opt_thr_idx, fname_out)[source]

Plot Dice results against thresholds.

Parameters:
  • thr_list (list) – Thresholds list.
  • dice_list (list) – Dice results.
  • opt_thr_idx (int) – Index of the optimal threshold.
  • fname_out (str) – Output filename.
plot_roc_curve(tpr, fpr, opt_thr_idx, fname_out)[source]

Plot ROC curve.

Parameters:
  • tpr (list) – True positive rates.
  • fpr (list) – False positive rates.
  • opt_thr_idx (int) – Index of the optimal threshold.
  • fname_out (str) – Output filename.
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

Postprocessing API

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.
__init__(postprocessing_params, data_pred, dim_lst, filename_prefix)[source]

Initialize self. See help(type(self)) for accurate signature.

apply()[source]

Parse postprocessing parameters and apply postprocessing steps to data.

binarize_prediction(thr)[source]

Binarize output.

fill_holes()[source]

Fill holes in the predictions

keep_largest()[source]

Keep largest object in prediction

remove_noise(thr)[source]

Remove prediction values under the given threshold

Parameters:thr (float) – Threshold under which predictions are set to 0.
remove_small(unit, thr)[source]

Remove small objects

Parameters:
  • unit (str) – Indicates the units of the objects: “mm3” or “vox”
  • thr (int) – Minimal object size to keep in input data.
uncertainty(thr, suffix)[source]

Removes the most uncertain predictions.

Parameters:
  • thr (float) – Uncertainty threshold.
  • suffix (str) – Suffix of uncertainty filename.
binarize_with_low_threshold(wrapped)[source]

Decorator to set low values (< 0.001) to 0.

Parameters:wrapped – Given function.
Returns:Functions’ return.
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, 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
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.

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).

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
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).

multilabel_capable(wrapped)[source]

Decorator to make a given function compatible multilabel images.

Parameters:wrapped – Given function.
Returns:Functions’ return.
nifti_capable(wrapped)[source]

Decorator to make a given function compatible with input being Nifti objects.

Parameters:wrapped – Given function.
Returns:Functions’ return.
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

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

Testing API

get_gt(filenames)[source]

Get ground truth data as numpy array.

Parameters:filenames (list) – List of ground truth filenames, one per class.
Returns:4D numpy array.
Return type:ndarray
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

test(model_params, dataset_test, testing_params, log_directory, 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.
  • log_directory (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

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

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.

get_sampler(ds, balance_bool)[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).

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

save_film_params(gammas, betas, contrasts, depth, ofolder)[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) –
  • contrasts (list) – list of the batch sample’s contrasts (eg T2w, T1w)
  • depth (int) –
  • ofolder (str) –
store_film_params(gammas, betas, contrasts, metadata, model, film_layers, depth)[source]

Store FiLM params.

Parameters:
  • gammas (dict) –
  • betas (dict) –
  • contrasts (list) – list of the batch sample’s contrasts (eg T2w, T1w)
  • metadata (list) –
  • model (nn.Module) –
  • film_layers (list) –
  • depth (int) –
Returns:

gammas, betas

Return type:

dict, dict

train(model_params, dataset_train, dataset_val, training_params, log_directory, device, 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) –
  • log_directory (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 log directory.
  • resume_training (bool) – Load a saved model (“checkpoint.pth.tar” in the log_directory) 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

Transformations API

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.
__call__(sample, metadata=None)[source]

Call self as a function.

__init__(mean=0.0, std=0.01)[source]

Initialize self. See help(type(self)) for accurate signature.

class BoundingBoxCrop(size)[source]

Bases: ivadomed.transforms.Crop

Crops image according to given bounding box.

__call__(sample, metadata)[source]

Call self as a function.

class CenterCrop(size)[source]

Bases: ivadomed.transforms.Crop

Make a centered crop of a specified size.

__call__(sample, metadata=None)[source]

Call self as a function.

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) –
__call__(sample, metadata=None)[source]

Call self as a function.

__init__(clip_limit=3.0, kernel_size=(8, 8))[source]

Initialize self. See help(type(self)) for accurate signature.

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.

__call__(sample, metadata, data_type='im')[source]

Call self as a function.

__init__(dict_transforms, requires_undo=False)[source]

Initialize self. See help(type(self)) for accurate signature.

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.
__call__(sample, metadata)[source]

Call self as a function.

__init__(size)[source]

Initialize self. See help(type(self)) for accurate signature.

class CroppableArray[source]

Bases: numpy.ndarray

Zero padding slice past end of array in numpy.

Adapted From: https://stackoverflow.com/a/41155020/13306686

__getitem__(item)[source]

Return self[key].

class DilateGT(dilation_factor)[source]

Bases: ivadomed.transforms.ImedTransform

Randomly dilate a ground-truth tensor.

_images/dilate-gt.png
Parameters:
  • dilation_factor (float) – Controls the number of dilation iterations. For each individual lesion, the number of
  • iterations is computed as follows (dilation) – nb_it = int(round(dilation_factor * sqrt(lesion_area)))
  • dilation_factor <= 0, then no dilation will be performed. (If) –
__call__(sample, metadata=None)[source]

Call self as a function.

__init__(dilation_factor)[source]

Initialize self. See help(type(self)) for accurate signature.

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.
__call__(sample, metadata=None)[source]

Call self as a function.

__init__(alpha_range, sigma_range, p=0.1)[source]

Initialize self. See help(type(self)) for accurate signature.

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.
__call__(sample, metadata=None)[source]

Call self as a function.

__init__(min_percentile=5.0, max_percentile=95.0)[source]

Initialize self. See help(type(self)) for accurate signature.

class ImedTransform[source]

Bases: object

Base class for transforamtions.

__call__(sample, metadata=None)[source]

Call self as a function.

class NormalizeInstance[source]

Bases: ivadomed.transforms.ImedTransform

Normalize a tensor or an array image with mean and standard deviation estimated from the sample itself.

__call__(sample, metadata=None)[source]

Call self as a function.

class NumpyToTensor[source]

Bases: ivadomed.transforms.ImedTransform

Converts nd array to tensor object.

__call__(sample, metadata=None)[source]

Converts nd array to Tensor.

undo_transform(sample, metadata=None)[source]

Converts Tensor to nd array.

class ROICrop(size)[source]

Bases: ivadomed.transforms.Crop

Make a crop of a specified size around a Region of Interest (ROI).

__call__(sample, metadata=None)[source]

Call self as a function.

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)
__call__(sample, metadata=None)[source]

Call self as a function.

__init__(degrees=0, translate=None, scale=None)[source]

Initialize self. See help(type(self)) for accurate signature.

class RandomReverse[source]

Bases: ivadomed.transforms.ImedTransform

Make a randomized symmetric inversion of the different values of each dimensions.

__call__(sample, metadata=None)[source]

Call self as a function.

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.
__call__(sample, metadata=None)[source]

Call self as a function.

__init__(shift_range, prob=0.1)[source]

Initialize self. See help(type(self)) for accurate signature.

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.
__call__(sample, metadata=None)[source]

Resample to a given resolution, in millimeters.

__init__(hspace, wspace, dspace=1.0)[source]

Initialize self. See help(type(self)) for accurate signature.

undo_transform(sample, metadata=None)[source]

Resample to original resolution.

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) –
__call__(sample, metadata, data_type='gt')[source]

Call self as a function.

__init__(compose)[source]

Initialize self. See help(type(self)) for accurate signature.

class UndoTransform(transform)[source]

Bases: object

Call undo transformation.

Attributes:transform (ImedTransform)
Parameters:transform (ImedTransform) –
__call__(sample)[source]

Call self as a function.

__init__(transform)[source]

Initialize self. See help(type(self)) for accurate signature.

apply_preprocessing_transforms(transforms, seg_pair, roi_pair=None)[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

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
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
multichannel_capable(wrapped)[source]

Decorator to make a given function compatible multichannel images.

Parameters:wrapped – Given function.
Returns:Functions’ return.
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

two_dim_compatible(wrapped)[source]

Decorator to make a given function compatible 2D or 3D images.

Parameters:wrapped – Given function.
Returns:Functions’ return.

Utils API

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.
__init__(size)[source]

Initialize self. See help(type(self)) for accurate signature.

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.
__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.

class LoopingPillowWriter(fps=5, metadata=None, codec=None, bitrate=None)[source]

Bases: matplotlib.animation.PillowWriter

finish()[source]

Finish any processing for writing the movie.

class SliceFilter(filter_empty_mask=True, filter_empty_input=True, filter_classification=False, classifier_path=None, device=None, cuda_available=None)[source]

Bases: object

Filter 2D slices from dataset.

If a sample does not meet certain conditions, it is discarded from the dataset.

Parameters:
  • filter_empty_mask (bool) – If True, samples where all voxel labels are zeros are discarded.
  • filter_empty_input (bool) – If True, samples where all voxel intensities are zeros are discarded.
Attributes:
  • filter_empty_mask (bool) – If True, samples where all voxel labels are zeros are discarded.
  • filter_empty_input (bool) – If True, samples where all voxel intensities are zeros are discarded.
__call__(sample)[source]

Call self as a function.

__init__(filter_empty_mask=True, filter_empty_input=True, filter_classification=False, classifier_path=None, device=None, cuda_available=None)[source]

Initialize self. See help(type(self)) for accurate signature.

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
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:
  1. fname_prob, a soft segmentation obtained by averaging the Monte Carlo samples.
  2. 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.
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
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

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’]
init_ivadomed()[source]

Initialize the ivadomed for typical terminal usage.

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

onnx_inference(model_path, inputs)[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

overlap_im_seg(img, seg)[source]

Overlap image (background, greyscale) and segmentation (foreground, jet).

plot_transformed_sample(before, after, list_title=[], 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.
pred_to_nib(data_lst, z_lst, fname_ref, fname_out, slice_axis, debug=False, kernel_dim='2d', bin_thr=0.5, discard_noise=True, postprocessing=None)[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:

Object containing the Network prediction.

Return type:

NibabelObject

reorient_image(arr, slice_axis, nib_ref, nib_ref_canonical)[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).
run_uncertainty(ifolder)[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:ifolder (str) – Folder containing the Monte Carlo samples.
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

save_feature_map(batch, layer_name, log_directory, model, test_input, slice_axis)[source]

Save model feature maps.

Parameters:
  • batch (dict) –
  • layer_name (str) –
  • log_directory (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.
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) –
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.
save_tensorboard_img(writer, epoch, dataset_type, input_samples, gt_samples, preds, is_three_dim=False)[source]

Saves input images, gt and predictions in tensorboard.

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.
segment_volume(folder_model, fname_image, gpu_number=0, options=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_image (str) – image filename (e.g. .nii.gz) to segment.
  • gpu_number (int) – Number representing gpu number if available.
  • options (dict) –

    Contains postprocessing steps and prior filename (fname_prior) which is an image filename (e.g., .nii.gz) containing processing information (e.i., spinal cord segmentation, spinal location or MS lesion classification)

    e.g., 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:

Object containing the soft segmentation.

Return type:

nibabelObject

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.
unstack_tensors(sample)[source]

Unstack tensors.

Parameters:sample (Tensor) –
Returns:list of Tensors.
Return type:list
volume_reconstruction(batch, pred, undo_transforms, smp_idx, volume=None, weight_matrix=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, boolean representing if its the last sample to process, reconstructed volume, weight matrix
Return type:tensor, dict, bool, tensor, tensor
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).

Maths API

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
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.