Skip to content

train - Train deep learning networks for neuroimaging classification

This task enables the training of a convolutional neural network (CNN) classifier or an autoencoder using different formats of inputs (whole 3D images, 3D patches or 2D slices), as defined in [Wen et al., 2020]. It mainly relies on the PyTorch deep learning library [Paszke et al., 2019].

Prerequisites

You need to execute the clinicadl tsvtool getlabels and clinicadl tsvtool {split|kfold} commands prior to running this task to have the correct TSV file organization. Moreover, there should be a CAPS, obtained running the preprocessing pipeline wanted.

Parcellation prediction

It is now possible to predict the intensities in different regions of a neuronatomical atlas with the binary classification task. In this case the outputs of the preprocessing pipeline clinica run t1-volume must exist in the CAPS.

Running the task

The training task can be run with the following command line: 

clinicadl train <mode> <network_type> <caps_directory> \
                <preprocessing> <tsv_path> <output_directory> <architecture>
where mandatory arguments are:

  • mode (str) is the type of input used. Must be chosen between image, patch, roi and slice.
  • network_type (str) is the type of network used. The options depend on the type of input used, but at most it can be chosen between autoencoder, cnn and multicnn.
  • caps_directory (str) is the input folder containing the neuroimaging data in a CAPS hierarchy. In case of multi-cohort training, must be a path to a TSV file.
  • preprocessing (str) corresponds to the preprocessing pipeline whose outputs will be used for training.
  • tsv_path (str) is the input folder of a TSV file tree generated by clinicadl tsvtool {split|kfold}. In case of multi-cohort training, must be a path to a TSV file.
  • output_directory (str) is the folder where the results are stored.
  • architecture (str) is the name of the architecture used (e.g. Conv5_FC3). It must correspond to a class that inherits from nn.Module imported in tools/deep_learning/models/__init__.py.

from_json mode

To shorten the command line, the option from_json was added to clinicadl train in order to define all the arguments in a JSON file.

Options shared for all values of mode are organized in groups:

  • Computational resources
    • --use_cpu (bool) forces to use CPU. Default behaviour is to try to use a GPU and to raise an error if it is not found.
    • --nproc (int) is the number of workers used by the DataLoader. Default value: 2.
    • --batch_size (int) is the size of the batch used in the DataLoader. Default value: 2.
    • --evaluation_steps (int) gives the number of iterations to perform an evaluation internal to an epoch. Default will only perform an evaluation at the end of each epoch.
  • Data management
    • --diagnoses (list of str) is the list of the labels that will be used for training. These labels must be chosen from {AD,CN,MCI,sMCI,pMCI}. Default will use AD and CN labels.
    • --baseline (bool) is a flag to load only _baseline.tsv files instead of .tsv files comprising all the sessions. Default: False.
    • --unnormalize (bool) is a flag to disable min-max normalization that is performed by default. Default: False.
    • --data_augmentation (list of str) is the list of data augmentation transforms applied to the training data. Must be chosen in [None, Noise, Erasing, CropPad, Smoothing]. Default: False.
    • --sampler (str) is the sampler used on the training set. It must be chosen in [random, weighted]. weighted will give a stronger weight to underrepresented classes. Default: random.
    • --multi_cohort (bool) is a flag indicated that multi-cohort training is performed. In this case, caps_directory and tsv_path must be paths to TSV files.
    • --predict_atlas_intensities (str) corresponds to a neuroanatomical atlas. If given the network learns to compute the grey matter intensity according to this atlas. The number of output nodes will be 2 + number of regions in the atlas. Must be chosen in the following list: AAL2, AICHA, Hammers, LPBA40, "Neuromorphometrics.
    • --atlas_weight (float) is the weight put on the MSE loss computed to learn the grey matter intensities when added to the cross-entropy loss. Default: 1.
    • --merged_tsv_path (str) is the path to the output of clinica iotools merged-tsv (or the concatenation of the outputs in case of multi-cohort framework). Giving this file can accelerate the computation when computing the grey matter intensities.
  • Cross-validation arguments
    • --n_splits (int) is a number of splits k to load in the case of a k-fold cross-validation. Default will load a single-split.
    • --split (list of int) is a subset of folds that will be used for training. By default all splits available are used.
  • Optimization parameters
    • --epochs (int) is the maximum number of epochs. Default: 20.
    • --learning_rate (float) is the learning rate used to perform weight update. Default: 1e-4.
    • --weight_decay (float) is the weight decay used by the Adam optimizer. Default: 1e-4.
    • --dropout (float) is the rate of dropout applied in dropout layers. Default: 0.
    • --patience (int) is the number of epochs for early stopping patience. Default: 0.
    • --tolerance (float) is the value used for early stopping tolerance. Default: 0.
    • --accumulation_steps (int) gives the number of iterations during which gradients are accumulated before performing the weights update. This allows to virtually increase the size of the batch. Default: 1.

Specific options

Other options are highly dependent on the input and the type of network used. Please refer to the corresponding sections for more information.

Tip

Typing clinicadl train {image|patch|roi|slice} --help will show you the networks that are available for training in this category.

Outputs

At the first level of the file system, outputs are identical regardless of the mode and network_type. Below is an example of the output file system for a network trained with data split between train and validation sets corresponding to a 5-fold cross-validation.

results
├── commandline.json
├── environment.txt
├── fold-0
├── fold-1
├── fold-2
├── fold-3
└── fold-4

where:

  • commandline.json is a file containing all the arguments necessary to reproduce the experiment,
  • environment.txt contains description of the environment used for the experiment,
  • fold-<i> is a folder containing the result of the run on the i-th split of the 5-fold cross-validation.

Validation procedure

A run of clinicadl train is necessarily associated to a TSV file system defining a series of data splits (k-fold cross-validation or single split). In the case of a single split the results folder will only contain a folder named fold-0.

The structure of the fold-<i> folders partly depends on the type of network trained. They may contain the following folders:

  • models is the folder containing checkpoints saved at the end of each epoch, as well as the best model according to a specific metric on the validation set. The selection of a best model is only performed at the end of an epoch (a model cannot be selected based on internal evaluations in an epoch).
  • tensorboard_logs contains logs that can be visualized with TensorBoard.
  • cnn_classification specific to (multi)cnn contains TSV files corresponding to the evaluation of the best models as saved in models.
  • autoencoder_reconstruction specific to autoencoder contains reconstructions of the best model selected on the validation loss.