train image - Train deep learning networks using whole 3D images

This option allows training a network on whole 3D images (as opposed to 3D patches and 2D slices). Two network types can be trained with the image mode:

• autoencoder, that learns to reconstruct the input images,
• cnn, that learns to differentiate two labels assigned to input images.

Two architectures are implemented in clinicadl for the image mode:

• Conv5_FC3, adapted to t1-linear pipeline outputs,
• Conv5_FC3_mni, adapted to t1-extensive pipeline outputs.

Adding a custom architecture

It is possible to add a custom architecture and train it with clinicadl. Detailed instructions can be found here.

train image autoencoder - Train autoencoders using whole 3D images

The objective of an autoencoder is to learn to reconstruct images given in input while performing a dimension reduction.

The difference between the input and the output image is given by the mean squared error. In clinicadl, autoencoders are designed based on a CNN architecture.

Running the task

Here is the command line to train an autoencoder on t1-linear outputs with the predefined architecture of ClinicaDL:

clinicadl train image autoencoder <caps_directory> t1-linear <tsv_path> <output_directory> Conv5_FC3

where mandatory arguments are:

• caps_directory (str) is the input folder containing the neuroimaging data in a CAPS hierarchy.
• tsv_path (str) is the input folder of a TSV file tree generated by clinicadl tsvtool {split|kfold}.
• output_directory (str) is the folder where the results are stored.

Common options

Options that are common to all train input and network types can be found in the introduction of clinicadl train.

There is one specific option for this task:

• --visualization (bool) if this flag is given, inputs of the train and the validation sets and their corresponding reconstructions are written in autoencoder_reconstruction. Inputs are reconstructed based on the model that obtained the best validation loss.

Outputs

The complete output file system is the following (the folder autoencoder_reconstruction is created only if the flag --visualization was given):

results
├── commandline.json
├── environment.txt
└── fold-0
    ├── autoencoder_reconstruction
    │   ├── train
    │   │   ├── input-0.nii.gz
    │   │   ├── input-1.nii.gz
    │   │   ├── input-2.nii.gz
    │   │   ├── output-0.nii.gz
    │   │   ├── output-1.nii.gz
    │   │   └── output-2.nii.gz
    │   └── validation
    │        ├── input-0.nii.gz
    │        ├── input-1.nii.gz
    │        ├── input-2.nii.gz
    │        ├── output-0.nii.gz
    │        ├── output-1.nii.gz
    │        └── output-2.nii.gz
    ├── models
    │    └── best_loss
    │        └── model_best.pth.tar
    └── tensorboard_logs
         ├── train
         │    └── events.out.tfevents.XXXX
         └── validation
              └── events.out.tfevents.XXXX

autoencoder_reconstruction contains the reconstructions of the first three participants of the dataset.

train image cnn - Train classification CNN using whole 3D images

The objective of a CNN is to learn to predict labels associated to images.

The output of a CNN is a vector of size equal to the number of classes in this dataset. This vector can be preprocessed by the softmax function to produce a probability for each class. During training, the CNN is optimized according to the cross-entropy loss. Its value becomes null for a subset of images if the probability of the CNN is 1, with respect to the true class (ground truth) of each image in the subset.

Running the task

Here is the command line to train a CNN on t1-linear outputs with the predefined architecture of ClinicaDL:

clinicadl train image autoencoder <caps_directory> t1-linear <tsv_path> <output_directory> Conv5_FC3

where mandatory arguments are:

• caps_directory (str) is the input folder containing the neuroimaging data in a CAPS hierarchy.
• tsv_path (str) is the input folder of a TSV file tree generated by clinicadl tsvtool {split|kfold}.
• output_directory (str) is the folder where the results are stored.

Common options

Options that are common to all train input and network types can be found in the introduction of clinicadl train.

The options specific to this task are the following:

• --transfer_learning_path (str) is the path to a result folder (output of clinicadl train). The best model of this folder will be used to initialize the network as explained in the implementation details. If nothing is given the initialization will be random.
• --transfer_learning_selection (str) corresponds to the metric according to which the best model of transfer_learning_path will be loaded. This argument will only be taken into account if the source network is a CNN. Choices are best_loss and best_balanced_accuracy. Default: best_balanced_accuracy.

Outputs

The complete output file system is the following:

results
├── commandline.json
├── environment.txt
└── fold-0
    ├── cnn_classification
    │   ├── best_balanced_accuracy
    │   │   ├── train_image_level_metrics.tsv
    │   │   ├── train_image_level_prediction.tsv
    │   │   ├── validation_image_level_metrics.tsv
    │   │   └── validation_image_level_prediction.tsv
    │   └── best_loss
    │        ├── train_image_level_metrics.tsv
    │        ├── train_image_level_prediction.tsv
    │        ├── validation_image_level_metrics.tsv
    │        └── validation_image_level_prediction.tsv
    ├── models
    │    └── best_loss
    │        └── model_best.pth.tar
    └── tensorboard_logs
         ├── train
         │    └── events.out.tfevents.XXXX
         └── validation
              └── events.out.tfevents.XXXX