t1-freesurfer
– FreeSurfer-based processing of T1-weighted MR images¶
This pipeline performs cortical surface extraction, segmentation of subcortical structures [Dale et al., 1999], cortical thickness estimation [Fischl and Dale, 2000], spatial normalization onto the FreeSurfer surface template (FsAverage) [Fischl et al., 1999a], and parcellation of cortical regions based on different atlases [Fischl et al., 2004], using the FreeSurfer recon-all
command.
Additionally, from the FreeSurfer outputs, we generate TSV files containing a summary of the regional statistics (e.g. regional volume, mean cortical thickness) to ease subsequent statistical analysis.
Dependencies¶
If you only installed the core of Clinica, this pipeline needs the installation of FreeSurfer 6.0 on your computer.
Running the pipeline¶
The pipeline can be run with the following command line:
clinica run t1-freesurfer [OPTIONS] BIDS_DIRECTORY CAPS_DIRECTORY
where:
BIDS_DIRECTORY
is the input folder containing the dataset in a BIDS hierarchyCAPS_DIRECTORY
is the output folder containing the results in a CAPS hierarchy
with specific options :
-raa/--recon_all_args
: For people familiar with FreeSurfer, we compute the normalized data on the FreeSurfer atlas (FsAverage) with the-qcache
option fromrecon-all
. If you want to add some custom flags, you can do it in Clinica with this option. For example :--recon_all_args="-bigventricles -qcache"
. Please note that=
is compulsory.-ap
/--atlas_path
: In case you wish to use another atlas, specify its folder path with this option. Your atlas will need to be in FreeSurfergcs
format (e.ghemisphere.atlasname_6p0.gcs
). The results will be stored in the same folder as the original results with additional files inlabels
,stats
andregional measures
.-overwrite
/--overwrite_outputs
: Force the overwrite of output files in the CAPS folder with this option.
Optional parameters common to all pipelines
-tsv
/--subjects_sessions_tsv
This 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 BIDS_PATH OUTPUT_PATH -tsv my_subjects.tsv
participant_id session_id
sub-CLNC0001 ses-M000
sub-CLNC0001 ses-M018
sub-CLNC0002 ses-M000
Creating the TSV
To make the display clearer the rows here contain successive tabs but that should not happen in an actual TSV.
-wd
/--working_directory
By default when running a pipeline, a temporary working directory is created. This directory stores all the intermediary inputs and outputs of the different steps of the pipeline. If everything goes well, the output directory is eventually created and the working directory is deleted.
With this option, a working directory of your choice can be specified. It is very useful for the debugging process or if your pipeline crashes. Then, you can relaunch it with the exact same parameters which will allow you to continue from the last successfully executed node.
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
This 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. We recommend using your_number_of_cpu - 1
for costly pipelines such as pet-surface-longitudinal
.
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.
-cn
/--caps-name
Use this option if you want to specify the name of the CAPS dataset that will be used inside the dataset_description.json
file, at the root of the CAPS folder (see CAPS Specifications for more details). This works if this CAPS dataset does not exist yet, otherwise the existing name will be kept.
Computational time
The computational time for one subject is around 10–15 hours depending on your CPU and the quality of your input T1. Please be aware that even though the pipeline runs in parallel, processing many subjects (e.g. ADNI dataset) is time consuming.
Centering BIDS nifti
If the images from the BIDS_DIRECTORY
are not centered, Clinica will give a warning because this can be an issue if later processing steps involve SPM (for instance if you are planning to run pet-surface afterwards).
The warning message will contain a suggestion of a command to be run on your BIDS_DIRECTORY
in order to generate a new BIDS dataset with images centered. This relies on the IOTool center-nifti.
It is highly recommended to follow this recommendation but Clinica won't force you to do so.
Outputs¶
Results are stored in the following folder of the CAPS hierarchy: subjects/<participant_id>/<session_id>/t1/freesurfer_cross_sectional
.
This folder contains the standard output structure of the recon-all
command, i.e. folders such as label/
, mri/
, surf/
, etc.
Among the files generated by FreeSurfer, you may be interested in the following outputs:
*/mri/aseg.mgz
: subcortical segmentation volume*/mri/wm.mgz
: white matter mask*/mri/brainmask.mgz
: skull-stripped volume*/surf/{l|r}h.white
: white surface between white matter and gray matter*/surf/{l|r}h.pial
: pial surface between gray matter and CSF (where*
stands for<participant_id>_<session_id>
)
More details regarding the recon-all
output files can be found on the FreeSurfer website.

t1-freesurfer
outputs.
TSV files summarizing the regional statistics are also created for each subject.
Note
The full list of features extracted from the FreeSurfer pipeline can be found in The ClinicA Processed Structure (CAPS) specifications.
Describing this pipeline in your paper¶
Example of paragraph (short version):
These results have been obtained using the t1-freesurfer
pipeline of Clinica [Routier et al., 2021].
This pipeline is a wrapper of different tools of the FreeSurfer software (http://surfer.nmr.mgh.harvard.edu/) [Fischl et al., 2012].
This processing includes segmentation of subcortical structures, extraction of cortical surfaces, cortical thickness estimation, spatial normalization onto the FreeSurfer surface template (FsAverage), and parcellation of cortical regions.
Example of paragraph (long version):
These results have been obtained using the t1-freesurfer
pipeline of Clinica
[Routier et al., 2021].
This pipeline is a wrapper of different tools of the FreeSurfer software, which is documented and freely available for download online (http://surfer.nmr.mgh.harvard.edu/).
The technical details of these procedures are described in prior publications
[Dale et al., 1999;
Dale and Sereno, 1993;
Fischl and Dale, 2000;
Fischl et al., 2001;
Fischl et al., 2002;
Fischl et al., 2004a;
Fischl et al., 1999a;
Fischl et al., 1999b;
Fischl et al., 2004b;
Han et al., 2006;
Jovicich et al., 2006;
Segonne et al., 2004;
Reuter and Fischl, 2010;
Reuter et al., 2012].
Briefly, this processing includes removal of non-brain tissue using a hybrid watershed/surface deformation procedure [Segonne et al., 2004], automated Talairach transformation, segmentation of the subcortical white matter and
deep gray matter volumetric structures (including hippocampus, amygdala, caudate, putamen, thalamus, ventricles) [Fischl et al., 2002;
Fischl et al., 2004a], intensity normalization [Sled et al., 1998], tessellation of the gray matter/white matter boundary, automated topology correction [Fischl et al., 2001;
Segonne et al., 2007], and
surface deformation following intensity gradients to optimally place the gray/white and
gray/cerebrospinal fluid borders at the location where the greatest shift in intensity defines the transition to the other tissue class
[Dale et al., 1999;
Dale and Sereno, 1993;
Fischl and Dale, 2000], surface inflation [Fischl et al., 1999a], registration to a spherical atlas which is based on individual cortical folding patterns to match cortical geometry across subjects [Fischl et al., 1999b], parcellation of the cerebral cortex into units with respect to gyral and sulcal structures [Desikan et al., 2006;
Fischl et al., 2004b], computation of maps of cortical thickness, calculated as the closest distance from the gray/white boundary to the gray/CSF boundary at each vertex on the tessellated surface [Fischl and Dale, 2000] and creation of a variety of surface based data including maps of curvature and sulcal depth.
Procedures for the measurement of cortical thickness have been validated against histological analysis [Rosas et al., 2002] and manual measurements [Kuperberg et al., 2003;
Salat et al., 2004].
FreeSurfer morphometric procedures have been demonstrated to show good test-retest reliability across scanner manufacturers and across field strengths
[Han et al., 2006;
Reuter et al., 2012].
Tip
Easily access the papers cited on this page on Zotero.
Support¶
- You can use the Clinica Google Group to ask for help!
- Report an issue on GitHub.
Appendix: Main steps of the t1-freesurfer
pipeline¶
Following the links to visualize diagrams summarizing the main steps of the t1-freesurfer
pipeline: pre-processing, voxel-based processing, surface-based processing.
For a detailed explanation of the FreeSurfer recon-all
pipeline, click here.
Contact us !¶
- Check for past answers on Clinica Google Group
- Start a discussion on GitHub
- Report an issue on Github