Skip to content

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. Similar to the BIDS specifications, the CAPS specifications are versioned such that it can evolve in time. The version of the CAPS specifications is indicated in a dataset_description.json file, located at the root of the CAPS folder. This file is similar to the dataset_description.json file of the BIDS specifications and provides other metadata on the dataset.

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

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.

  2. 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 M018 and M000 sessions, the longitudinal ID will be long-M000M018.

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. Compression is recommended by the BIDS specifications but not mandatory.

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 M000:

dataset_description.json
subjects/
└─ sub-CLNC01/
   └─ ses-M000/
      └─ dwi/
         ├─ dti_based_processing/
         │  ├─ atlas_statistics/
         │  │  ├─ sub-CNLC01_ses-M000_dwi_space-JHUTracts0_res-1x1x1_map-FA_statistics.tsv
         │  │  ├─ sub-CNLC01_ses-M000_dwi_space-JHUTracts0_res-1x1x1_map-MD_statistics.tsv
         │  │  ├─ sub-CNLC01_ses-M000_dwi_space-JHUTracts0_res-1x1x1_map-AD_statistics.tsv
         │  │  └─ sub-CNLC01_ses-M000_dwi_space-JHUTracts0_res-1x1x1_map-RD_statistics.tsv
         │  ├─ native_space/
         │  │  ├─ sub-CNLC01_ses-M000_dwi_model-DTI_diffmodel.nii.gz
         │  │  ├─ sub-CNLC01_ses-M000_dwi_space-b0_FA.nii.gz
         │  │  ├─ sub-CNLC01_ses-M000_dwi_space-b0_MD.nii.gz
         │  │  ├─ sub-CNLC01_ses-M000_dwi_space-b0_AD.nii.gz
         │  │  ├─ sub-CNLC01_ses-M000_dwi_space-b0_RD.nii.gz
         │  │  └─ sub-CNLC01_ses-M000_dwi_space-b0_DECFA.nii.gz
         │  └─ normalized_space/
         │     ├─ sub-CNLC01_ses-M000_dwi_space-MNI152Lin_res-1x1x1_AD.nii.gz
         │     ├─ sub-CNLC01_ses-M000_dwi_space-MNI152Lin_res-1x1x1_affine.mat
         │     ├─ sub-CNLC01_ses-M000_dwi_space-MNI152Lin_res-1x1x1_deformation.nii.gz
         │     ├─ sub-CNLC01_ses-M000_dwi_space-MNI152Lin_res-1x1x1_FA.nii.gz
         │     ├─ sub-CNLC01_ses-M000_dwi_space-MNI152Lin_res-1x1x1_MD.nii.gz
         │     └─ sub-CNLC01_ses-M000_dwi_space-MNI152Lin_res-1x1x1_RD.nii.gz
         └─ preprocessing/
            ├─ sub-CNLC01_ses-M000_dwi_space-b0_brainmask.nii.gz
            ├─ sub-CNLC01_ses-M000_dwi_space-b0_preproc.bval
            ├─ sub-CNLC01_ses-M000_dwi_space-b0_preproc.bvec
            └─ sub-CNLC01_ses-M000_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:

dataset_description.json
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 M000 and M018. 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-M000M018 using the M000 and M018 sessions. This template is finally used to longitudinally correct the segmentations, whose results are stored in the sub-CLNC01_ses-M000.long.sub-CLNC01_long-M000M018 and sub-CLNC01_ses-M018.long.sub-CLNC01_long-M000M018 folders.

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

dataset_description.json
subjects/
├── sub-CLNC01/
│   ├── long-M000M018/
│   │   ├── long-M000M018_sessions.tsv
│   │   └── freesurfer_unbiased_template/
│   │       └── sub-CLNC01_long-M000M018/
│   │           ├── base-tps/
│   │           ├── label/
│   │           ├── mri/
│   │           ├── stats/
│   │           └── surf/
│   ├── ses-M000/
│   │   └── t1/
│   │       ├── freesurfer_cross_sectional/
│   │       │   ├── regional_measures/
│   │       │   └── sub-CLNC01_ses-M000/
│   │       │       ├── label/
│   │       │       ├── mri/
│   │       │       ├── stats/
│   │       │       └── surf/
│   │       └── long-M000M018/
│   │           └── freesurfer_longitudinal/
│   │               ├── regional_measures/
│   │               └── sub-CLNC01_ses-M000.long.sub-CLNC01_long-M000M018/
│   │                   ├── label/
│   │                   ├── mri/
│   │                   ├── stats/
│   │                   └── surf/
│   └── ses-M018/
│       └── t1/
│           ├── freesurfer_cross_sectional/
│           │   ├── regional_measures/
│           │   └── sub-CLNC01_ses-M018/
│           │       ├── label/
│           │       ├── mri/
│           │       ├── stats/
│           │       └── surf/
│           └── long-M000M018
│               └── freesurfer_longitudinal
│                   ├── regional_measures
│                   └── sub-CLNC01_ses-M018.long.sub-CLNC01_long-M000M018/
│                       ├── label/
│                       ├── mri/
│                       ├── stats/
│                       └── surf/
└── sub-CLNC02/
    ├── ...

Contact us !