Interacting with Clinica¶
Preparing your data¶
Clinica pipelines require to have your data organized in the BIDS format. 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 it :
- If your data are in DICOM format, you can use one of the converters referenced on the BIDS website.
- Otherwise, Clinica includes converters for public datasets :
Clinica available converters
adni-to-bids
- ADNI: Alzheimer’s Disease Neuroimaging Initiativeaibl-to-bids
- AIBL: Australian Imaging, Biomarker & Lifestyle Flagship Study of Ageinggenfi-to-bids
- GENFI:Genetic Frontotemporal dementia Initiativehabs-to-bids
- HABS: Harvard Aging Brain Studyixi-to-bids
- IXI: Information eXtraction from Imagesnifd-to-bids
- NIFD: Neuroimaging in Frontotemporal Dementiaoasis-to-bids
- OASIS: Open Access Series of Imaging Studiesoasis3-to-bids
- OASIS-3: Longitudinal Neuroimaging, Clinical, and Cognitive Dataset for Normal Aging and Alzheimer’s Diseaseukb-to-bids
- UK Biobank: Large-scale biomedical database and research resource in the United Kingdom
Clinica and cross-sectional BIDS datasets
If you run Clinica with a dataset containing no timepoints e.g.:
BIDS
└── sub-CLNC0001
├── anat
│ └── sub-CLNC0001_T1w.nii.gz
└── pet
├── sub-CLNC0001_trc-18FFDG_pet.json
└── sub-CLNC0001_trc-18FFDG_pet.nii.gz
BIDS
└── sub-CLNC0001
└── ses-M000
├── anat
│ └── sub-CLNC0001_ses-M000_T1w.nii.gz
└── pet
├── sub-CLNC0001_ses-M000_trc-18FFDG_pet.json
└── sub-CLNC0001_ses-M000_trc-18FFDG_pet.nii.gz
Tip
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.
See the list of available commands on your terminal
- Do not hesitate to use
-h
or--help
after any component of the command line, ex :clinica -h
,clinica run -h
... to see what options are available. - Clinica supports autocompletion for zsh shell users : 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
.
Components order
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).
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 image processing and analysis pipelines using the following syntax:
clinica run modality-pipeline bids_directory caps_directory options
"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 execute clinica run --help
, you can see the list of modality-pipeline
available :
Clinica available pipelines
-
Anatomical MRI
t1-linear
- Linear processing of T1w MR images: affine registration to the MNI standard space of T1 imagesflair-linear
- Linear processing of FLAIR images: affine registration to the MNI standard space of FLAIR imagest1-volume
- Processing of T1w MR images using SPM: tissue segmentation and spatial normalizationt1-freesurfer
- Processing of T1w MR images using FreeSurfer: cortical surface, subcortical structures and volumetricst1-freesurfer-longitudinal
- Longitudinal processing of T1w MR images using FreeSurfer: cortical surface, subcortical structures and volumetrics
-
Diffusion MRI (DWI)
dwi-preprocessing-*
- DWI pre-processing: correction of head motion, magnetic susceptibility, eddy current and bias field induced distortionsdwi-dti
- DTI scalar maps (FA, MD, AD, RD) and spatial normalization: extraction of DTI-based measures (FA, MD, AD, RD)dwi-connectome
- Construction of structural connectome: computation of fiber orientation distributions, tractogram and connectome
-
PET
- Introduction to concepts used in the PET pipelines: partial volume correction and standardized uptake value ratio (SUVR) map computation
pet-linear
- Linear processing of PET images: affine registration to the MNI standard space and intensity normalizationpet-volume
- Volume-based processing of PET images: registration to T1w MRI, intensity normalization, partial volume correction and spatial normalizationpet-surface
- Surface-based processing of PET images: projection of the PET signal onto the subject’s cortical surfacepet-surface-longitudinal
- Surface-based longitudinal processing of PET images: projection of the PET signal onto the subject’s cortical surface
-
Statistics
statistics-surface
- Surface-based mass-univariate analysis with SurfStatstatistics-volume
- Volume-based mass-univariate analysis with SPM
-
Machine Learning
machinelearning-prepare-spatial-svm
- Prepare input data for spatially regularized SVMmachinelearning-classification
- Classification based on machine learning
-
Deep learning
- You can use the ClinicaDL framework for the reproducible processing of neuroimaging data with deep learning methods.
Clinica run logs
Clinica run logs are written in the current working directory by default. A different directory may be specified by setting the CLINICA_LOGGING_DIR
environment variable.
clinica convert
¶
These tools allow you to convert unorganized datasets from publicly available neuroimaging studies into a BIDS hierarchy.
Clinica currently includes some converters for public datasets :
Clinica available converters
adni-to-bids
- ADNI: Alzheimer’s Disease Neuroimaging Initiativeaibl-to-bids
- AIBL: Australian Imaging, Biomarker & Lifestyle Flagship Study of Ageinggenfi-to-bids
- GENFI:Genetic Frontotemporal dementia Initiativehabs-to-bids
- HABS: Harvard Aging Brain Studyixi-to-bids
- IXI: Information eXtraction from Imagesnifd-to-bids
- NIFD: Neuroimaging in Frontotemporal Dementiaoasis-to-bids
- OASIS: Open Access Series of Imaging Studiesoasis3-to-bids
- OASIS-3: Longitudinal Neuroimaging, Clinical, and Cognitive Dataset for Normal Aging and Alzheimer’s Diseaseukb-to-bids
- UK Biobank: Large-scale biomedical database and research resource in the United Kingdom
clinica iotools
¶
iotools
is a set of tools that allows the user to handle BIDS and CAPS datasets.
It allows 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
The main arguments¶
BIDS_DIRECTORY
and/or CAPS_DIRECTORY
¶
Running a pipeline involves most of 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.
GROUP_LABEL
¶
You will see the GROUP_LABEL
argument 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.
Common options for pipelines¶
-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 path/to/my/bids/dataset path/where/results/will/be/stored -tsv my_list_of_subjects.tsv
where your TSV file looks as follows:
participant_id session_id
sub-CLNC0001 ses-M000
sub-CLNC0001 ses-M018
sub-CLNC0002 ses-M000
sub-CLNC0002 ses-M018
sub-CLNC0003 ses-M000
Writing the TSV
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.
Working directory
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 dwi-preprocessing
(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 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.
If you do not specify -np
/ --n_procs
flag, Clinica will detect the number of threads to run in parallel and propose the adequate number of threads to the user.
Optional parameters common to all converters¶
-- subjects_list
/- sl
: path to a text file containing a list of specific subjects to extract. The expected format is one subject per line :
001_S_0001
002_S_0002
-- n_procs
/- np
: Number of cores used to run in parallel. (default: (Number of available CPU minus one))
Known issue with Matlab and SPM12¶
Matlab and SPM12 (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).
Contact us !¶
- Check for past answers on Clinica Google Group
- Start a discussion on GitHub
- Report an issue on Github