Skip to content

Introduction

Ninon Burgos edited this page Sep 10, 2020 · 6 revisions

Introduction

The outputs of the Clinica pipelines are stored following a specific structure called CAPS (ClinicA Processed Structure), which is inspired from the BIDS structure and the upcoming BIDS Derivatives. The CAPS specifications are described in detail here.

Motivation

When the development of Clinica started in 2015, the BIDS specifications did not provide specific rules for the processed data. As a result, the goal of CAPS (designed by the Aramis Lab) was to define a hierarchy for the data processed using Clinica. The idea is to include in a single folder all the results of the different pipelines and organize the data following the main patterns of the BIDS specification.

!!! note It is our objective for the CAPS and BIDS Derivatives specifications to converge.

Definitions

We use the same definitions as the BIDS Specifications concerning Dataset, Subject, Session, MRI acquisition, Data type, Task, Event and Run. On top on that, we define the notion of:

  1. Group - a set of subjects (group key). You will find this notion when working on any group-wise analysis (e.g. template creation from a list of subjects, statistical analysis). This is simply a label name that will define the group of subjects used for this analysis. It will be written in your output CAPS folder, for possible future reuses.

For example, an AD group label could be used in case you create a template for a group of Alzheimer’s disease patients. Any time you would like to use this AD template you will need to provide the group label used to identify the pipeline output obtained from this group. You might also use CNvsAD, for instance, as group label for a statistical group comparison.

  1. Longitudinal template - a set of sessions (long key). You will find this notion when working on longitudinal datasets. This is simply a label that will define the set of sessions considered. Unlike group, longitudinal template is dedicated to intra-subject analysis. Besides, the longitudinal label for a participant is defined concatenating the different session labels in alphabetical order so that the longitudinal label will be unique. For instance, if the intra-subject template is computed on M18 and M00 sessions, the longitudinal ID will be long-M00M18.

Differences with BIDS

Several differences exist between the BIDS and CAPS specifications.

  • Instead of the BIDS derivatives/ folder, the processed data are stored in the CAPS folder.

  • CAPS assumes that the session is always present in a BIDS dataset even though there is a single session. In other words, all datasets are considered longitudinal, even when they have only one session.

  • NifTi files generated by a Clinica pipeline are always compressed, while this is not systematic with the BIDS specifications.

Subject and group naming

The naming convention for subjects (participants) is identical to the BIDS Specifications 1.0.0.

Groups should be assigned unique labels. Labels can consist of letters and/or numbers.

Examples

Subject level example

This CAPS folder contains the outputs of the dwi-preprocessing-* pipeline and dwi-dti pipeline of a fictional participant CLNC01 at session M00:

subjects/
└─ sub-CLNC01/
   └─ ses-M00/
      └─ dwi/
         ├─ dti_based_processing/
         │  ├─ atlas_statistics/
         │  │  ├─ sub-CNLC01_ses-M00_acq-axial_dwi_space-JHUTracts0_res-1x1x1_map-FA_statistics.tsv
         │  │  ├─ sub-CNLC01_ses-M00_acq-axial_dwi_space-JHUTracts0_res-1x1x1_map-MD_statistics.tsv
         │  │  ├─ sub-CNLC01_ses-M00_acq-axial_dwi_space-JHUTracts0_res-1x1x1_map-AD_statistics.tsv
         │  │  └─ sub-CNLC01_ses-M00_acq-axial_dwi_space-JHUTracts0_res-1x1x1_map-RD_statistics.tsv
         │  ├─ native_space/
         │  │  ├─ sub-CNLC01_ses-M00_acq-axial_dwi_model-DTI_diffmodel.nii.gz
         │  │  ├─ sub-CNLC01_ses-M00_acq-axial_dwi_space-b0_FA.nii.gz
         │  │  ├─ sub-CNLC01_ses-M00_acq-axial_dwi_space-b0_MD.nii.gz
         │  │  ├─ sub-CNLC01_ses-M00_acq-axial_dwi_space-b0_AD.nii.gz
         │  │  ├─ sub-CNLC01_ses-M00_acq-axial_dwi_space-b0_RD.nii.gz
         │  │  └─ sub-CNLC01_ses-M00_acq-axial_dwi_space-b0_DECFA.nii.gz
         │  └─ normalized_space/
         │     ├─ sub-CNLC01_ses-M00_acq-axial_dwi_space-MNI152Lin_res-1x1x1_AD.nii.gz
         │     ├─ sub-CNLC01_ses-M00_acq-axial_dwi_space-MNI152Lin_res-1x1x1_affine.mat
         │     ├─ sub-CNLC01_ses-M00_acq-axial_dwi_space-MNI152Lin_res-1x1x1_deformation.nii.gz
         │     ├─ sub-CNLC01_ses-M00_acq-axial_dwi_space-MNI152Lin_res-1x1x1_FA.nii.gz
         │     ├─ sub-CNLC01_ses-M00_acq-axial_dwi_space-MNI152Lin_res-1x1x1_MD.nii.gz
         │     └─ sub-CNLC01_ses-M00_acq-axial_dwi_space-MNI152Lin_res-1x1x1_RD.nii.gz
         └─ preprocessing/
            ├─ sub-CNLC01_ses-M00_acq-axial_dwi_space-b0_brainmask.nii.gz
            ├─ sub-CNLC01_ses-M00_acq-axial_dwi_space-b0_preproc.bval
            ├─ sub-CNLC01_ses-M00_acq-axial_dwi_space-b0_preproc.bvec
            └─ sub-CNLC01_ses-M00_acq-axial_dwi_space-b0_preproc.nii.gz

Group level example

This CAPS folder contains the outputs of a group comparison of patients with Alzheimer’s disease (AD) and healthy subjects (HC) thanks to the statistics-surface pipeline. Results are stored under the group ID ADvsHC:

groups/
└─ group-ADvsHC/
   └─ statistics/
      ├─ participant.tsv
      └─ surfstat_group_comparison/
         ├─ group-ADvsHC_HC-lt-AD_measure-ct_fwhm-20_FDR.jpg
         ├─ group-ADvsHC_HC-lt-AD_measure-ct_fwhm-20_FDR.mat
         ├─ group-ADvsHC_HC-lt-AD_measure-ct_fwhm-20_TStatistics.jpg
         ├─ group-ADvsHC_HC-lt-AD_measure-ct_fwhm-20_TStatistics.mat
         ├─ group-ADvsHC_HC-lt-AD_measure-ct_fwhm-20_correctedPValue.jpg
         ├─ group-ADvsHC_HC-lt-AD_measure-ct_fwhm-20_correctedPValue.mat
         ├─ group-ADvsHC_HC-lt-AD_measure-ct_fwhm-20_uncorrectedPValue.jpg
         ├─ group-ADvsHC_HC-lt-AD_measure-ct_fwhm-20_uncorrectedPValue.mat
         ├─ group-ADvsHC_glm.json
         ├─ group-ADvsHC_AD-lt-HC_measure-ct_fwhm-20_FDR.jpg
         ├─ group-ADvsHC_AD-lt-HC_measure-ct_fwhm-20_FDR.mat
         ├─ group-ADvsHC_AD-lt-HC_measure-ct_fwhm-20_TStatistics.jpg
         ├─ group-ADvsHC_AD-lt-HC_measure-ct_fwhm-20_TStatistics.mat
         ├─ group-ADvsHC_AD-lt-HC_measure-ct_fwhm-20_correctedPValue.jpg
         ├─ group-ADvsHC_AD-lt-HC_measure-ct_fwhm-20_correctedPValue.mat
         ├─ group-ADvsHC_AD-lt-HC_measure-ct_fwhm-20_uncorrectedPValue.jpg
         └─ group-ADvsHC_AD-lt-HC_measure-ct_fwhm-20_uncorrectedPValue.mat

Subject level example with longitudinal analysis

This CAPS folder contains the outputs of longitudinal segmentations performed with FreeSurfer for a fictional participant CLNC01 at sessions M00 and M18. First, the t1-freesurfer pipeline is run on the two sessions. Then, the t1-freesurfer-longitudinal pipeline will compute the intra-subject template sub-CLNC01_long-M00M18 using the M00 and M18 sessions. This template is finally used to longitudinally correct the segmentations, whose results are stored in the sub-CLNC01_ses-M00.long.sub-CLNC01_long-M00M18 and sub-CLNC01_ses-M18.long.sub-CLNC01_long-M00M18 folders.

Of note, the <time_point_id>.long.<template_id> naming comes from FreeSurfer when running the longitudinal recon-all command.

subjects/
├── sub-CLNC01/
│   ├── long-M00M18/
│   │   ├── long-M00M18_sessions.tsv
│   │   └── freesurfer_unbiased_template/
│   │       └── sub-CLNC01_long-M00M18/
│   │           ├── base-tps/
│   │           ├── label/
│   │           ├── mri/
│   │           ├── stats/
│   │           └── surf/
│   ├── ses-M00/
│   │   └── t1/
│   │       ├── freesurfer_cross_sectional/
│   │       │   ├── regional_measures/
│   │       │   └── sub-CLNC01_ses-M00/
│   │       │       ├── label/
│   │       │       ├── mri/
│   │       │       ├── stats/
│   │       │       └── surf/
│   │       └── long-M00M18/
│   │           └── freesurfer_longitudinal/
│   │               ├── regional_measures/
│   │               └── sub-CLNC01_ses-M00.long.sub-CLNC01_long-M00M18/
│   │                   ├── label/
│   │                   ├── mri/
│   │                   ├── stats/
│   │                   └── surf/
│   └── ses-M18/
│       └── t1/
│           ├── freesurfer_cross_sectional/
│           │   ├── regional_measures/
│           │   └── sub-CLNC01_ses-M18/
│           │       ├── label/
│           │       ├── mri/
│           │       ├── stats/
│           │       └── surf/
│           └── long-M00M18
│               └── freesurfer_longitudinal
│                   ├── regional_measures
│                   └── sub-CLNC01_ses-M18.long.sub-CLNC01_long-M00M18/
│                       ├── label/
│                       ├── mri/
│                       ├── stats/
│                       └── surf/
└── sub-CLNC02/
    ├── ...