API Reference

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

Loader API

loader.adaptative

class ivadomed.loader.adaptative.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_suffix=None, transform=None, object_detection_params=None)[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_suffix (str) – List of suffixes for ROI masks.
  • 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_suffix=None, transform=None, object_detection_params=None)[source]

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

class ivadomed.loader.adaptative.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 ivadomed.loader.adaptative.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_suffix=None, object_detection_params=None)[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_suffix (str) – Suffix of the ROI mask.
  • 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_suffix=None, object_detection_params=None)[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, …
ivadomed.loader.adaptative.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 ivadomed.loader.film.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.

ivadomed.loader.film.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

ivadomed.loader.film.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

ivadomed.loader.film.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

ivadomed.loader.film.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’ and ‘constrasts’.
  • 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 ivadomed.loader.loader.Bids3DDataset(root_dir, subject_lst, target_suffix, model_params, contrast_params, slice_axis=2, cache=True, transform=None, metadata_choice=False, roi_suffix=None, multichannel=False, object_detection_params=None)[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_suffix (list) – List of suffixes for ROI masks.
  • 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_suffix=None, multichannel=False, object_detection_params=None)[source]

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

class ivadomed.loader.loader.BidsDataset(root_dir, subject_lst, target_suffix, contrast_params, slice_axis=2, cache=True, transform=None, metadata_choice=False, slice_filter_fn=None, roi_suffix=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”, None or False, relatec to FiLM.
  • slice_filter_fn (SliceFilter) – Class that filters slices according to their content.
  • roi_suffix (list) – List of suffixes for ROI masks.
  • 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_suffix=None, multichannel=False, object_detection_params=None, task='segmentation', soft_gt=False)[source]

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

class ivadomed.loader.loader.MRI2DSegmentationDataset(filename_pairs, slice_axis=2, cache=True, transform=None, slice_filter_fn=None, task='segmentation', 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.
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.
__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', 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 ivadomed.loader.loader.MRI3DSubVolumeSegmentationDataset(filename_pairs, transform=None, length=(64, 64, 64), stride=(0, 0, 0), slice_axis=0)[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.
__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)[source]

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

__len__()[source]

Return the dataset size. The number of subvolumes.

class ivadomed.loader.loader.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.
ivadomed.loader.loader.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, **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 ivadomed.loader.utils.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 ivadomed.loader.utils.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.

ivadomed.loader.utils.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
ivadomed.loader.utils.filter_roi(ds, nb_nonzero_thr)[source]

Filter slices from dataset using ROI data.

This function loops across the dataset (ds) and discards slices 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:
  • ds (mt_datasets.MRI2DSegmentationDataset) – Dataset.
  • nb_nonzero_thr (int) – Threshold.
Returns:

Dataset without filtered slices.

Return type:

mt_datasets.MRI2DSegmentationDataset

ivadomed.loader.utils.get_new_subject_split(path_folder, center_test, split_method, random_seed, train_frac, test_frac, log_directory)[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.
Returns:

Training, validation and testing subjects lists.

Return type:

list, list list

ivadomed.loader.utils.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

ivadomed.loader.utils.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
ivadomed.loader.utils.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

ivadomed.loader.utils.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

ivadomed.loader.utils.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

ivadomed.loader.utils.split_dataset(path_folder, 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:
  • path_folder (str) – Path to BIDS folder.
  • 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

ivadomed.loader.utils.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

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

ivadomed.object_detection.utils.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

ivadomed.object_detection.utils.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.
ivadomed.object_detection.utils.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)
ivadomed.object_detection.utils.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.
ivadomed.object_detection.utils.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

ivadomed.object_detection.utils.get_bounding_boxes(mask)[source]

Generates a 3D bounding box around a given mask. :param mask: Mask of the ROI. :type mask: Numpy array

Returns:Bounding box coordinate (x_min, x_max, y_min, y_max, z_min, z_max).
Return type:list
ivadomed.object_detection.utils.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

ivadomed.object_detection.utils.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.
ivadomed.object_detection.utils.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

ivadomed.object_detection.utils.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 ivadomed.evaluation.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.

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.

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

Removes all unconnected objects smaller than the minimum specified size.

Parameters:data (ndarray) – Input data.
Returns:Array with small objects.
Return type: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
ivadomed.evaluation.evaluate(bids_path, log_directory, path_preds, 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.
  • path_preds (str) – Folder where model predictions were saved
  • 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 ivadomed.losses.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.

..seealso::
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 ivadomed.losses.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 ivadomed.losses.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 ivadomed.losses.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 ivadomed.losses.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 ivadomed.losses.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 ivadomed.losses.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 ivadomed.losses.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 ivadomed.losses.Loss_Combination(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 ivadomed.losses.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 ivadomed.losses.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

ivadomed.main.run_main(config=None)[source]

Run main command.

This function is central in the ivadomed project as training / testing / evaluation commands are run via this function. All the process parameters are defined in the config.

Parameters:config (dict) – Dictionary containing all parameters that are needed for a given process. See Configuration File for more details.
Returns:Returns floats: best loss score for both training and validation. If “test” command: Returns dict: of averaged metrics computed on the testing sub dataset. If “eval” command: Returns a pandas Dataframe: of metrics computed for each subject of the testing sub dataset.
Return type:If “train” command

Metrics API

class ivadomed.metrics.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.

ivadomed.metrics.accuracy_score(prediction, groundtruth)[source]

Accuracy.

Parameters:
  • prediction (ndarray) – First array.
  • groundtruth (ndarray) – Second array.
Returns:

Accuracy.

Return type:

float

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

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

ivadomed.metrics.intersection_over_union(prediction, groundtruth, err_value=0.0)[source]

Intersection of two 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

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

ivadomed.metrics.multi_class_dice_score(im1, im2)[source]

Dice score for multi-label images.

Parameters:
  • im1 (ndarray) – First array.
  • im2 (ndarray) – Second array.
Returns:

Multi-class dice.

Return type:

float

ivadomed.metrics.numeric_score(prediction, groundtruth)[source]

Computation of statistical numerical scores:

  • FP = False Positives
  • FN = False Negatives
  • TP = True Positives
  • TN = True Negatives
Parameters:
  • prediction (ndarray) – Binary prediction.
  • groundtruth (ndarray) – Binary groundtruth.
Returns:

FP, FN, TP, TN

Return type:

float, float, float, float

ivadomed.metrics.precision_score(prediction, groundtruth, err_value=0.0)[source]

Positive predictive value (PPV).

Parameters:
  • prediction (ndarray) – First array.
  • groundtruth (ndarray) – Second array.
  • err_value (float) – Value returned in case of error.
Returns:

Precision score.

Return type:

float

ivadomed.metrics.recall_score(prediction, groundtruth, err_value=0.0)[source]

True positive rate (TPR).

Parameters:
  • prediction (ndarray) – First array.
  • groundtruth (ndarray) – Second array.
  • err_value (float) – Value returned in case of error.
Returns:

Recall score.

Return type:

float

ivadomed.metrics.specificity_score(prediction, groundtruth, err_value=0.0)[source]

True negative rate (TNR).

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

ivadomed.postprocessing.binarize_with_low_threshold(wrapped)[source]

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

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

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

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

ivadomed.postprocessing.multilabel_capable(wrapped)[source]

Decorator to make a given function compatible multilabel images.

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

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

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

ivadomed.testing.run_inference(test_loader, model, model_params, testing_params, ofolder, cuda_available, i_monte_carlo=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.
Returns:

Prediction, Ground-truth of shape n_sample, n_label, h, w, d.

Return type:

ndarray, ndarray

ivadomed.testing.test(model_params, dataset_test, testing_params, log_directory, device, cuda_available=True, metric_fns=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.
Returns:

result metrics.

Return type:

dict

Training API

ivadomed.training.get_loss_function(params)[source]

Get Loss function.

Parameters:params (dict) – See ivadomed.losses.
Returns:imed_losses object.
ivadomed.training.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.

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

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

ivadomed.training.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) –
ivadomed.training.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

ivadomed.training.train(model_params, dataset_train, dataset_val, training_params, log_directory, device, cuda_available=True, metric_fns=None, 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.
  • 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 ivadomed.transforms.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 ivadomed.transforms.BoundingBoxCrop(size)[source]

Bases: ivadomed.transforms.Crop

Crops image according to given bounding box.

__call__(sample, metadata)[source]

Call self as a function.

class ivadomed.transforms.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 ivadomed.transforms.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:: .. seealso:

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 ivadomed.transforms.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 ivadomed.transforms.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 ivadomed.transforms.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 ivadomed.transforms.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 dilation iterations is computed as follows:

nb_it = int(round(dilation_factor * sqrt(lesion_area)))

If dilation_factor <= 0, then no dilation will be performed.

__call__(sample, metadata=None)[source]

Call self as a function.

__init__(dilation_factor)[source]

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

class ivadomed.transforms.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 ivadomed.transforms.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 ivadomed.transforms.ImedTransform[source]

Bases: object

Base class for transforamtions.

__call__(sample, metadata=None)[source]

Call self as a function.

class ivadomed.transforms.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 ivadomed.transforms.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 ivadomed.transforms.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 ivadomed.transforms.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 ivadomed.transforms.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 ivadomed.transforms.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 ivadomed.transforms.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 ivadomed.transforms.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 ivadomed.transforms.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.

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

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

Decorator to make a given function compatible multichannel images.

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

ivadomed.transforms.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.
ivadomed.transforms.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 ivadomed.utils.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 ivadomed.utils.SliceFilter(filter_empty_mask=True, filter_empty_input=True)[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)[source]

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

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

ivadomed.utils.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
ivadomed.utils.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.
ivadomed.utils.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’]
ivadomed.utils.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

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

ivadomed.utils.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.
ivadomed.utils.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)[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.
Returns:

Object containing the Network prediction.

Return type:

NibabelObject

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

ivadomed.utils.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.
ivadomed.utils.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) –
ivadomed.utils.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.
ivadomed.utils.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.
ivadomed.utils.segment_volume(folder_model, fname_image, fname_prior=None, gpu_number=0)[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,

  • fname_image (str) – image filename (e.g. .nii.gz) to segment.
  • fname_prior (str) –

    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.

  • gpu_number (int) – Number representing gpu number if available.
Returns:

Object containing the soft segmentation.

Return type:

nibabelObject

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

Unstack tensors.

Parameters:sample (Tensor) –
Returns:list of Tensors.
Return type:list
ivadomed.utils.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
ivadomed.utils.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).