Configuration File

All parameters used for loading data, training and predicting are contained within a single JSON configuration file. This section describes how to set up this configuration file.

For convenience, here is an generic configuration file: config_config.json.

Below are other, more specific configuration files:

General Parameters

command

Run the specified command.

type

string

options

train

train a model on a training/validation sub-datasets

test

evaluate a trained model on a testing sub-dataset

segment

segment a entire dataset using a trained model

{
    "command": "train"
}

gpu_ids

List of IDs of one or more GPUs to use. Default: [0].

type

list[int]

{
    "gpu_ids": [1,2,3]
}

Note

Currently only ivadomed_automate_training supports the use of more than one GPU.

path_output

Folder name that will contain the output files (e.g., trained model, predictions, results).

type

string

{
    "path_output": "tmp/spineGeneric"
}

model_name

Folder name containing the trained model (ONNX format) and its configuration file, located within log_directory/.

type

string

"log_directory/seg_gm_t2star/seg_gm_t2star.onnx"
"log_directory/seg_gm_t2star/seg_gm_t2star.json"

When possible, the folder name will follow the following convention: task_(animal)_region_(contrast) with

task = {seg, label, find}
animal = {human, dog, cat, rat, mouse, ...}
region = {sc, gm, csf, brainstem, ...}
contrast = {t1, t2, t2star, dwi, ...}
{
    "model_name": "seg_gm_t2star"
}

debugging

Extended verbosity and intermediate outputs. Default: False.

type

boolean

{
    "debugging": true
}

log_file

Name of the file to be logged to, located within log_directory/. Default: log.

type

string

{
    "log_file": "log"
}

Weights & Biases (WandB)

WandB is an additional option to track your DL experiments. It provides a feature-rich dashboard (accessible through any web-browser) to track and visualize the learning curves, gradients, and media. It is recommended to setup a personal WandB account to track experiments on WandB, however, you can still train ivadomed models without an account, since the metrics are logged on Tensorboard by default.

{
    "wandb": {
        "wandb_api_key": "<alphanumeric-key-here>"
    }
}

project_name

Defines the name of the current project to which the groups and runs will be synced. Default: my_project.

type

string

{
    "wandb": {
        "project_name": "my-temp-project"
    }
}

group_name

Defines the name of the group to which the runs will be synced. On the WandB Dashboard,

the groups can be found on clicking the Projects tab on the left. Default: my_group.

type

string

{
    "wandb": {
        "group_name": "my-temp-group"
    }
}

run_name

Defines the name of the current run (or, experiment). All the previous and active runs

can be found under the corresponding group on the WandB Dashboard. Default: run-1.

type

string

{
    "wandb": {
        "run_name": "run-1"
    }
}

Note

Using the same run_name does not replace the previous run but does create multiple entries of the same name. If left empty then the default is a random string assigned by WandB.

Note

We recommend defining the project/group/run names such that hierarchy is easily understandable. For instance, project_name could be the name of the dataset or the problem you are working (i.e. brain tumor segmentation/spinal cord lesion segmentation etc.), the group_name could be the various models you are willing to train, and the run_name could be the various experiments within a particular model (i.e. typically with different hyperparameters).

log_grads_every

Defines the frequency (in number of steps) of the logging of gradients on to the Dashboard to track and visualize

their histograms as the model trains. Default: 100.

type

int

{
    "wandb": {
        "log_grads_every": 100
    }
}

Note

There are two important points to be noted: (1) Gradients can be large so they can consume more storage space if log_grads_every is set to a small number, (2) log_grads_every also depends on the total duration of training, i.e. if the model is run for only a few epochs, gradients might not be logged if log_grads_every is too large. Hence, the right frequency of gradient logging depends on the training duration and model size.

Note

If debugging = True is specified in the config file, the training and validation input images, ground truth labels, and the model predictions are also periodically logged on WandB, which can be seen under Media on the WandB Dashboard.

Loader Parameters

path_data

Path(s) of the BIDS folder(s).

type

str or list[str]

{
    "loader_parameters": {
        "path_data": ["path/to/data_example_spinegeneric", "path/to/other_data_example"]
    }
}

Alternatively:

{
    "loader_parameters": {
        "path_data": "path/to/data_example_spinegeneric"
    }
}

bids_config

(Optional). Path of the custom BIDS configuration file for BIDS non-compliant modalities. Default: ivadomed/config/config_bids.json.

type

string

{
    "loader_parameters": {
        "bids_config": "ivadomed/config/config_bids.json"
    }
}

subject_selection

Used to specify a custom subject selection from a dataset.

type

dict

options

n

List containing the number subjects of each metadata. Default: [].

type

list[int]

metadata

List of metadata used to select the subjects. Each metadata should be the name

of a column from the participants.tsv file. Default: [].

type

list[str]

value

List of metadata values of the subject to be selected. Default: [].

type

list[str]

{
    "loader_parameters": {
        "subject_selection": {
            "n": [5, 10],
            "metadata": ["disease", "disease"],
            "value": ["healthy", "ms"]
        }
    }
}

In this example, a subdataset composed of 5 healthy subjects and 10 ms subjects will be selected for training/testing.

target_suffix

Suffix list of the derivative file containing the ground-truth of interest. Default: [].

type

list[str]

{
    "loader_parameters": {
        "target_suffix": ["_seg-manual", "_lesion-manual"]
    }
}

The length of this list controls the number of output channels of the model (i.e. out_channel). If the list has a length greater than 1, then a multi-class model will be trained. If a list of list(s) is input for a training, (e.g. [["_seg-manual-rater1", "_seg-manual-rater2"], ["_lesion-manual-rater1", "_lesion-manual-rater2"]), then each sublist is associated with one class but contains the annotations from different experts: at each training iteration, one of these annotations will be randomly chosen.

extensions

Used to specify a list of file extensions to be selected for training/testing.

Must include the file extensions of both the raw data and derivatives. Default: [].

type

list[str]

{
    "loader_parameters": {
        "extensions": [".png"]
    }
}

contrast_params

type

dict

options

training_validation

List of image contrasts (e.g. T1w, T2w) loaded for the training and

validation. If multichannel is true, this list represents the different

channels of the input tensors (i.e. its length equals model’s in_channel).

Otherwise, the contrasts are mixed and the model has only one input channel

(i.e. model’s in_channel=1).

type

list[str]

testing

List of image contrasts (e.g. T1w, T2w) loaded in the testing dataset.

Same comment as for training_validation regarding multichannel.

type

list[str]

balance

Enables to weight the importance of specific channels (or contrasts) in the

dataset: e.g. {'T1w': 0.1} means that only 10% of the available T1w

images will be included into the training/validation/test set. Please set

multichannel to false if you are using this parameter. Default: {}.

type

dict

{
    "loader_parameters": {
        "contrast_params": {
            "training_validation": ["T1w", "T2w", "T2star"],
            "testing": ["T1w", "T2w", "T2star"],
            "balance": {}
        }
    }
}

multichannel

Indicated if more than a contrast (e.g. T1w and T2w) is used by the model. Default: False.

type

boolean

See details in both training_validation and testing for the contrasts that are input.

{
    "loader_parameters": {
        "multichannel": false
    }
}

bids_validate

Indicates if the loader should validate the dataset for compliance with BIDS. Default: True.

type

boolean

{
    "loader_parameters": {
        "bids_validate": true
    }
}

slice_axis

Sets the slice orientation for 3D NIfTI files on which the model will be used. Default: axial.

type

string

options

sagittal

plane dividing body into left/right

coronal

plane dividing body into front/back

axial

plane dividing body into top/bottom

{
    "loader_parameters": {
        "slice_axis": "sagittal"
    }
}

slice_filter_params

Discard a slice from the dataset if it meets a condition, defined below.

A slice is an entire 2D image taken from a 3D volume (e.g. an image of size 128x128 taken from a volume of size 128x128x16).

Therefore, the parameter slice_filter_params is applicable for 2D models only.

type

dict

options

filter_empty_input

Discard slices where all voxel intensities are zeros. Default: True.

type

boolean

filter_empty_mask

Discard slices where all voxel labels are zeros. Default: False.

type

boolean

filter_absent_class

Discard slices where all voxel labels are zero for one or more classes

(this is most relevant for multi-class models that need GT for all classes at training time). Default: False.

type

boolean

filter_classification

Discard slices where all images fail a custom classifier filter. If used,

classifier_path must also be specified, pointing to a saved PyTorch classifier. Default: False.

type

boolean

{
    "loader_parameters": {
        "slice_filter_params": {
            "filter_empty_mask": false,
            "filter_empty_input": true
        }
    }
}

patch_filter_params

Discard a 2D or 3D patch from the dataset if it meets a condition at training time, defined below.

A 2D patch is a portion of a 2D image (e.g. a patch of size 32x32 taken inside an image of size 128x128).

A 3D patch is a portion of a 3D volume (e.g. a patch of size 32x32x16 from a volume of size 128x128x16).

Therefore, the parameter patch_filter_params is applicable for 2D or 3D models.

In addition, contrary to slice_filter_params which applies at training and testing time, patch_filter_params

is applied only at training time. This is because the reconstruction algorithm for predictions from patches

needs to have the predictions for all patches at testing time.

type

dict

options

filter_empty_input

Discard 2D or 3D patches where all voxel intensities are zeros. Default: False.

type

boolean

filter_empty_mask

Discard 2D or 3D patches where all voxel labels are zeros. Default: False.

type

boolean

filter_absent_class

Discard 2D or 3D patches where all voxel labels are zero for one or more classes

(this is most relevant for multi-class models that need GT for all classes).

Default: False.

type

boolean

{
    "loader_parameters": {
        "patch_filter_params": {
            "filter_empty_mask": false,
            "filter_empty_input": false
        }
    }
}

roi_params

Parameters for the region of interest.

type

dict

options

suffix

Suffix of the derivative file containing the ROI used to crop

(e.g. _seg-manual) with ROICrop as transform. Default: null.

type

string

slice_filter_roi

If the ROI mask contains less than slice_filter_roi non-zero voxels

the slice will be discarded from the dataset. This feature helps with

noisy labels, e.g., if a slice contains only 2-3 labeled voxels, we do

not want to use these labels to crop the image. This parameter is only

considered when using ROICrop. Default: null.

type

int

{
    "loader_parameters": {
        "roi_params": {
            "suffix": null,
            "slice_filter_roi": null
        }
    }
}

soft_gt

Indicates if a soft mask will be used as ground-truth to train

and / or evaluate a model. In particular, the masks are not binarized

after interpolations implied by preprocessing or data-augmentation operations.

Approach inspired by the SoftSeg paper. Default: False.

type

boolean

{
    "loader_parameters": {
        "soft_gt": true
    }
}

Note

To get the full advantage of the soft segmentations, in addition to setting soft_gt: true the following keys in the config file must also be changed: (i) final_activation: relu - to use the normalized ReLU activation function (ii) loss: AdapWingLoss - a regression loss described in the paper. Note: It is also recommended to use the DiceLoss since convergence with AdapWingLoss is sometimes difficult to achieve.

is_input_dropout

Indicates if input-level dropout should be applied during training.

This option trains a model to be robust to missing modalities by setting

to zero input channels (from 0 to all channels - 1). Always at least one

channel will remain. If one or more modalities are already missing, they will

be considered as dropped. Default: False.

type

boolean

{
    "loader_parameters": {
        "is_input_dropout": true
    }
}

Split Dataset

fname_split

Name of the joblib file that was generated during a previous training, and that contains the list of training/validation/testing filenames.

Specifying the .joblib file ensures reproducible data splitting across multiple trainings. When specified, the other split parameters are

ignored. If null is specified, a new splitting scheme is performed.

type

string

{
    "split_dataset": {
        "fname_split": null
    }
}

random_seed

Seed used by the random number generator to split the dataset between

training/validation/testing sets. The use of the same seed ensures the same split between

the sub-datasets, which is useful for reproducibility. Default: 6.

type

int

{
    "split_dataset": {
        "random_seed": 6
    }
}

split_method

Metadata contained in a BIDS tabular (TSV) file or a BIDS sidecar JSON file on which the files are shuffled

then split between train/validation/test, according to train_fraction and test_fraction.

For examples, participant_id will shuffle all participants from the participants.tsv file

then split between train/validation/test sets. Default: participant_id.

type

string

{
    "split_dataset": {
        "split_method": "participant_id"
    }
}

data_testing

(Optional) Used to specify a custom metadata to only include in the testing dataset (not validation).

For example, to not mix participants from different institutions between the train/validation set and the test set,

use the column institution_id from participants.tsv in data_type.

type

dict

options

data_type

Metadata to include in the testing dataset.

If specified, the test_fraction is applied to this metadata.

If not specified, data_type is the same as split_method. Default: null.

type

string

data_value

(Optional) List of metadata values from the data_type column to include in the testing dataset.

If specified, the testing set contains only files from the data_value list and the test_fraction is not used.

If not specified, create a random data_value according to data_type and test_fraction. Default: [].

type

list

{
    "split_dataset": {
        "data_testing": {"data_type": "institution_id", "data_value":[]}
    }
}

balance

Metadata contained in participants.tsv file with categorical values. Each category

will be evenly distributed in the training, validation and testing datasets. Default: null.

type

string

required

false

{
    "split_dataset": {
        "balance": null
    }
}

train_fraction

Fraction of the dataset used as training set. Default: 0.6.

type

float

range

[0, 1]

{
    "split_dataset": {
        "train_fraction": 0.6
    }
}

test_fraction

Fraction of the dataset used as testing set. Default: 0.2.

type

float

range

[0, 1]

{
    "split_dataset": {
        "test_fraction": 0.2
    }
}

Note

The fraction of the dataset used as validation set will correspond to 1 - train_fraction - test_fraction.
For example: 1 - 0.6 - 0.2 = 0.2.

Cascaded Models

object_detection_params

type

dict

required

false

options

object_detection_path

Path to the object detection model. The folder,

configuration file, and model need to have the same name

(e.g. findcord_tumor/, findcord_tumor/findcord_tumor.json, and

findcord_tumor/findcord_tumor.onnx, respectively). The model’s prediction

will be used to generate bounding boxes. Default: null.

type

string

safety_factor

List of length 3 containing the factors to multiply each dimension of the

bounding box. Ex: If the original bounding box has a size of 10x20x30 with

a safety factor of [1.5, 1.5, 1.5], the final dimensions of the bounding box

will be 15x30x45 with an unchanged center. Default: [1.0, 1.0, 1.0].

type

[int, int, int]

{
    "object_detection_params": {
        "object_detection_path": null,
        "safety_factor": [1.0, 1.0, 1.0]
    }
}

Training Parameters

batch_size

Defines the number of samples that will be propagated through the network. Default: 18.

type

int

range

(0, inf)

{
    "training_parameters": {
        "batch_size": 24
    }
}

loss

Metadata for the loss function. Other parameters that could be needed in the

Loss function definition: see attributes of the Loss function of interest (e.g. 'gamma': 0.5 for FocalLoss).

type

dict

options

name

Name of the loss function class. See ivadomed.losses. Default: DiceLoss.

type

string

{
    "training_parameters": {
        "loss": {
            "name": "DiceLoss"
        }
    }
}

training_time

type

dict

options

num_epochs

type

int

range

(0, inf)

early_stopping_epsilon

If the validation loss difference during one epoch

(i.e. abs(validation_loss[n] - validation_loss[n-1] where n is the current epoch)

is inferior to this epsilon for early_stopping_patience consecutive epochs,

then training stops. Default: 0.001.

type

float

early_stopping_patience

Number of epochs after which the training is stopped if the validation loss

improvement is smaller than early_stopping_epsilon. Default: 50.

type

int

range

(0, inf)

{
    "training_parameters": {
        "training_time": {
            "num_epochs": 100,
            "early_stopping_patience": 50,
            "early_stopping_epsilon": 0.001
        }
    }
}

scheduler

A predefined framework that adjusts the learning rate between epochs or iterations as the training progresses.

type

dict

options

initial_lr

Initial learning rate. Default: 0.001.

type

float

lr_scheduler

Other parameters depend on the scheduler of interest.

type

dict

options

name

One of CosineAnnealingLR, CosineAnnealingWarmRestarts and CyclicLR.

Please find documentation here. Default: CosineAnnealingLR.

type

string

max_lr

Upper learning rate boundaries in the cycle for each parameter group. Default: 1e-2.

type

float

base_lr

Initial learning rate which is the lower boundary in the cycle for each parameter group.

Default: 1e-5.

type

float

{
    "training_parameters": {
        "scheduler": {
            "initial_lr": 0.001,
            "lr_scheduler": {
                "name": "CosineAnnealingLR",
                "max_lr": 1e-2,
                "base_lr": 1e-5
            }
        }
    }
}

balance_samples

Balance labels in both the training and the validation datasets.

type

dict

options

applied

Indicates whether to use a balanced sampler or not. Default: False.

type

boolean

type

Indicates which metadata to use to balance the sampler.

Choices: gt or the name of a column from the participants.tsv file

(i.e. subject-based metadata). Default: gt.

type

string

{
    "training_parameters": {
        "balance_samples": {
            "applied": false,
            "type": "gt"
        }
    }
}

mixup_alpha

Alpha parameter of the Beta distribution, see original paper on the Mixup technique. Default: null.

type

float

{
    "training_parameters": {
        "mixup_alpha": null
    }
}

transfer_learning

A learning method where a model pretrained for a task is reused as the starting point for a model on a second task.

type

dict

options

retrain_model

Filename of the pretrained model (path/to/pretrained-model). If null,

no transfer learning is performed and the network is trained from scratch. Default: null.

type

string

retrain_fraction

Controls the fraction of the pre-trained model that will be fine-tuned. For

instance, if set to 0.5, the second half of the model will be fine-tuned while

the first layers will be frozen. Default: 1.0.

type

float

range

[0, 1]

reset

If true, the weights of the layers that are not frozen are reset. If false, they are kept as loaded. Default: True.

type

boolean

 {
     "training_parameters": {
         "transfer_learning": {
             "retrain_model": null,
             "retrain_fraction": 1.0,
             "reset": true
         }
     }
}

Architecture

Architectures for both segmentation and classification are available and described in the Architectures section. If the selected architecture is listed in the loader file, a classification (not segmentation) task is run. In the case of a classification task, the ground truth will correspond to a single label value extracted from target, instead being an array (the latter being used for the segmentation task).

default_model

Define the default model (Unet) and mandatory parameters that are common to all available Architectures.

For custom architectures (see below), the default parameters are merged with the parameters that are specific

to the tailored architecture.

type

dict

required

true

options

name

Default: Unet

type

string

dropout_rate

Default: 0.3

type

float

bn_momentum

Defines the importance of the running average: (1 - bn_momentum). A large running

average factor will lead to a slow and smooth learning.

See PyTorch’s BatchNorm classes for more details. for more details. Default: 0.1

type

float

depth

Number of down-sampling operations. Default: 3

type

int

range

(0, inf)

final_activation

Final activation layer. Options: sigmoid (default), relu (normalized ReLU), or softmax.

type

string

required

false

length_2D

(Optional) Size of the 2D patches used as model’s input tensors.

type

[int, int]

required

false

stride_2D

(Optional) Strictly positive integers: Pixels’ shift over the input matrix to create 2D patches.

Ex: Stride of [1, 2] will cause a patch translation of 1 pixel in the 1st dimension and 2 pixels in

the 2nd dimension at every iteration until the whole input matrix is covered.

type

[int, int]

required

false

is_2d

Indicates if the model is 2D, if not the model is 3D. If is_2d is False, then parameters

length_3D and stride_3D for 3D loader need to be specified (see Modified3DUNet).

Default: True.

type

boolean

{
    "default_model": {
        "name": "Unet",
        "dropout_rate": 0.3,
        "bn_momentum": 0.1,
        "depth": 3,
        "final_activation": "sigmoid"
        "is_2d": true,
        "length_2D": [256, 256],
        "stride_2D": [244, 244]
    }
}

FiLMedUnet

U-Net network containing FiLM layers to condition the model with another data type (i.e. not an image).

type

dict

required

false

options

applied

Set to true to use this model. Default: False.

type

boolean

metadata

Choice between mri_params, contrasts (i.e. image-based metadata) or the

name of a column from the participants.tsv file (i.e. subject-based metadata).

type

string

options

mri_params

Vectors of [FlipAngle, EchoTime, RepetitionTime, Manufacturer]

(defined in the json of each image) are input to the FiLM generator.

contrasts

Image contrasts (according to config/contrast_dct.json) are input to the FiLM generator.

film_layers

List of 0 or 1 indicating on which layer FiLM is applied.

{
    "FiLMedUnet": {
        "applied": false,
        "metadata": "contrasts",
        "film_layers": [0, 1, 0, 0, 0, 0, 0, 0, 0, 0]
    }
}

HeMISUnet

A U-Net model inspired by HeMIS to deal with missing contrasts.

type

dict

required

false

options

applied

Set to true to use this model.

type

boolean

missing_probability

Initial probability of missing image contrasts as model’s input

(e.g. 0.25 results in a quarter of the image contrasts, i.e. channels, that

will not be sent to the model for training).

type

float

range

[0, 1]

missing_probability_growth

Controls missing probability growth at each epoch: at each epoch, the

missing_probability is modified with the exponent missing_probability_growth.

type

float

{
    "HeMISUnet": {
        "applied": true,
        "missing_probability": 0.00001,
        "missing_probability_growth": 0.9,
        "contrasts": ["T1w", "T2w"],
        "ram": true,
        "path_hdf5": "/path/to/HeMIS.hdf5",
        "csv_path": "/path/to/HeMIS.csv",
        "target_lst": ["T2w"],
        "roi_lst": null
    }
}

Modified3DUNet

The main differences with the original UNet resides in the use of LeakyReLU instead of ReLU, InstanceNormalisation

instead of BatchNorm due to small batch size in 3D and the addition of segmentation layers in the decoder.

type

dict

required

false

options

applied

Set to true to use this model.

type

boolean

length_3D

Size of the 3D patches used as model’s input tensors. Default: [128, 128, 16].

type

[int, int, int]

stride_3D

Voxels’ shift over the input matrix to create patches. Ex: Stride of [1, 2, 3]

will cause a patch translation of 1 voxel in the 1st dimension, 2 voxels in

the 2nd dimension and 3 voxels in the 3rd dimension at every iteration until

the whole input matrix is covered. Default: [128, 128, 16].

type

[int, int, int]

attention

Use attention gates in the Unet’s decoder. Default: False.

type

boolean

required

false

n_filters

Number of filters in the first convolution of the UNet.

This number of filters will be doubled at each convolution. Default: 16.

type

int

required

false

{
    "Modified3DUNet": {
        "applied": false,
        "length_3D": [128, 128, 16],
        "stride_3D": [128, 128, 16],
        "attention": false,
        "n_filters": 8
    }
}

Transformations

Transformations applied during data augmentation. Transformations are sorted in the order they are applied to the image samples. For each transformation, the following parameters are customizable:

  • applied_to: list between "im", "gt", "roi". If not specified, then the transformation is applied to all loaded samples. Otherwise, only applied to the specified types: Example: ["gt"] implies that this transformation is only applied to the ground-truth data.

  • dataset_type: list between "training", "validation", "testing". If not specified, then the transformation is applied to the three sub-datasets. Otherwise, only applied to the specified subdatasets. Example: ["testing"] implies that this transformation is only applied to the testing sub-dataset.

NumpyToTensor

Converts nd array to tensor object.

type

dict

{
    "transformation": {
        "NumpyToTensor": {
            "applied_to": ["im", "gt"]
        }
    }
}

CenterCrop

Make a centered crop of a specified size.

type

dict

options

size

type

list[int]

applied_to

type

list[str]

{
    "transformation": {
        "CenterCrop": {
            "applied_to": ["im", "gt"],
            "size":  [512, 256, 16]
        }
    }
}

ROICrop

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

type

dict

options

size

type

list[int]

applied_to

type

list[str]

{
    "transformation": {
        "ROICrop": {
            "size": [48, 48],
            "applied_to": ["im", "roi"]
        }
    }
}

NormalizeInstance

Normalize a tensor or an array image with mean and standard deviation estimated from

the sample itself.

type

dict

options

applied_to

type

list[str]

{
    "transformation": {
        "NormalizeInstance": {
            "applied_to": ["im"]
        }
    }
}

RandomAffine

Apply Random Affine transformation.

type

dict

options

degrees

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 tuple defines this range.

type

float or tuple(float)

range

(0, inf)

translate

Length 2 or 3 depending on the sample shape (2D or 3D). Defines

the maximum range of translation along each axis.

type

list[float]

range

[0, 1]

scale

Length 2 or 3 depending on the sample shape (2D or 3D). Defines

the maximum range of scaling along each axis. Default: [0., 0., 0.].

type

list[float]

range

[0, 1]

{
    "transformation": {
        "RandomAffine": {
            "translate": [0.03, 0.03],
            "applied_to": ["im"],
            "dataset_type": ["training"],
            "scale": [0.1, 0.5],
            "degrees": 180
        }
    }
}

RandomShiftIntensity

Add a random intensity offset.

type

dict

options

shift_range

Range from which the offset applied is randomly selected.

type

(float, float)

{
    "transformation": {
        "RandomShiftIntensity": {
            "shift_range": [28.0, 30.0]
        }
    }
 }

ElasticTransform

Applies elastic transformation. See also:

Best practices for convolutional neural networks applied to visual document analysis.

type

dict

options

alpha_range

Deformation coefficient.

type

(float, float)

sigma_range

Standard deviation.

type

(float, float)

p

Probability. Default: 0.1

type

float

{
    "transformation": {
        "ElasticTransform": {
            "alpha_range": [28.0, 30.0],
            "sigma_range":  [3.5, 4.5],
            "p": 0.1,
            "applied_to": ["im", "gt"],
            "dataset_type": ["training"]
        }
    }
}

Resample

Resample image to a given resolution.

type

dict

options

hspace

Resolution along the first axis, in mm.

type

float

range

[0, 1]

wspace

Resolution along the second axis, in mm.

type

float

range

[0, 1]

dspace

Resolution along the third axis, in mm.

type

float

range

[0, 1]

{
    "transformation": {
        "Resample": {
            "hspace": 0.75,
            "wspace": 0.75,
            "dspace": 1
        }
    }
}

AdditiveGaussianNoise

Adds Gaussian Noise to images.

type

dict

options

mean

Mean of Gaussian noise. Default: 0.0.

type

float

std

Standard deviation of Gaussian noise. Default: 0.01.

type

float

{
    "transformation": {
        "AdditiveGaussianNoise": {
            "mean": 0.0,
            "std": 0.02
        }
    }
}

DilateGT

Randomly dilate a ground-truth tensor.

type

dict

options

dilation_factor

Controls the number of iterations of ground-truth dilation depending on

the size of each individual lesion, data augmentation of the training set.

Use 0 to disable.

type

float

{
    "transformation": {
        "DilateGT": {
            "dilation_factor": 0
        }
    }
}

HistogramClipping

Perform intensity clipping based on percentiles.

type

dict

options

min_percentile

Lower clipping limit. Default: 5.0.

type

float

range

[0, 100]

max_percentile

Higher clipping limit. Default: 95.0.

type

float

range

[0, 100]

{
    "transformation": {
        "HistogramClipping": {
            "min_percentile": 50,
            "max_percentile": 75
        }
    }
}

Clahe

Applies Contrast Limited Adaptive Histogram Equalization for enhancing the local image contrast.

type

dict

options

clip_limit

Clipping limit, normalized between 0 and 1. Default: 3.0.

type

float

kernel_size

Defines the shape of contextual regions used in the algorithm.

List length = dimension, i.e. 2D or 3D. Default: [8, 8].

type

list[int]

{
    "transformation": {
        "Clahe": {
            "clip_limit": 0.5,
            "kernel_size": [8, 8]
        }
    }
}

RandomReverse

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

type

dict

{
    "transformation": {
        "RandomReverse": {
            "applied_to": ["im"]
        }
    }
}

RandomGamma

Randomly changes the contrast of an image by gamma exponential.

type

dict

options

log_gamma_range

Log gamma range for changing contrast.

type

[float, float]

p

Probability of performing the gamma contrast. Default: 0.5.

type

float

{
    "transformation": {
        "RandomGamma": {
            "log_gamma_range": [-3.0, 3.0],
            "p": 0.5,
            "applied_to": ["im"],
            "dataset_type": ["training"]
        }
    }
}

RandomBiasField

Applies a random MRI bias field artifact to the image via torchio.RandomBiasField().

type

dict

options

coefficients

Maximum magnitude of polynomial coefficients.

type

float

order

Order of the basis polynomial functions.

type

int

p

Probability of applying the bias field. Default: 0.5.

type

float

{
    "transformation": {
        "RandomBiasField": {
            "coefficients": 0.5,
            "order": 3,
            "p": 0.5,
            "applied_to": ["im"],
            "dataset_type": ["training"]
        }
    }
}

RandomBlur

Applies a random blur to the image.

type

dict

options

sigma_range

Standard deviation range for the gaussian filter.

type

(float, float)

p

Probability of performing blur. Default: 0.5.

type

float

{
    "transformation": {
        "RandomBlur": {
            "sigma_range": [0.0, 2.0],
            "p": 0.5,
            "applied_to": ["im"],
            "dataset_type": ["training"]
        }
    }
}

Uncertainty

Uncertainty computation is performed if n_it>0 and at least epistemic or aleatoric is true. Note: both epistemic and aleatoric can be true.

epistemic

Model-based uncertainty with Monte Carlo Dropout. Default: false.

type

boolean

{
    "uncertainty": {
        "epistemic": true
    }
}

aleatoric

Image-based uncertainty with test-time augmentation. Default: false.

type

boolean

{
    "uncertainty": {
        "aleatoric": true
    }
}

n_it

Number of Monte Carlo iterations. Set to 0 for no uncertainty computation. Default: 0.

type

int

{
    "uncertainty": {
        "n_it": 2
    }
}

Postprocessing

binarize_prediction

Binarizes predictions according to the given threshold thr. Predictions below the

threshold become 0, and predictions above or equal to threshold become 1.

type

dict

options

thr

Threshold. To use soft predictions (i.e. no binarisation, float between 0 and 1)

for metric computation, indicate -1. Default: 0.5.

type

float

range

[0, 1]

{
    "postprocessing": {
        "binarize_prediction": {
            "thr": 0.1
        }
    }
}

binarize_maxpooling

Binarize by setting to 1 the voxel having the maximum prediction across all classes.

Useful for multiclass models. No parameters required (i.e., {}). Default: {}.

type

dict

{
    "postprocessing": {
        "binarize_maxpooling": {}
    }
}

fill_holes

Fill holes in the predictions. No parameters required (i.e., {}). Default: {}.

type

dict

{
    "postprocessing": {
        "fill_holes": {}
    }
}

keep_largest

Keeps only the largest connected object in prediction. Only nearest neighbors are

connected to the center, diagonally-connected elements are not considered neighbors.

No parameters required (i.e., {}). Default: {}.

type

dict

{
    "postprocessing": {
        "keep_largest": {}
    }
}

remove_noise

Sets to zero prediction values strictly below the given threshold thr.

type

dict

options

thr

Threshold. Threshold set to -1 will not apply this postprocessing step. Default: -1.

type

float

range

[0, 1]

{
    "postprocessing": {
        "remove_noise": {
            "thr": 0.1
        }
    }
}

remove_small

Remove small objects from the prediction. An object is defined as a group of connected

voxels. Only nearest neighbors are connected to the center, diagonally-connected

elements are not considered neighbors.

type

dict

options

thr

Minimal object size. If a list of thresholds is chosen, the length should

match the number of predicted classes. Default: 3.

type

int or list[int]

unit

Either vox for voxels or mm3. Indicates the unit used to define the

minimal object size. Default: vox.

type

string

{
    "postprocessing": {
        "remove_small": {
            "unit": "vox",
            "thr": 3
        }
    }
}

threshold_uncertainty

Removes the most uncertain predictions (set to 0) according to a threshold thr

using the uncertainty file with the suffix suffix. To apply this method,

uncertainty needs to be evaluated on the predictions with the uncertainty parameter.

type

dict

options

thr

Threshold. Threshold set to -1 will not apply this postprocessing step.

type

float

range

[0, 1]

suffix

Indicates the suffix of an uncertainty file. Choices: _unc-vox.nii.gz for

voxel-wise uncertainty, _unc-avgUnc.nii.gz for structure-wise uncertainty

derived from mean value of _unc-vox.nii.gz within a given connected object,

_unc-cv.nii.gz for structure-wise uncertainty derived from coefficient of

variation, _unc-iou.nii.gz for structure-wise measure of uncertainty

derived from the Intersection-over-Union of the predictions, or _soft.nii.gz

to threshold on the average of Monte Carlo iterations.

type

string

{
    "postprocessing": {
        "threshold_uncertainty": {
            "thr": -1,
            "suffix": "_unc-vox.nii.gz"
        }
    }
}

Evaluation Parameters

Dict. Parameters to get object detection metrics (lesions true positive rate, lesions false detection rate and Hausdorff score), and this, for defined object sizes.

object_detection_metrics

Indicate if object detection metrics (lesions true positive rate, lesions false detection rate

and Hausdorff score) are computed or not at evaluation time. Default: true

type

boolean

{
    "evaluation_parameters": {
        "object_detection_metrics": true
    }
}

target_size

type

dict

options

thr

These values will create several consecutive target size bins. For instance

with a list of two values, we will have three target size bins: minimal size

to first list element, first list element to second list element, and second

list element to infinity. Default: [20, 100].

object_detection_metrics must be true for the target_size to apply.

type

list[int]

unit

Either vox for voxels or mm3. Indicates the unit used to define the

target object sizes. Default: vox.

type

string

{
    "evaluation_parameters": {
        "target_size": {
            "thr": [20, 100],
            "unit": "vox"
        }
    }
}

overlap

type

dict

options

thr

Minimal object size overlapping to be considered a TP, FP, or FN. Default: 3.

object_detection_metrics must be true for the overlap to apply.

type

int

unit

Either vox for voxels or mm3. Indicates the unit used to define the overlap.

Default: vox.

type

string

{
    "evaluation_parameters": {
        "overlap": {
            "thr": 3,
            "unit": "vox"
        }
    }
}