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

usage: fmriprep [-h] [--version] [--skip_bids_validation]
                [--participant_label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]]
                [-t TASK_ID] [--echo-idx ECHO_IDX] [--nthreads NTHREADS]
                [--omp-nthreads OMP_NTHREADS] [--mem_mb MEM_MB] [--low-mem]
                [--use-plugin USE_PLUGIN] [--anat-only] [--boilerplate]
                [--md-only-boilerplate] [--error-on-aroma-warnings] [-v]
                [--ignore {fieldmaps,slicetiming,sbref} [{fieldmaps,slicetiming,sbref} ...]]
                [--longitudinal] [--t2s-coreg]
                [--output-spaces OUTPUT_SPACES [OUTPUT_SPACES ...]]
                [--bold2t1w-dof {6,9,12}] [--force-bbr] [--force-no-bbr]
                [--medial-surface-nan] [--dummy-scans DUMMY_SCANS]
                [--use-aroma]
                [--aroma-melodic-dimensionality AROMA_MELODIC_DIMENSIONALITY]
                [--return-all-components]
                [--fd-spike-threshold FD_SPIKE_THRESHOLD]
                [--dvars-spike-threshold DVARS_SPIKE_THRESHOLD]
                [--skull-strip-template SKULL_STRIP_TEMPLATE]
                [--skull-strip-fixed-seed] [--fmap-bspline] [--fmap-no-demean]
                [--use-syn-sdc] [--force-syn] [--fs-license-file PATH]
                [--fs-subjects-dir PATH] [--no-submm-recon]
                [--cifti-output | --fs-no-reconall] [-w WORK_DIR]
                [--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 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

Options to handle performance

--nthreads, --n_cpus, -n-cpus

maximum number of threads across all processes

--omp-nthreads

maximum number of threads per-process

--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 configuration file

--anat-only

run anatomical workflows only

--boilerplate

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

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

--t2s-coreg

If provided with multi-echo BOLD dataset, create T2*-map and perform T2*-driven coregistration. When multi-echo data is provided and this option is not enabled, standard EPI-T1 coregistration is performed using the middle echo.

--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”, “fsLR”, “fsaverage”) 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, the res-* modifier does not define the resolution used for the spatial normalization. For further details, please check out https://fmriprep.readthedocs.io/en/1.5.3/spaces.html

--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.

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

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

output BOLD files as CIFTI dtseries

--fs-no-reconall

disable FreeSurfer surface preprocessing.

Other options

-w, --work-dir

path where intermediate results should be stored

--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 FMRIPREP developers. This information helps to improve FMRIPREP 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 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/poldracklab/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]
                       [--use-plugin PATH] [-f PATH] [-n PATH] [-p PATH]
                       [--shell] [--config PATH] [-e ENV_VAR value] [-u USER]
                       [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, the res-* 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)

--use-plugin

nipype plugin configuration file

Developer options

Tools for testing and debugging FMRIPREP

-f, --patch-fmriprep

working fmriprep repository

-n, --patch-niworkflows

working niworkflows repository

-p, --patch-nipype

working nipype repository

--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

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 \
    poldracklab/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 poldracklab/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 poldracklab/fmriprep:1.0.0 \
    /data /out participant
...

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/poldracklab/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.