Forked from bids-apps/freesurfer then modified for FreeSurfer 7.1.1 by Neil Oxtoby and Damiano Archetti on behalf of E-DADS as part of E_DADS tools.
To get the corresponding docker container: docker pull noxtoby/edads:freesurfer7p1p1
This app implements the recon-all pipeline of Freesurfer for each subject individually and creates a study specific template. In case there are multiple sessions the Freesurfer longitudinal pipeline is used (creating subject specific templates) unless instructed to combine data across sessions.
Freesurfer version: freesurfer-linux-centos8_x86_64-7.1.1.tar.gz
The output of the pipeline consist of the SUBJECTS_DIR created during the analysis.
https://surfer.nmr.mgh.harvard.edu/fswiki/FreeSurferSupport
https://surfer.nmr.mgh.harvard.edu/fswiki/FreeSurferMethodsCitation
This App has the following command line arguments:
$ docker run -ti --rm E-DADS/freesurfer --help
usage: run.py [-h]
[--participant_label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]]
[--session_label SESSION_LABEL [SESSION_LABEL ...]]
[--n_cpus N_CPUS]
[--stages {autorecon1,autorecon2,autorecon2-cp,autorecon2-wm,autorecon-pial,autorecon3,autorecon-all,all}
[{autorecon1,autorecon2,autorecon2-cp,autorecon2-wm,autorecon-pial,autorecon3,autorecon-all,all} ...]]
[--steps {cross-sectional,template,longitudinal}
[{cross-sectional,template,longitudinal} ...]]
[--template_name TEMPLATE_NAME] --license_file LICENSE_FILE
[--acquisition_label ACQUISITION_LABEL]
[--refine_pial_acquisition_label REFINE_PIAL_ACQUISITION_LABEL]
[--multiple_sessions {longitudinal,multiday}]
[--refine_pial {T2,FLAIR,None,T1only}]
[--hires_mode {auto,enable,disable}]
[--parcellations {aparc,aparc.a2009s} [{aparc,aparc.a2009s} ...]]
[--measurements {area,volume,thickness,thicknessstd,meancurv,gauscurv,foldind,curvind}
[{area,volume,thickness,thicknessstd,meancurv,gauscurv,foldind,curvind} ...]]
[-v] [--bids_validator_config BIDS_VALIDATOR_CONFIG]
[--skip_bids_validator] [--3T {true,false}] [--cw256 {false,true}]
bids_dir output_dir {participant,group1,group2}
FreeSurfer recon-all + custom template generation.
positional arguments:
bids_dir The directory with the input dataset formatted
according to the BIDS standard.
output_dir The directory where the output files should be stored.
If you are running group level analysis this folder
should be prepopulated with the results of
theparticipant level analysis.
{participant,group1,group2}
Level of the analysis that will be performed. Multiple
participant level analyses can be run independently
(in parallel) using the same output_dir. "group1"
creates study specific group template. "group2"
exports group stats tables for cortical parcellation,
subcortical segmentation a table with euler numbers.
optional arguments:
-h, --help show this help message and exit
--participant_label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]
The label of the participant that should be analyzed.
The label corresponds to sub-<participant_label> from
the BIDS spec (so it does not include "sub-"). If this
parameter is not provided all subjects should be
analyzed. Multiple participants can be specified with
a space separated list.
--session_label SESSION_LABEL [SESSION_LABEL ...]
The label of the session that should be analyzed. The
label corresponds to ses-<session_label> from the BIDS
spec (so it does not include "ses-"). If this
parameter is not provided all sessions should be
analyzed. Multiple sessions can be specified with a
space separated list.
--n_cpus N_CPUS Number of CPUs/cores available to use.
--stages {autorecon1,autorecon2,autorecon2-cp,autorecon2-wm,autorecon-pial,autorecon3,autorecon-all,all}
[{autorecon1,autorecon2,autorecon2-cp,autorecon2-wm,autorecon-pial,autorecon3,autorecon-all,all} ...]
Autorecon stages to run.
--steps {cross-sectional,template,longitudinal} [{cross-sectional,template,longitudinal} ...]
Longitudinal pipeline steps to run.
--template_name TEMPLATE_NAME
Name for the custom group level template generated for
this dataset
--license_file LICENSE_FILE
Path to FreeSurfer license key file. To obtain it you
need to register (for free) at
https://surfer.nmr.mgh.harvard.edu/registration.html
--acquisition_label ACQUISITION_LABEL
If the dataset contains multiple T1 weighted images
from different acquisitions which one should be used?
Corresponds to "acq-<acquisition_label>"
--refine_pial_acquisition_label REFINE_PIAL_ACQUISITION_LABEL
If the dataset contains multiple T2 or FLAIR weighted
images from different acquisitions which one should be
used? Corresponds to "acq-<acquisition_label>"
--multiple_sessions {longitudinal,multiday}
For datasets with multiday sessions where you do not
want to use the longitudinal pipeline, i.e., sessions
were back-to-back, set this to multiday, otherwise
sessions with T1w data will be considered independent
sessions for longitudinal analysis.
--refine_pial {T2,FLAIR,None,T1only}
If the dataset contains 3D T2 or T2 FLAIR weighted
images (~1x1x1), these can be used to refine the pial
surface. If you want to ignore these, specify None or
T1only to base surfaces on the T1 alone.
--hires_mode {auto,enable,disable}
Submilimiter (high resolution) processing. 'auto' -
use only if <1.0mm data detected, 'enable' - force on,
'disable' - force off
--parcellations {aparc,aparc.a2009s} [{aparc,aparc.a2009s} ...]
Group2 option: cortical parcellation(s) to extract
stats from.
--measurements {area,volume,thickness,thicknessstd,meancurv,gauscurv,foldind,curvind}
[{area,volume,thickness,thicknessstd,meancurv,gauscurv,foldind,curvind} ...]
Group2 option: cortical measurements to extract stats
for.
-v, --version show program's version number and exit
--bids_validator_config BIDS_VALIDATOR_CONFIG
JSON file specifying configuration of bids-validator:
See https://github.com/INCF/bids-validator for more info
--skip_bids_validator skips bids validation
--3T {true,false} enables the two 3T specific options that recon-all
supports: nu intensity correction params, and the
special schwartz atlas
--cw256 {false,true}
if set to true, mri_convert conforms images with a
FOV > 256 to dimensions of 256^3
To run it in participant level mode (for one participant):
docker run -ti --rm \
-v /Users/filo/data/ds005:/bids_dataset:ro \
-v /Users/filo/outputs:/outputs \
-v /Users/filo/freesurfer_license.txt:/license.txt \
E-DADS/freesurfer \
/bids_dataset /outputs participant --participant_label 01 \
--license_file "/license.txt"
After doing this for all subjects (potentially in parallel) the group level analyses can be run.
To create a study specific template run:
docker run -ti --rm \
-v /Users/filo/data/ds005:/bids_dataset:ro \
-v /Users/filo/outputs:/outputs \
-v /Users/filo/freesurfer_license.txt:/license.txt \
E-DADS/freesurfer \
/bids_dataset /outputs group1 \
--license_file "/license.txt"
To export tables with aggregated measurements within regions of cortical parcellation and subcortical segementation, and a table with euler numbers (a quality metric, see Rosen et. al, 2017), run:
docker run -ti --rm \
-v /Users/filo/data/ds005:/bids_dataset:ro \
-v /Users/filo/outputs:/outputs \
-v /Users/filo/freesurfer_license.txt:/license.txt \
E-DADS/freesurfer \
/bids_dataset /outputs group2 \
--license_file "/license.txt"
Also see the --parcellations and --measurements arguments.
This step writes ouput into <output_dir>/00_group2_stats_tables/. E.g.:
lh.aparc.thickness.tsvcontains cortical thickness values for the left hemisphere extracted via the aparac parcellation.aseg.tsvcontains subcortical information from the aseg segmentation.euler.tsvcontains the euler numbers