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/
Further information about BIDS and BIDS-Apps can be found at the NiPreps portal.
Command-Line Arguments
fMRIPrep: fMRI PREProcessing workflows v24.1.0
usage: fmriprep [-h] [--skip_bids_validation]
[--participant-label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]]
[-t TASK_ID] [--echo-idx ECHO_IDX] [--bids-filter-file FILE]
[-d PACKAGE=PATH [PACKAGE=PATH ...]]
[--bids-database-dir PATH] [--nprocs NPROCS]
[--omp-nthreads OMP_NTHREADS] [--mem MEMORY_MB] [--low-mem]
[--use-plugin FILE] [--sloppy] [--anat-only]
[--level {minimal,resampling,full}] [--boilerplate-only]
[--reports-only]
[--ignore {fieldmaps,slicetiming,sbref,t2w,flair,fmap-jacobian} [{fieldmaps,slicetiming,sbref,t2w,flair,fmap-jacobian} ...]]
[--output-spaces [OUTPUT_SPACES ...]] [--longitudinal]
[--bold2t1w-init {register,header}] [--bold2t1w-dof {6,9,12}]
[--bold2anat-init {auto,t1w,t2w,header}]
[--bold2anat-dof {6,9,12}] [--force-bbr] [--force-no-bbr]
[--slice-time-ref SLICE_TIME_REF] [--dummy-scans DUMMY_SCANS]
[--random-seed _RANDOM_SEED]
[--me-t2s-fit-method {curvefit,loglin}]
[--output-layout {bids,legacy}] [--me-output-echos]
[--aggregate-session-reports AGGR_SES_REPORTS]
[--medial-surface-nan] [--project-goodvoxels]
[--md-only-boilerplate] [--cifti-output [{91k,170k}]]
[--no-msm] [--use-aroma USE_AROMA]
[--aroma-melodic-dimensionality AROMA_MELODIC_DIM]
[--error-on-aroma-warnings AROMA_ERR_ON_WARN]
[--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 [{warn,error}]]
[--force-syn] [--fs-license-file FILE]
[--fs-subjects-dir PATH] [--no-submm-recon] [--fs-no-reconall]
[--fs-no-resume] [--track-carbon]
[--country-code COUNTRY_CODE] [--version] [-v] [-w WORK_DIR]
[--clean-workdir] [--resource-monitor] [--config-file FILE]
[--write-graph] [--stop-on-first-crash] [--notrack]
[--debug {compcor,fieldmaps,pdb,all} [{compcor,fieldmaps,pdb,all} ...]]
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).
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/24.1.0/faq.html#how-do-I-select-only-certain-files-to-be-input-to-fMRIPrep
- -d, --derivatives
Search PATH(s) for pre-computed derivatives. These may be provided as named folders (e.g., –derivatives smriprep=/path/to/smriprep).
- --bids-database-dir
Path to a PyBIDS database folder, for faster indexing (especially useful for large datasets). Will be created if not present.
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
- --sloppy
Use low-quality tools for speed - TESTING ONLY
Options for performing only a subset of the workflow
- --anat-only
Run anatomical workflows only
- --level
Possible choices: minimal, resampling, full
Processing level; may be ‘minimal’ (nothing that can be recomputed), ‘resampling’ (recomputable targets that aid in resampling) or ‘full’ (all target outputs).
- --boilerplate-only, --boilerplate_only
Generate boilerplate only
- --reports-only
Only generate reports, don’t run workflows. This will only rerun report aggregation, not reportlet generation for specific nodes.
Workflow configuration
- --ignore
Possible choices: fieldmaps, slicetiming, sbref, t2w, flair, fmap-jacobian
Ignore selected aspects of the input dataset to disable corresponding parts of the workflow (a space delimited list)
- --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/24.1.0/spaces.html- --longitudinal
Treat dataset as longitudinal - may increase runtime
- --bold2t1w-init
Possible choices: register, header
Deprecated - use –bold2anat-init instead.
- --bold2t1w-dof
Possible choices: 6, 9, 12
Deprecated - use –bold2anat-dof instead.
- --bold2anat-init
Possible choices: auto, t1w, t2w, header
Method of initial BOLD to anatomical coregistration. If auto, a T2w image is used if available, otherwise the T1w image. t1w forces use of the T1w, t2w forces use of the T2w, and header uses the BOLD header information without an initial registration.
- --bold2anat-dof
Possible choices: 6, 9, 12
Degrees of freedom when registering BOLD to anatomical 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)
- --slice-time-ref
The time of the reference slice to correct BOLD values to, as a fraction acquisition time. 0 indicates the start, 0.5 the midpoint, and 1 the end of acquisition. The alias start corresponds to 0, and middle to 0.5. The default value is 0.5.
- --dummy-scans
Number of nonsteady-state volumes. Overrides automatic detection.
- --random-seed
Initialize the random seed for the workflow
- --me-t2s-fit-method
Possible choices: curvefit, loglin
The method by which to estimate T2* and S0 for multi-echo data. ‘curvefit’ uses nonlinear regression. It is more memory intensive, but also may be more accurate, than ‘loglin’. ‘loglin’ uses log-linear regression. It is faster and less memory intensive, but may be less accurate.
- --project-goodvoxels
Exclude voxels whose timeseries have locally high coefficient of variation from surface resampling. Only performed for GIFTI files mapped to a freesurfer subject (fsaverage or fsnative).
Options for modulating outputs
- --output-layout
Possible choices: bids, legacy
Organization of outputs. “bids” (default) places fMRIPrep derivatives directly in the output directory, and defaults to placing FreeSurfer derivatives in <output-dir>/sourcedata/freesurfer. “legacy” creates derivative datasets as subdirectories of outputs.
- --me-output-echos
Output individual echo time series with slice, motion and susceptibility correction. Useful for further Tedana processing post-fMRIPrep.
- --aggregate-session-reports
Maximum number of sessions aggregated in one subject’s visual report. If exceeded, visual reports are split by session.
- --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).
- --md-only-boilerplate
Skip generation of HTML and LaTeX formatted citation with pandoc
- --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)
- --no-msm
Disable Multimodal Surface Matching surface registration.
[DEPRECATED] Options for running ICA_AROMA
- --use-aroma
Deprecated. Will raise an error in 24.0.
- --aroma-melodic-dimensionality
Deprecated. Will raise an error in 24.0.
- --error-on-aroma-warnings
Deprecated. Will raise an error in 24.0.
Options relating to 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 (OASIS30ANTs, by default)
- --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
Perform 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
Possible choices: warn, error
Use fieldmap-less distortion correction based on anatomical image; if unable, error (default) or warn based on optional argument.
- --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)
- --no-submm-recon
Disable sub-millimeter (hires) reconstruction
- --fs-no-reconall
Disable FreeSurfer surface preprocessing.
- --fs-no-resume
EXPERT: Import pre-computed FreeSurfer reconstruction without resuming. The user is responsible for ensuring that all necessary files are present.
Options for carbon usage tracking
- --track-carbon
Tracks power draws using CodeCarbon package
- --country-code
Country ISO code used by carbon trackers
Other options
- --version
show program’s version number and exit
- -v, --verbose
Increases log verbosity for each occurrence, debug level is -vvv
- -w, --work-dir
Path where intermediate results should be stored
- --clean-workdir
Clears working directory of contents. Use of this flag is not recommended when running concurrent processes of fMRIPrep.
- --resource-monitor
Enable Nipype’s resource monitoring to keep track of memory and CPU usage
- --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, fieldmaps, pdb, all
Debug mode(s) to enable. ‘all’ is alias for all available modes.
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 acknowledge this work using the citation boilerplate that fMRIPrep includes in the visual report generated for every subject processed. For a more detailed description of the citation boilerplate and its relevance, please check out the NiPreps documentation. Please report any feedback to our GitHub repository.
usage: fmriprep-docker [-h] [--version] [-i IMG] [-w WORK_DIR]
[--output-spaces [OUTPUT_SPACES ...]]
[--fs-license-file PATH] [--fs-subjects-dir PATH]
[--config-file PATH] [-d PATH [PATH ...]]
[--use-plugin PATH] [--bids-database-dir PATH]
[--bids-filter-file 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; see fmriprep usage for complete descriptions
- -w, --work-dir
- --output-spaces
- --fs-license-file
- --fs-subjects-dir
- --config-file
- -d, --derivatives
Search PATH(s) for pre-computed derivatives.
- --use-plugin
- --bids-database-dir
- --bids-filter-file
Developer options
Tools for testing and debugging FMRIPREP
- --patch
Sequence of PACKAGE=PATH specifications to patch a Python package into the container Python environment.
- --shell
Open shell in image instead of running FMRIPREP
- --config
Use custom nipype.cfg file
- -e, --env
Set custom environment variables 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
Limitations and reasons not to use fMRIPrep
Very narrow FoV images oftentimes do not contain enough information for standard image registration methods to work correctly. Also, problems may arise when extracting the brain from these data. fMRIPrep supports pre-aligned BOLD series, and accepting pre-computed derivatives such as brain masks is a target of future effort.
fMRIPrep may also underperform for particular populations (e.g., infants) and non-human brains, although appropriate templates can be provided to overcome the issue.
The “EPInorm” approach is currently not supported, although we plan to implement this feature (see #620).
If you really want unlimited flexibility (which is obviously a double-edged sword).
If you want students to suffer through implementing each step for didactic purposes, or to learn shell-scripting or Python along the way.
If you are trying to reproduce some in-house lab pipeline.
(Reasons 4-6 were kindly provided by S. Nastase in his open review of our pre-print).
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. Some workflow nodes will rerun unconditionally, so there will always be some amount of reprocessing.
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.
BIDS Derivatives reuse
As of version 23.2.0, fMRIPrep can reuse precomputed derivatives that follow BIDS Derivatives
conventions. To provide derivatives to fMRIPrep, use the --derivatives (-d) flag one
or more times.
This mechanism replaces the earlier, more limited --anat-derivatives flag.
Note
Derivatives reuse is considered experimental.
This feature has several intended use-cases:
To enable fMRIPrep to be run in a “minimal” mode, where only the most essential derivatives are generated. This can be useful for large datasets where disk space is a concern, or for users who only need a subset of the derivatives. Further derivatives may be generated later, or by a different tool.
To enable fMRIPrep to be integrated into a larger processing pipeline, where other tools may generate derivatives that fMRIPrep can use in place of its own steps.
To enable users to substitute their own custom derivatives for those generated by fMRIPrep. For example, a user may wish to use a different brain extraction tool, or a different registration tool, and then use fMRIPrep to generate the remaining derivatives.
To enable complicated meta-workflows, where fMRIPrep is run multiple times with different options, and the results are combined. For example, the My Connectome dataset contains 107 sessions for a single-subject. Processing of all sessions simultaneously would be impractical, but the anatomical processing can be done once, and then the functional processing can be done separately for each session.
See also the --level flag, which can be used to control which derivatives are
generated.
Troubleshooting
Logs and crashfiles are output into the
<output dir>/fmriprep/sub-<participant_label>/log directory.
Information on how to customize and understand these files can be found on the
Debugging Nipype Workflows
page.
Support and communication. The documentation of this project is found here: https://fmriprep.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: https://neurostars.org/tag/fmriprep/
To participate in the fMRIPRep development-related discussions please use the following mailing list: https://mail.python.org/mailman/listinfo/neuroimaging Please add [fmriprep] to the subject line when posting on the mailing list.
About the NiPreps framework licensing
Please check https://www.nipreps.org/community/licensing/ for detailed information on the criteria we use to license fMRIPrep and other projects of the framework.
License information
Copyright (c) 2023, the NiPreps Developers.
As of the 21.0.x pre-release and release series, fMRIPrep is licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Copyright (c) 2015-2023, the fMRIPrep developers and the CRN. All rights reserved.
fMRIPrep 20.2 series and earlier are licensed under the BSD 3-clause license. You may obtain a copy of the License at https://opensource.org/licenses/BSD-3-Clause
All trademarks referenced herein are property of their respective holders.
The fmriprep-wrapper for Docker
Copyright (c) 2020-2023, the NiPreps Developers. Copyright (c) 2015-2020, the fMRIPrep developers and the CRN. All rights reserved.
fMRIPrep-wrapper is licensed under the BSD 3-clause license. You may obtain a copy of the License at https://opensource.org/licenses/BSD-3-Clause
All trademarks referenced herein are property of their respective holders.