Interacting with ClinicaLink

Preparing your dataLink

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 is 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 command-line interfaceLink

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. The table below summarizes the different sections available in clinica:

Type of command Description Examples of command
iotools Tools for preparing your dataset merge-tsv, create-subjects-visits
run Allows you to run different pipelines t1-freesurfer, pet-preprocessing, t1-spm-segment
convert Used to convert dataset convert-adni-to-bids, convert-aibl-to-bids, convert-oasis-to-bids

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 argumentsLink

bids_directory & caps_directoryLink

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.

tsvLink

A fairly common option is the ability to use a TSV file using the flag -tsv. With this file, you can process your data only on a subset of your subjects (see below for more information). For instance, running the FreeSurfer pipeline on T1 MRI can be done using :

clinica run t1-freesurfer path/to/my/bids/dataset path/where/results/will/be/stored -tsv my_list_of_subjects.tsv

group_idLink

There is one flag that you will meet when working on any group-wise analysis (e.g. template creation from a list of subjects, statistical analysis): the group_id parameter. 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 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_idused to identify the pipeline output obtained from this group. You might also use ‘CNvsAD’, for instance, as group_id for a statistical group comparison.

wdLink

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

Categories of command lineLink

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

clinica runLink

This category allows the user to run the different pipelines. Most of the time, it looks like this:

clinica run modality-pipeline bids_directory caps_directory subjects_sessions_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 iotoolsLink

iotools is a set of tools that allows the user to handle his dataset before using them in a pipeline.

Conversion of publicly available neuroimaging datasets to BIDSLink

Clinica includes converters for public datasets such as ADNI, AIBL and OASIS. See here for more details.

Data handling toolsLink

These tools provide easy interaction mechanisms with BIDS and CAPS compliant datasets, including generating subjects list or merging all tabular data into a single tsv for analysis with external statistical software. See here for more details.

Using Clinica pipelines in pythonLink

If you want to use Clinica directly in your python script, it is possible : you need to use autocompletion in order to help you, but it can be summed up as follows. To make things more clear, everything in bold depends on which pipeline is used. Everything else should not change across pipelines.

from clinica.pipeline.example.example_pipeline import example
mypipeline = example(bids_directory='/path/to/BIDS',
                     caps_directory='/path/to/CAPS',
                     tsv_file='/path/to/tsv')
mypipeline.parameters = { 
        'param1': value1,
        'param2': value2
}
mypipeline.run()

or mypipeline.run(plugin='MultiProc', plugin_args={'n_procs': number_of_process_in_parallel})