Skip to content

Interacting with Clinica

Preparing your data

The easiest way to use Clinica is to have your data organized using the BIDS standard. BIDS is currently becoming the standard for data organization in the brain imaging community and we strongly recommend to use it.

If your dataset does not follow this standard, you will need to convert to it:

  • If your data are in DICOM format, you can use one of the converters from the BIDS website.
  • Otherwise, Clinica includes converters for public datasets such as ADNI, AIBL and OASIS. See here for more details.


Clinica does not handle cross-sectional BIDS dataset. In practical terms, this means your dataset must always contains a session information. This BIDS-tree view does not work with Clinica:

─── BIDS
    └── sub-CLNC0001
        ├── anat
        │    └── sub-CLNC0001_T1w.nii.gz
        └── pet
             ├── sub-CLNC0001_task-rest_acq-FDG_pet.json
             └── sub-CLNC0001_task-rest_acq-FDG_pet.nii.gz
A correct one is:
─── BIDS
    └── sub-CLNC0001
        └── ses-M00
            ├── anat
            │    └── sub-CLNC0001_ses-M00_T1w.nii.gz
            └── pet
                 ├── sub-CLNC0001_ses-M00_task-rest_acq-FDG_pet.json
                 └── sub-CLNC0001_ses-M00_task-rest_acq-FDG_pet.nii.gz


If you need to create BIDS compliant datasets or need tutorials on BIDS, you can look at this BIDS Starter Kit.

Clinica command-line interface

Clinica's main usage is through command-line. Clinica supports autocompletion: to see the list of commands, simply type clinica followed by Tab.

In general, a Clinica command-line has the following syntax:

clinica category_of_command command argument options
where the arguments are usually your input/output folders, and where the options look like --flag_1 option_1 --flag_2 option_2.

Please note that the ordering of options on the command-line is not important, whereas arguments must be given in the exact order specified in the documentation (or in the command line helper).

The main arguments

bids_directory and/or caps_directory

Running a pipeline involves most the time these two parameters:

  • bids_directory, which is the input folder containing the dataset in a BIDS hierarchy;
  • caps_directory, which is the output folder containing the expected results in a CAPS hierarchy. It can be also the input folder containing the dataset in a CAPS hierarchy.


You will see the group_id flag 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 ID label could be used when creating 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 ID used to identify the pipeline output obtained from this group. You might also use CNvsAD, for instance, as group ID for a statistical group comparison between patients with Alzheimer's disease (AD) and cognitively normal (CN) subjects.

-tsv / --subjects_sessions_tsv

The -tsv flag allows you to specify in a TSV file the participants belonging to your subset. For instance, running the FreeSurfer pipeline on T1w MRI can be done using :

clinica run t1-freesurfer-cross-sectional path/to/my/bids/dataset path/where/results/will/be/stored -tsv my_list_of_subjects.tsv
where your TSV file looks like as follows:
participant_id  session_id
sub-CLNC0001    ses-M00
sub-CLNC0001    ses-M18
sub-CLNC0001    ses-M36
sub-CLNC0002    ses-M00
sub-CLNC0002    ses-M18
sub-CLNC0002    ses-M36
sub-CLNC0003    ses-M00
Note that to make the display clearer, the rows contain successive tabs, which should not happen in an actual TSV file.

-wd / --working_directory

In every pipeline, a working directory can be specified. This directory gathers all the inputs and outputs of the different steps of the pipeline. It is then very useful for the debugging process. It is specially useful in the case where your pipeline execution crashes and you relaunch it with the exact same parameters, allowing you to continue from the last successfully executed node. If you do not specify any working directory, a temporary one will be created, then deleted at the end if everything went well. For the pipelines that generate many files, such as t1-freesurfer-* (especially if you run it on multiple subjects), a specific drive/partition with enough space can be used to store the working directory

-np / --n_procs

The --n_procs flag allows you to exploit several cores of your machine in order to run pipelines in parallel, which is very useful when dealing with numerous subjects and multiple sessions. Thanks to Nipype, even for a single subject, a pipeline can be run in parallel by exploiting the cores available to process simultaneously independent sub-parts.

Categories of command line

The command-line clinica has been divided into four main categories.

clinica run

This category allows the user to run the different pipelines using the following syntax:

clinica run modality-pipeline bids_directory caps_directory -tsv my_participants.tsv
"modality" is a prefix that corresponds to the data modality (e.g. T1, DWI, fMRI, PET) or to the category of processing (machine learning, statistics...). If you run clinica run --help, you can see the list of modality-pipeline available: they correspond to the different pipelines displayed on the main page of the documentation.

clinica convert

These tools allow you to convert unorganized datasets from publicly available neuroimaging studies into a BIDS hierarchy. Clinica currently includes converters for ADNI, AIBL and OASIS. See here for more details.

clinica iotools

iotools is a set of tools that allows the user to handle BIDS and CAPS datasets, including generating lists of subjects or merging all tabular data into a single TSV file for analysis with external statistical software packages. See here for more details.

clinica generate (for developers)

This category allows developers to generate the skeleton for a new pipeline. The syntax is:

clinica generate template "Modality My Pipeline" -d output_folder

Known issues ⚠️

Matlab and SPM (whose implementation is based on Matlab) can sometimes randomly crash, causing a rather unreadable error in the console. Those events are unpredictable. In case it occurs to you, please do the following: - Check that you have a valid Matlab license - Before relaunching the command line, be sure to remove the content of the working directory (if you specified one)