t1-freesurfer-longitudinal
– FreeSurfer-based longitudinal processing of T1-weighted MR images¶
This pipeline processes a series of images acquired at different time points for the same subject with the longitudinal FreeSurfer stream [Reuter et al., 2012] to increase the accuracy of volume and thickness estimates. It does so in a single command consisting of two consecutive steps:
-
Template creation This corresponds to the FreeSurfer
recon-all -base
command. It is executed on the subject to produce an unbiased template image using robust and inverse consistent registration [Reuter et al., 2010]. -
Longitudinal correction This template is then used as an initialization to a sequence of processing steps triggered by the command FreeSurfer
recon-all -long
to perform segmentation, extract surfaces and derive measurements at each time point.
Prerequisites¶
The pipeline requires a prior run of the cross-sectional t1-freesurfer
pipeline.
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-longitudinal [OPTIONS] CAPS_DIRECTORY
where:
CAPS_DIRECTORY
is the input/output folder containing the results in a CAPS hierarchy.
with specific options :
-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 6-8 hours (creation of the unbiased template) + 2-5 hours per corresponding session. The code execution speed depends on your CPU and the quality of your input T1 volumes. Please be aware that even though the pipeline runs in parallel, processing many subjects and sessions (e.g. ADNI dataset) is time consuming.
Known issues with FreeSurfer and paths length¶
Case when longitudinal correction is performed on macOS
If your run the t1-freesurfer-longitudinal
pipeline on macOS, you will see warning messages when longitudinal correction is performed e.g.:
[19:29:11] Needs to create a $SUBJECTS_DIR folder in /var/folders/m_/j76n37kn4vs6zsj8fq0qcgy0000dn9/T/tmpbrbg9w1n for sub-01 | ses-2011 | long-20112015 (macOS case).
When longitudinal correction is performed on macOS, FreeSurfer (recon-all -long
) may crash if it has to handle a very long path.
The workaround we are currently using is that FreeSurfer will be run in a temporary folder (e.g. /tmp/tmp<hash>
) instead of <path_to_wd>/t1-freesurfer-longitudinal-correction/ReconAll
.
Then, the results will be copied to the working directory before the temporary folder is deleted.
Case where one session is used for a participant
If your CAPS directory contains a participant with one session e.g.:
CAPS_DIRECTORY
└── subjects
├── sub-CLNC01
│ ├── ses-M000
│ │ └── t1
│ │ └── freesurfer_cross_sectional
│ └── ses-M018
│ └── t1
│ └── freesurfer_cross_sectional
└── sub-CLNC02
└── ses-M000
└── t1
└── freesurfer_cross_sectional
You will see this type of message when running Clinica:
$ clinica run t1-freesurfer-template CAPS -np 2 -wd <path_to_wd>
The pipeline will be run on the following 2 participant(s):
sub-CLNC01 | ses-M018, ses-M000 | long-M000M018
sub-CLNC02 | ses-M000 | long-M000
List available in <path_to_wd>/t1-freesurfer-template/participants.tsv
The pipeline will last approximately 10 hours per participant.
[13:33:43] sub-CLNC02 | long-M000 has only one time point. Needs to create a $SUBJECTS_DIR folder in /tmp/tmpe7ztq9hq
[13:33:43] Running pipeline for sub-CLNC01 | long-M000M018
[13:33:43] Running pipeline for sub-CLNC02 | long-M000
[19:51:18] sub-CLNC01 | long-M000M018 has completed
[20:15:04] Segmentation of sub-CLNC02 | long-M000 has moved to working directory and $SUBJECTS_DIR folder (/tmp/tmpe7ztq9hq) was deleted
[20:15:05] sub-CLNC02 | long-M000 has completed
[20:15:09] The t1-freesurfer-template pipeline has completed. You can now delete the working directory (<path_to_wd>/t1-freesurfer-template).
When one session is used for template creation, FreeSurfer (recon-all -base
) may crash if it has to handle a very long path.
The workaround we are currently using is that when one time point is detected for a given participant, FreeSurfer will be run in a temporary folder (e.g. /tmp/tmp<hash>
) instead of <path_to_wd>/t1-freesurfer-template/ReconAll
.
Then, the results will be copied to the working directory before the temporary folder is deleted.
Known error with FreeSurfer on Linux : buffer overflow
If you are running the t1-freesurfer-longitudinal
pipeline on Linux, it might crash with this error message :
*** buffer overflow detected ***: terminated
Abort (core dumped)
Wed Feb 26 11:43:21 CET 2025
ERROR: vertexvol
mris_convert --volume sub-MIRIAD215_ses-1a. long.sub-MIRIAD215_long-lalb lh /localdrive10TB/users/matthieu.joulot/data/miriad/processings/freesurfer/wd_trt_m/t1-freesurfer-longitud
sub-MIRIAD215_ses-1a_long-1alb/sub-MIRIAD215_ses-1a. long. sub-MIRIAD215_long-lalb/surf/h. volume
Command exited with non-zero status 1
Outputs¶
Template creation¶
Results stored in the following folder of the
CAPS hierarchy:
subjects/<participant_id>/<long_id>/freesurfer_unbiased_template/<participant_id>_<long_id>
.
<long_label>
is an identifier defined by concatenating all the sessions associated with the current <participant_id>
(e.g. if the template for participant sub-CLNC01
is built from sessions M00
, M01
, M05
, then <long_label>
will be M00M01M05
).
See CAPS specifications for full definition and example of <long_id>
.
This folder contains the standard output structure of the recon-all
command (label/
, mri/
, surf/
, etc.) already explained in the t1-freesurfer
pipeline.
Longitudinal correction¶
Results are stored in the following folder of
CAPS hierarchy:
subjects/<participant_id>/<session_id>/t1/<long_id>/freesurfer_longitudinal/<participant_id>_<session_id>.long.<participant_id>_<long_id>
.
Similar to the template creation folder, the longitudinal folder contains the standard output structure of the recon-all
command (label/
, mri/
, surf/
, etc.).
Among the files generated by FreeSurfer, you may be interested in the following outputs:
*/mri/aseg.mgz
: subcortical segmentation volume after correction with the unbiased template*/mri/wm.mgz
: white matter mask after correction with the unbiased template*/mri/brainmask.mgz
: skull-stripped volume after correction with the unbiased template*/surf/{l|r}.white
: white surface between white matter and gray matter after correction with the unbiased template*/surf/{l|r}.pial
: pial surface between gray matter and CSF after correction with the unbiased template
(where *
stands for <participant_id>_<session_id>.long.<participant_id>_<long_id>
)
More details regarding the recon-all
output files can be found on the FreeSurfer website.
Note
The full list of features extracted from the FreeSurfer pipeline can be found in the 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-longitudinal
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 builds a subject-dependent template space and
extracts volume and thickness estimates in this space at different points in time.
Example of paragraph (long version):
These results have been obtained using the t1-freesurfer-longitudinal
pipeline of Clinica
Routier et al., 2021.
This pipeline is a wrapper of different tools of the FreeSurfer software
[Fischl et al., 2012],
which is documented and freely available for download online (http://surfer.nmr.mgh.harvard.edu/).
The technical details of the procedures concerned with longitudinal analysis are described in prior publications
[Reuter et al., 2010;
Reuter et al., M00;
Reuter et al., 2012].
The pipeline processes a series of images acquired at different time points for the same subject.
It first produces an unbiased (with respect to any time point) template volume, and then, for each time point, uses the template as an initialisation (tailored to the subject) for the FreeSurfer cortical reconstruction process.
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.
Advanced usage¶
The two main processing steps of the t1-freesurfer-longitudinal
pipeline can be performed individually:
-
Template creation
clinica run t1-freesurfer-template [OPTIONS] CAPS_DIRECTORY
-
Longitudinal correction
clinica run t1-freesurfer-longitudinal-correction CAPS_DIRECTORY
Contact us !¶
- Check for past answers on Clinica Google Group
- Start a discussion on GitHub
- Report an issue on Github