Skip to content

extract - 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.

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 extract <caps_directory> <tsv_file> <working_dir> <tensor_format>

where:

  • 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.
  • tsv_file (str) is the TSV file with subjects/sessions to process.
  • working_dir (str) is the working directory to save temporary file.
  • 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.

Regarding the default values

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

The full list of options available for tensor extraction
usage: clinicadl extract [-h] [-ps PATCH_SIZE] [-ss STRIDE_SIZE]
                         [-sd SLICE_DIRECTION] [-sm {original,rgb}]
                         [-np NPROC]
                         caps_dir tsv_file working_dir {slice,patch,whole}

positional arguments:
  caps_dir              Data using CAPS structure.
  tsv_file              TSV file with subjects/sessions to process.
  working_dir           Working directory to save temporary file.
  {slice,patch,whole}   Method used to extract features. Three options:
                        'slice' to get 2D slices from the MRI, 'patch' to get
                        3D volumetric patches or 'whole' to get the complete
                        MRI.

optional arguments:
  -h, --help            show this help message and exit
  -ps PATCH_SIZE, --patch_size PATCH_SIZE
                        Patch size (only for 'patch' extraction) e.g:
                        --patch_size 50
  -ss STRIDE_SIZE, --stride_size STRIDE_SIZE
                        Stride size (only for 'patch' extraction) e.g.:
                        --stride_size 50
  -sd SLICE_DIRECTION, --slice_direction SLICE_DIRECTION
                        Slice direction (only for 'slice' extraction). Three
                        options: '0' -> Sagittal plane, '1' -> Coronal plane
                        or '2' -> Axial plane
  -sm {original,rgb}, --slice_mode {original,rgb}
                        Slice mode (only for 'slice' extraction). Two options:
                        'original' to save one single channel (intensity),
                        'rgb' to saves three channel (with same intensity).
  -np NPROC, --nproc NPROC
                        Number of cores used for processing

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.

Describing this pipeline in your paper

Example of paragraph

These results have been obtained using the deeplearning-prepare-data pipeline of Clinica [Routier et al.; Wen et al., 2020]. More precisely,

  • 3D images

  • 3D patches with patch size of <patch_size> and stride size of <stride_size>

  • 2D slices in {sagittal | coronal | axial} plane and saved in {three identical channels | a single channel}

were extracted and converted to PyTorch tensors [Paszke et al., 2019].