Usage Notes¶
Warning
As of fMRIPRep 1.0.12, the software includes a tracking system
to report usage statistics and errors. Users can opt-out using
the --notrack
command line argument.
Execution and the BIDS format¶
The fMRIPRep 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 fMRIPRep depends on the Installation method. The common parts of the command follow the BIDS-Apps definition. Example:
fmriprep data/bids_root/ out/ participant -w work/
Command-Line Arguments¶
fMRIPrep: fMRI PREProcessing workflows v20.2.1
usage: fmriprep [-h] [--version] [--skip_bids_validation]
[--participant-label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]]
[-t TASK_ID] [--echo-idx ECHO_IDX] [--bids-filter-file FILE]
[--anat-derivatives PATH] [--bids-database-dir PATH]
[--nprocs NPROCS] [--omp-nthreads OMP_NTHREADS]
[--mem MEMORY_GB] [--low-mem] [--use-plugin FILE]
[--anat-only] [--boilerplate_only] [--md-only-boilerplate]
[--error-on-aroma-warnings] [-v]
[--ignore {fieldmaps,slicetiming,sbref,t2w,flair} [{fieldmaps,slicetiming,sbref,t2w,flair} ...]]
[--longitudinal]
[--output-spaces [OUTPUT_SPACES [OUTPUT_SPACES ...]]]
[--bold2t1w-init {register,header}] [--bold2t1w-dof {6,9,12}]
[--force-bbr] [--force-no-bbr] [--medial-surface-nan]
[--dummy-scans DUMMY_SCANS] [--random-seed _RANDOM_SEED]
[--use-aroma]
[--aroma-melodic-dimensionality AROMA_MELODIC_DIM]
[--return-all-components]
[--fd-spike-threshold REGRESSORS_FD_TH]
[--dvars-spike-threshold REGRESSORS_DVARS_TH]
[--skull-strip-template SKULL_STRIP_TEMPLATE]
[--skull-strip-fixed-seed]
[--skull-strip-t1w {auto,skip,force}] [--fmap-bspline]
[--fmap-no-demean] [--use-syn-sdc] [--force-syn]
[--fs-license-file FILE] [--fs-subjects-dir PATH]
[--no-submm-recon] [--cifti-output [{91k,170k}] |
--fs-no-reconall] [--output-layout {bids,legacy}]
[-w WORK_DIR] [--clean-workdir] [--resource-monitor]
[--reports-only] [--config-file FILE] [--write-graph]
[--stop-on-first-crash] [--notrack]
[--debug {compcor,all} [{compcor,all} ...]] [--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 fMRIPrep (see BIDS-Apps specification).
Named Arguments¶
- --version
show program’s version number and exit
Options for filtering BIDS queries¶
- --skip_bids_validation, --skip-bids-validation
assume the input dataset is BIDS compliant and skip the validation
- --participant-label, --participant_label
a space delimited list of participant identifiers or a single identifier (the sub- prefix can be removed)
- -t, --task-id
select a specific task to be processed
- --echo-idx
select a specific echo to be processed in a multiecho series
- --bids-filter-file
a JSON file describing custom BIDS input filters using PyBIDS. For further details, please check out https://fmriprep.readthedocs.io/en/20.2.1/faq.html#how-do-I-select-only-certain-files-to-be-input-to-fMRIPrep
- --anat-derivatives
Reuse the anatomical derivatives from another fMRIPrep run or calculated with an alternative processing tool (NOT RECOMMENDED).
- --bids-database-dir
Path to an existing PyBIDS database folder, for faster indexing (especially useful for large datasets).
Options to handle performance¶
- --nprocs, --nthreads, --n_cpus, --n-cpus
maximum number of threads across all processes
- --omp-nthreads
maximum number of threads per-process
- --mem, --mem_mb, --mem-mb
upper bound memory limit for fMRIPrep processes
- --low-mem
attempt to reduce memory usage (will increase disk usage in working directory)
- --use-plugin, --nipype-plugin-file
nipype plugin configuration file
- --anat-only
run anatomical workflows only
- --boilerplate_only
generate boilerplate only
- --md-only-boilerplate
skip generation of HTML and LaTeX formatted citation with pandoc
- --error-on-aroma-warnings
Raise an error if ICA_AROMA does not produce sensible output (e.g., if all the components are classified as signal or noise)
- -v, --verbose
increases log verbosity for each occurence, debug level is -vvv
Workflow configuration¶
- --ignore
Possible choices: fieldmaps, slicetiming, sbref, t2w, flair
ignore selected aspects of the input dataset to disable corresponding parts of the workflow (a space delimited list)
- --longitudinal
treat dataset as longitudinal - may increase runtime
- --output-spaces
Standard and non-standard spaces to resample anatomical and functional images to. Standard spaces may be specified by the form
<SPACE>[:cohort-<label>][:res-<resolution>][...]
, where<SPACE>
is a keyword designating a spatial reference, and may be followed by optional, colon-separated parameters. Non-standard spaces imply specific orientations and sampling grids. Important to note, theres-*
modifier does not define the resolution used for the spatial normalization. To generate no BOLD outputs, use this option without specifying any spatial references. For further details, please check out https://fmriprep.readthedocs.io/en/20.2.1/spaces.html- --bold2t1w-init
Possible choices: register, header
Either “register” (the default) to initialize volumes at center or “header” to use the header information when coregistering BOLD to T1w images.
- --bold2t1w-dof
Possible choices: 6, 9, 12
Degrees of freedom when registering BOLD to T1w images. 6 degrees (rotation and translation) are used by default.
- --force-bbr
Always use boundary-based registration (no goodness-of-fit checks)
- --force-no-bbr
Do not use boundary-based registration (no goodness-of-fit checks)
- --medial-surface-nan
Replace medial wall values with NaNs on functional GIFTI files. Only performed for GIFTI files mapped to a freesurfer subject (fsaverage or fsnative).
- --dummy-scans
Number of non steady state volumes.
- --random-seed
Initialize the random seed for the workflow
Specific options for running ICA_AROMA¶
- --use-aroma
add ICA_AROMA to your preprocessing stream
- --aroma-melodic-dimensionality
Exact or maximum number of MELODIC components to estimate (positive = exact, negative = maximum)
Specific options for estimating confounds¶
- --return-all-components
Include all components estimated in CompCor decomposition in the confounds file instead of only the components sufficient to explain 50 percent of BOLD variance in each CompCor mask
- --fd-spike-threshold
Threshold for flagging a frame as an outlier on the basis of framewise displacement
- --dvars-spike-threshold
Threshold for flagging a frame as an outlier on the basis of standardised DVARS
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 and matching –random-seed <int>
- --skull-strip-t1w
Possible choices: auto, skip, force
determiner for T1-weighted skull stripping (‘force’ ensures skull stripping, ‘skip’ ignores skull stripping, and ‘auto’ applies brain extraction based on the outcome of a heuristic to check whether the brain is already masked).
Specific options for handling fieldmaps¶
- --fmap-bspline
fit a B-Spline field using least-squares (experimental)
- --fmap-no-demean
do not remove median (within mask) from fieldmap
Specific options for SyN distortion correction¶
- --use-syn-sdc
EXPERIMENTAL: Use fieldmap-free distortion correction
- --force-syn
EXPERIMENTAL/TEMPORARY: Use SyN correction in addition to fieldmap correction, if available
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)
Surface preprocessing options¶
- --no-submm-recon
disable sub-millimeter (hires) reconstruction
- --cifti-output
Possible choices: 91k, 170k
output preprocessed BOLD as a CIFTI dense timeseries. Optionally, the number of grayordinate can be specified (default is 91k, which equates to 2mm resolution)
- --fs-no-reconall
disable FreeSurfer surface preprocessing.
Other options¶
- --output-layout
Possible choices: bids, legacy
Organization of outputs. legacy (default) creates derivative datasets as subdirectories of outputs. bids places fMRIPrep derivatives directly in the output directory, and defaults to placing FreeSurfer derivatives in <output-dir>/sourcedata/freesurfer.
- -w, --work-dir
path where intermediate results should be stored
- --clean-workdir
Clears working directory of contents. Use of this flag is notrecommended when running concurrent processes of fMRIPrep.
- --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.
- --config-file
Use pre-generated configuration file. Values in file will be overridden by command-line arguments.
- --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 FMRIPREP developers. This information helps to improve FMRIPREP and provides an indicator of real world usage crucial for obtaining funding.
- --debug
Possible choices: compcor, all
Debug mode(s) to enable. ‘all’ is alias for all available modes.
- --sloppy
Use low-quality tools for speed - TESTING ONLY
The command-line interface of the docker wrapper¶
The fMRIPrep on Docker wrapper
This is a lightweight Python wrapper to run fMRIPrep. 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/fmriprep) and do not forget to credit all the authors of software that fMRIPrep uses (https://fmriprep.readthedocs.io/en/latest/citing.html).
usage: fmriprep-docker [-h] [--version] [-i IMG] [-w WORK_DIR]
[--output-spaces [OUTPUT_SPACES [OUTPUT_SPACES ...]]]
[--fs-license-file PATH] [--fs-subjects-dir PATH]
[--config-file PATH] [--anat-derivatives PATH]
[--use-plugin PATH] [--bids-database-dir PATH]
[--patch PACKAGE=PATH [PACKAGE=PATH ...]] [--shell]
[--config PATH] [-e ENV_VAR value] [-u USER]
[--network NETWORK] [--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
- --output-spaces
Standard and non-standard spaces to resample anatomical and functional images to. Standard spaces may be specified by the form
<TEMPLATE>[:res-<resolution>][:cohort-<label>][...]
, where<TEMPLATE>
is a keyword (valid keywords: “MNI152Lin”, “MNI152NLin2009cAsym”, “MNI152NLin6Asym”, “MNI152NLin6Sym”, “MNIInfant”, “MNIPediatricAsym”, “NKI”, “OASIS30ANTs”, “PNC”, “UNCInfant”, “fsLR”, “fsaverage”, “fsaverage5”, “fsaverage6”) or path pointing to a user-supplied template, and may be followed by optional, colon-separated parameters. Non-standard spaces (valid keywords: anat, T1w, run, func, sbref, fsnative) imply specific orientations and sampling grids. Important to note, theres-*
modifier does not define the resolution used for the spatial normalization.- --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)
- --config-file
Use pre-generated configuration file. Values in file will be overridden by command-line arguments.
- --anat-derivatives
Path to existing sMRIPrep/fMRIPrep-anatomical derivatives to fasttrack the anatomical workflow.
- --use-plugin
nipype plugin configuration file
- --bids-database-dir
Path to an existing PyBIDS database folder, for faster indexing (especially useful for large datasets).
Developer options¶
Tools for testing and debugging FMRIPREP
- --patch
local repository to use within container
- --shell
open shell in image instead of running FMRIPREP
- --config
Use custom nipype.cfg file
- -e, --env
Set custom environment variable within container
- -u, --user
Run container as a given user/uid. Additionally, group/gid can beassigned, (i.e., –user <UID>:<GID>)
- --network
Run container with a different network driver (“none” to simulate no internet connection)
- --no-tty
Run docker without TTY flag -it
The FreeSurfer license¶
fMRIPRep 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 fMRIPRep.
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/fmriprep:latest \
/data /out/out \
participant \
--ignore fieldmaps
Using FreeSurfer can also be enabled when using fmriprep-docker
:
$ fmriprep-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/fmriprep:1.0.0 \
/data /out participant
...
If the environment variable $FS_LICENSE
is set in the host system, then
it will automatically used by fmriprep-docker
. For instance, the following
would be equivalent to the latest example:
$ export FS_LICENSE=$HOME/.licenses/freesurfer/license.txt
$ fmriprep-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/fmriprep:1.0.0 \
/data /out participant
...
Reusing precomputed derivatives¶
Reusing a previous, partial execution of fMRIPrep¶
fMRIPrep will pick up where it left off a previous execution, so long as the work directory points to the same location, and this directory has not been changed/manipulated.
Using a previous run of FreeSurfer¶
fMRIPrep will automatically reuse previous runs of FreeSurfer if a subject directory
named freesurfer/
is found in the output directory (<output_dir>/freesurfer
).
Reconstructions for each participant will be checked for completeness, and any missing
components will be recomputed.
You can use the --fs-subjects-dir
flag to specify a different location to save
FreeSurfer outputs.
If precomputed results are found, they will be reused.
The anatomical fast-track¶
Starting with version 20.1.0, fMRIPrep has a command-line argument (--anat-derivatives <PATH>
)
to indicate a path from which the preprocessed information derived from the T1w, T2w (if present) and
FLAIR (if present) images.
This feature was envisioned to help process very large multi-session datasets where the anatomical
images can be averaged (i.e., anatomy is not expected to vary substantially across sessions).
An example where this kind of processing would be useful is
My Connectome, a dataset that contains
107 sessions for a single-subject.
Most of these sessions contain anatomical information which, given the design of the dataset, can be averaged
across sessions as no substantial changes should happen.
In other words, the anatomical information of the dataset can be considered as cross-sectional.
Before version 20.1.0, preprocessing this dataset would be hard for two limitations:
if the dataset were to be processed in just one enormous job (be it in a commercial Cloud or HPC resources), the amount of data to be processed surely would exceed the time limitations per job (and/or related issues, such as restarting from where it left before); or
if the processing were split in sessions, then fMRIPrep would attempt to re-process the anatomical information for every session.
Because processing this emerging type of datasets (densely sampled neuroimaging) was impractical with
fMRIPrep, the option --anat-derivatives
will shortcut the whole anatomical processing.
Danger
Using the anatomical fast-track (the --anat-derivatives
argument) has important side-effects
that risk the reproducibility and reliability of fMRIPrep.
This flag breaks fMRIPrep’s internal tracing of provenance, and it trusts whatever input fMRIPrep
is given (so long it is BIDS-Derivatives compliant and contains all the necessary files).
When reporting results obtained with --anat-derivatives
, please make sure you highlight this
particular deviation from fMRIPrep, and clearly describe the alternative preprocessing of
anatomical data.
Attention
When the intention is to combine the anatomical fast-track with some advanced options that involve
standard spaces (e.g., --use-aroma
or --cifti-output
), please make sure you include the
MNI152NLin6Asym
space to the --output-spaces
list in the first invocation of fMRIPrep
(or sMRIPrep) from which the results are to be reused.
Otherwise, a warning message indicating that fMRIPrep’s expectations were not met will be issued,
and the pre-computed anatomical derivatives will not be reused.
Troubleshooting¶
Logs and crashfiles are outputted into the
<output dir>/fmriprep/sub-<participant_label>/log
directory.
Information on how to customize and understand these files can be found on the
nipype debugging
page.
Support and communication. The documentation of this project is found here: http://fmriprep.readthedocs.org/en/latest/.
All bugs, concerns and enhancement requests for this software can be submitted here: https://github.com/nipreps/fmriprep/issues.
If you have a problem or would like to ask a question about how to use fMRIPRep,
please submit a question to NeuroStars.org with an fmriprep
tag.
NeuroStars.org is a platform similar to StackOverflow but dedicated to neuroinformatics.
Previous questions about fMRIPRep are available here: http://neurostars.org/tags/fmriprep/
To participate in the fMRIPRep development-related discussions please use the following mailing list: http://mail.python.org/mailman/listinfo/neuroimaging Please add [fmriprep] to the subject line when posting on the mailing list.