This section contains a collection of useful scripts for quality control during the training of models.


run_visualization(input, config, number, output, roi)[source]

Utility function to visualize Data Augmentation transformations.

Data augmentation is a key part of the Deep Learning training scheme. This script aims at facilitating the fine-tuning of data augmentation parameters. To do so, this script provides a step-by-step visualization of the transformations that are applied on data.

This function applies a series of transformations (defined in a configuration file -c) to -n 2D slices randomly extracted from an input image (-i), and save as png the resulting sample after each transform.

For example:

ivadomed_visualize_transforms -i t2s.nii.gz -n 1 -c config.json -r t2s_seg.nii.gz

Provides a visualization of a series of three transformation on a randomly selected slice:


And on a binary mask:

ivadomed_visualize_transforms -i t2s_gmseg.nii.gz -n 1 -c config.json -r t2s_seg.nii.gz


  • input (string) – Image filename. Flag: –input, -i
  • config (string) – Configuration file filename. Flag: –config, -c
  • number (int) – Number of slices randomly extracted. Flag: –number, -n
  • output (string) – Folder path where the results are saved. Flag: –ofolder, -o
  • roi (string) – Filename of the region of interest. Only needed if ROICrop is part of the transformations. Flag: -roi, -r


convert_pytorch_to_onnx(model, dimension, gpu=0)[source]

Convert PyTorch model to ONNX.

The integration of Deep Learning models into the clinical routine requires cpu optimized models. To export the PyTorch models to ONNX format and to run the inference using ONNX Runtime is a time and memory efficient way to answer this need.

This function converts a model from PyTorch to ONNX format, with information of whether it is a 2D or 3D model (-d).

  • model (string) – Model filename. Flag: –model, -m.
  • dimension (int) – Indicates whether the model is 2D or 3D. Choice between 2 or 3. Flag: –dimension, -d
  • gpu (string) – GPU ID, if available. Flag: –gpu, -g


automate_training(config, param, fixed_split, all_combin, n_iterations=1, run_test=False, all_logs=False)[source]

Automate multiple training processes on multiple GPUs.

Hyperparameter optimization of models is tedious and time-consuming. This function automatizes this optimization across multiple GPUs. It runs trainings, on the same training and validation datasets, by combining a given set of parameters and set of values for each of these parameters. Results are collected for each combination and reported into a dataframe to allow their comparison. The script efficiently allocates each training to one of the available GPUs.

# TODO: add example of DF

  • config (string) – Configuration filename, which is used as skeleton to configure the training. Some of its parameters (defined in param file) are modified across experiments. Flag: –config, -c
  • param (string) –

    json file containing parameters configurations to compare. Parameter “keys” of this file need to match the parameter “keys” of config file. Parameter “values” are in a list. Flag: –param, -p Example:

    "default_model": {"depth": [2, 3, 4]}
  • fixed_split (bool) – If True, all the experiments are run on the same training/validation/testing subdatasets. Flag: –fixed-split
  • all_combin (bool) – If True, all parameters combinations are run. Flag: –all-combin
  • n_iterations (int) – Controls the number of time that each experiment (ie set of parameter) are run. Flag: –n-iteration, -n
  • run_test (bool) – If True, the trained model is also run on the testing subdataset. flag: –run-test
  • all_logs (bool) – If True, all the log directories are kept for every iteration. Flag: –all-logs, -l


compute_statistics(dataframe, n_iterations, run_test=True)[source]

Compares the performance of models at inference time on a common testing dataset using paired t-tests.

It uses a dataframe generated by scripts/ with the parameter --run-test (used to run the
models on the testing dataset).

# TODO: add example of DF

  • dataframe (pandas.Dataframe) – Dataframe of results generated by automate_training. Flag: –dataframe, -df
  • n_iterations (int) – Indicates the number of time that each experiment (ie set of parameter) was run. Flag: –n_iteration, -n
  • run_test (int) – Indicates if the comparison is done on the performances on either the testing subdataset (True) either on the training/validation subdatasets. Flag: –run_test


extract_mid_slice_and_convert_coordinates_to_heatmaps(path, suffix, aim=-1)[source]

This function takes as input a path to a dataset and generates a set of images: (i) mid-sagittal image and (ii) heatmap of disc labels associated with the mid-sagittal image.


ivadomed_prepare_dataset_vertebral_labeling -p path/to/bids -s _T2w -a 0
  • path (string) – path to BIDS dataset form which images will be generated. Flag: –path, -p
  • suffix (string) – suffix of image that will be processed (e.g., T2w). Flag: –suffix, -s
  • aim (int) – If aim is not 0, retrieves only labels with value = aim, else create heatmap with all labels. Flag: –aim, -a

None. Images are saved in BIDS folder


extract_small_dataset(input, output, n=10, contrast_list=None, include_derivatives=True, seed=-1)[source]

Extract small BIDS dataset from a larger BIDS dataset.


ivadomed_extract_small_dataset -i path/to/BIDS/dataset -o path/of/small/BIDS/dataset -n 10 -c T1w,T2w -d 0 -s 1234
  • input (str) – Input BIDS folder. Flag: –input, -i
  • output (str) – Output folder. Flag: –output, -o
  • n (int) – Number of subjects in the output folder. Flag: –number, -n
  • contrast_list (list) – List of image contrasts to include. If set to None, then all available contrasts are included. Flag: –contrasts, -c
  • include_derivatives (bool) – If True, derivatives/labels/ content is also copied, only the raw images otherwise. Flag: –derivatives,-d
  • seed (int) – Set np.random.RandomState to ensure reproducibility: the same subjects will be selected if the function is run several times on the same dataset. If set to -1, each function run is independent. Flag: –seed, -s.