Skip to content

extract-tensor - Prepare input data for deep learning with PyTorch

This pipeline prepares images generated by Clinica to be used with the PyTorch deep learning library [Paszke et al., 2019]. Three types of tensors are proposed: 3D images, 3D patches or 2D slices.

Currently, only outputs from the t1-linear pipeline can be processed.

Tip

This pipeline can be also run with Clinica by typing clinica run deeplearning-prepare-data pipeline. Results are equivalent.

Prerequisites

You need to have performed the t1-linear pipeline on your T1-weighted MRI.

Running the pipeline

The pipeline can be run with the following command line: 

clinicadl preprocessing extract-tensor <preprocessing> <caps_directory> <tsv_file> <working_dir> <tensor_format>

where:

  • preprocessing (str) corresponds to the preprocessing pipeline whose outputs will be formatted. Currently, only t1-linear pipeline is available.
  • caps_directory (str) is the folder containing the results of the t1-linear pipeline and the output of the present command, both in a CAPS hierarchy.
  • tensor_format (str) is the format of the extracted tensors. You can choose between image to convert to PyTorch tensor the whole 3D image, patch to extract 3D patches and slice to extract 2D slices from the image.

By default the features are extracted from the cropped image (see the documentation of the t1-linear pipeline. You can deactivate this behaviour with the --use_uncropped_image flag.

Pipeline options if you use patch extraction:

  • --patch_size: (int) patch size. Default value: 50.
  • --stride_size: (int) stride size. Default value: 50.

Pipeline options if you use slice extraction:

  • --slice_direction: (int) slice direction. You can choose between 0 (sagittal plane), 1(coronal plane) or 2 (axial plane). Default value: 0.
  • --slice_mode: (str) slice mode. You can choose between rgb (will save the slice in three identical channels) or single (will save the slice in a single channel). Default value: rgb.

Regarding the default values

When using patch or slice extraction, default values were set according to [Wen et al., 2020].

Outputs

In the following subsections, files with the .pt extension denote tensors in PyTorch format.

The full list of output files can be found in the ClinicA Processed Structure (CAPS) Specification.

Image-based outputs

Results are stored in the following folder of the CAPS hierarchy: subjects/<subject_id>/<session_id>/deeplearning_prepare_data/image_based/t1_linear.

The main output files are:

  • <source_file>_space-MNI152NLin2009cSym[_desc-Crop]_res-1x1x1_T1w.pt: tensor version of the 3D T1w image registered to the MNI152NLin2009cSym template and optionally cropped.

Patch-based outputs

Results are stored in the following folder of the CAPS hierarchy: subjects/<subject_id>/<session_id>/deeplearning_prepare_data/patch_based/t1_linear.

The main output files are:

  • <source_file>_space-MNI152NLin2009cSym[_desc-Crop]_res-1x1x1_patchsize-<N>_stride-<M>_patch-<i>_T1w.pt: tensor version of the <i>-th 3D isotropic patch of size <N> with a stride of <M>. Each patch is extracted from the T1w image registered to the MNI152NLin2009cSym template and optionally cropped.

Slice-based outputs

Results are stored in the following folder of the CAPS hierarchy: subjects/<subject_id>/<session_id>/deeplearning_prepare_data/slice_based/t1_linear.

The main output files are:

  • <source_file>_space-MNI152NLin2009cSym[_desc-Crop]_res-1x1x1_axis-{sag|cor|axi}_channel-{single|rgb}_T1w.pt: tensor version of the <i>-th 2D slice in sagittal, coronal or axial plane using three identical channels (rgb) or one channel (single). Each slice is extracted from the T1w image registered to the MNI152NLin2009cSym template and optionally cropped.