Usage
Execution and the BIDS format
The sMRIPrep workflow takes as principal input the path of the dataset that is to be processed. The input dataset is required to be in valid BIDS format, and it must include at least one T1w structural image and (unless disabled with a flag) a BOLD series. We highly recommend that you validate your dataset with the free, online BIDS Validator.
The exact command to run sMRIPrep depends on the Installation method. The common parts of the command follow the BIDS-Apps definition. Example:
smriprep data/bids_root/ out/ participant -w work/
Command-Line Arguments
sMRIPrep: Structural MRI PREProcessing workflows
usage: smriprep [-h] [--version]
[--participant-label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]]
[-d [PATH ...]] [--bids-filter-file PATH] [--nprocs NPROCS]
[--omp-nthreads OMP_NTHREADS] [--mem-gb MEM_GB] [--low-mem]
[--use-plugin USE_PLUGIN] [--boilerplate] [-v]
[--output-spaces [OUTPUT_SPACES ...]] [--longitudinal]
[--skull-strip-template SKULL_STRIP_TEMPLATE]
[--skull-strip-fixed-seed]
[--skull-strip-mode {auto,skip,force}]
[--fs-license-file PATH] [--fs-subjects-dir PATH]
[--fs-no-resume] [--cifti-output [{91k,170k}]]
[--no-submm-recon] [--no-msm] [--fs-no-reconall] [-w WORK_DIR]
[--fast-track] [--resource-monitor] [--reports-only]
[--run-uuid RUN_UUID] [--write-graph] [--stop-on-first-crash]
[--notrack] [--sloppy]
bids_dir output_dir {participant}
Positional Arguments
- bids_dir
the root folder of a BIDS valid dataset (sub-XXXXX folders should be found at the top level in this folder).
- output_dir
the output path for the outcomes of preprocessing and visual reports
- analysis_level
Possible choices: participant
processing stage to be run, only “participant” in the case of sMRIPrep (see BIDS-Apps specification).
Named Arguments
- --version
show program’s version number and exit
Options for filtering BIDS queries
- --participant-label, --participant_label
a space delimited list of participant identifiers or a single identifier (the sub- prefix can be removed)
- -d, --derivatives
Search PATH(s) for pre-computed derivatives.
- --bids-filter-file
a JSON file describing custom BIDS input filters using pybids {<suffix>:{<entity>:<filter>,…},…} (https://github.com/bids-standard/pybids/blob/master/bids/layout/config/bids.json)
Options to handle performance
- --nprocs, --ncpus, --nthreads, --n_cpus, -n-cpus
number of CPUs to be used.
- --omp-nthreads
maximum number of threads per-process
- --mem-gb, --mem_gb
upper bound memory limit for sMRIPrep processes (in GB).
- --low-mem
attempt to reduce memory usage (will increase disk usage in working directory)
- --use-plugin
nipype plugin configuration file
- --boilerplate
generate boilerplate only
- -v, --verbose
increases log verbosity for each occurrence, debug level is -vvv
Workflow configuration
- --output-spaces
paths or keywords prescribing output spaces - standard spaces will be extracted for spatial normalization.
- --longitudinal
treat dataset as longitudinal - may increase runtime
Specific options for ANTs registrations
- --skull-strip-template
select a template for skull-stripping with antsBrainExtraction
- --skull-strip-fixed-seed
do not use a random seed for skull-stripping - will ensure run-to-run replicability when used with –omp-nthreads 1
- --skull-strip-mode
Possible choices: auto, skip, force
determiner for T1-weighted skull stripping (force ensures skull stripping, skip ignores skull stripping, and auto automatically ignores skull stripping if pre-stripped brains are detected).
Specific options for FreeSurfer preprocessing
- --fs-license-file
Path to FreeSurfer license key file. Get it (for free) by registering at https://surfer.nmr.mgh.harvard.edu/registration.html
- --fs-subjects-dir
Path to existing FreeSurfer subjects directory to reuse. (default: OUTPUT_DIR/freesurfer)
- --fs-no-resume
EXPERT: Import pre-computed FreeSurfer reconstruction without resuming. The user is responsible for ensuring that all necessary files are present.
- --cifti-output
Possible choices: 91k, 170k
Output morphometry as CIFTI dense scalars. Optionally, the number of grayordinate can be specified (default is 91k, which equates to 2mm resolution)
Surface preprocessing options
- --no-submm-recon
disable sub-millimeter (hires) reconstruction
- --no-msm
Disable Multimodal Surface Matching surface registration.
- --fs-no-reconall
disable FreeSurfer surface preprocessing.
Other options
- -w, --work-dir
path where intermediate results should be stored
- --fast-track
fast-track the workflow by searching for existing derivatives. (DEPRECATED for –derivatives).
- --resource-monitor
enable Nipype’s resource monitoring to keep track of memory and CPU usage
- --reports-only
only generate reports, don’t run workflows. This will only rerun report aggregation, not reportlet generation for specific nodes.
- --run-uuid
Specify UUID of previous run, to include error logs in report. No effect without –reports-only.
- --write-graph
Write workflow graph.
- --stop-on-first-crash
Force stopping on first crash, even if a work directory was specified.
- --notrack
Opt-out of sending tracking information of this run to the sMRIPrep developers. This information helps to improve sMRIPrep and provides an indicator of real world usage crucial for obtaining funding.
- --sloppy
Use low-quality tools for speed - TESTING ONLY
The command-line interface of the docker wrapper
The sMRIPrep on Docker wrapper.
This is a lightweight Python wrapper to run sMRIPrep. Docker must be installed and running. This can be checked running
docker info
Please report any feedback to our GitHub repository (https://github.com/nipreps/smriprep) and do not forget to credit all the authors of software that sMRIPrep uses (consider using the citation boilerplate included in the individual reports).
usage: smriprep-docker [-h] [--version] [-i IMG] [-w WORK_DIR]
[-d PATH [PATH ...]] [--fs-license-file PATH]
[--fs-subjects-dir PATH] [--use-plugin PATH]
[--patch PACKAGE=PATH [PACKAGE=PATH ...]] [--shell]
[--config PATH] [-e ENV_VAR value] [-u USER] [--no-tty]
[bids_dir] [output_dir] [{participant}]
Positional Arguments
- bids_dir
- output_dir
- analysis_level
Possible choices: participant
Named Arguments
- -h, --help
show this help message and exit
- --version
show program’s version number and exit
- -i, --image
image name
Wrapper options
Standard options that require mapping files into the container
- -w, --work-dir
path where intermediate results should be stored
- -d, --derivatives
Search PATH(s) for pre-computed derivatives.
- --fs-license-file
Path to FreeSurfer license key file. Get it (for free) by registering at https://surfer.nmr.mgh.harvard.edu/registration.html
- --fs-subjects-dir
Path to existing FreeSurfer subjects directory to reuse. (default: OUTPUT_DIR/freesurfer)
- --use-plugin
nipype plugin configuration file
Developer options
Tools for testing and debugging sMRIPrep
- --patch
local repository to use within container
- --shell
open shell in image instead of running sMRIPrep
- --config
Use custom nipype.cfg file
- -e, --env
Set custom environment variable within container
- -u, --user
Run container as a given user/uid
- --no-tty
Run docker without TTY flag -it
The FreeSurfer license
sMRIPrep uses FreeSurfer tools, which require a license to run.
To obtain a FreeSurfer license, simply register for free at https://surfer.nmr.mgh.harvard.edu/registration.html.
When using manually-prepared environments or singularity, FreeSurfer will search
for a license key file first using the $FS_LICENSE
environment variable and then
in the default path to the license key file ($FREESURFER_HOME/license.txt
).
If using the --cleanenv
flag and $FS_LICENSE
is set, use --fs-license-file $FS_LICENSE
to pass the license file location to sMRIPrep.
It is possible to run the docker container pointing the image to a local path
where a valid license file is stored.
For example, if the license is stored in the $HOME/.licenses/freesurfer/license.txt
file on the host system:
$ docker run -ti --rm \
-v $HOME/fullds005:/data:ro \
-v $HOME/dockerout:/out \
-v $HOME/.licenses/freesurfer/license.txt:/opt/freesurfer/license.txt \
nipreps/smriprep:latest \
/data /out/out \
participant \
--ignore fieldmaps
Using FreeSurfer can also be enabled when using smriprep-docker
:
$ smriprep-docker --fs-license-file $HOME/.licenses/freesurfer/license.txt \
/path/to/data/dir /path/to/output/dir participant
RUNNING: docker run --rm -it -v /path/to/data/dir:/data:ro \
-v /home/user/.licenses/freesurfer/license.txt:/opt/freesurfer/license.txt \
-v /path/to_output/dir:/out nipreps/smriprep:1.0.0 \
/data /out participant
...
If the environment variable $FS_LICENSE
is set in the host system, then
it will automatically used by smriprep-docker
. For instance, the following
would be equivalent to the latest example:
$ export FS_LICENSE=$HOME/.licenses/freesurfer/license.txt
$ smriprep-docker /path/to/data/dir /path/to/output/dir participant
RUNNING: docker run --rm -it -v /path/to/data/dir:/data:ro \
-v /home/user/.licenses/freesurfer/license.txt:/opt/freesurfer/license.txt \
-v /path/to_output/dir:/out nipreps/smriprep:1.0.0 \
/data /out participant
...