Usage¶
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]
[--participant_label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]]
[-t TASK_ID] [--nthreads NTHREADS]
[--omp-nthreads OMP_NTHREADS] [--mem_mb MEM_MB] [--low-mem]
[--use-plugin USE_PLUGIN] [--anat-only] [--boilerplate]
[--ignore-aroma-denoising-errors] [-v] [--debug]
[--ignore {fieldmaps,slicetiming,sbref} [{fieldmaps,slicetiming,sbref} ...]]
[--longitudinal] [--t2s-coreg] [--bold2t1w-dof {6,9,12}]
[--output-space {T1w,template,fsnative,fsaverage,fsaverage6,fsaverage5} [{T1w,template,fsnative,fsaverage,fsaverage6,fsaverage5} ...]]
[--force-bbr] [--force-no-bbr]
[--template {MNI152NLin2009cAsym}]
[--output-grid-reference OUTPUT_GRID_REFERENCE]
[--template-resampling-grid TEMPLATE_RESAMPLING_GRID]
[--medial-surface-nan] [--use-aroma]
[--aroma-melodic-dimensionality AROMA_MELODIC_DIMENSIONALITY]
[--skull-strip-template {OASIS,NKI}]
[--skull-strip-fixed-seed] [--fmap-bspline] [--fmap-no-demean]
[--use-syn-sdc] [--force-syn] [--fs-license-file 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¶
--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 |
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 |
--ignore-aroma-denoising-errors | |
ignores the errors ICA_AROMA returns when there are no components classified as either noise or signal | |
-v, --verbose | increases log verbosity for each occurence, debug level is -vvv |
--debug | DEPRECATED - Does not do what you want. |
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. |
--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. |
--output-space | Possible choices: T1w, template, fsnative, fsaverage, fsaverage6, fsaverage5
this argument can be single value or a space delimited list, for example: –output-space T1w fsnative |
--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) |
--template | Possible choices: MNI152NLin2009cAsym volume template space (default: MNI152NLin2009cAsym) |
--output-grid-reference | |
Deprecated after FMRIPREP 1.0.8. Please use –template-resampling-grid instead. | |
--template-resampling-grid | |
Keyword (“native”, “1mm”, or “2mm”) or path to an existing file. Allows to define a reference grid for the resampling of BOLD images in template space. Keyword “native” will use the original BOLD grid as reference. Keywords “1mm” and “2mm” will use the corresponding isotropic template resolutions. If a path is given, the grid of that image will be used. It determines the field of view and resolution of the output images, but is not used in normalization. | |
--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). |
Specific options for running ICA_AROMA¶
--use-aroma | add ICA_AROMA to your preprocessing stream |
--aroma-melodic-dimensionality | |
set the dimensionality of MELODIC before runningICA-AROMA |
Specific options for ANTs registrations¶
--skull-strip-template | |
Possible choices: OASIS, NKI select ANTs skull-stripping template (default: OASIS)) | |
--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 |
Surface preprocessing options¶
--no-submm-recon | |
disable sub-millimeter (hires) reconstruction | |
--cifti-output | output BOLD files as CIFTI dtseries |
--fs-no-reconall, --no-freesurfer | |
disable FreeSurfer surface preprocessing. Note : –no-freesurfer is deprecated and will be removed in 1.2. Use –fs-no-reconall instead. |
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 docker wrapper CLI¶
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-grid-reference OUTPUT_GRID_REFERENCE]
[--template-resampling-grid TEMPLATE_RESAMPLING_GRID]
[--fs-license-file 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-grid-reference | |
Deprecated after FMRIPREP 1.0.8. Please use –template-resampling-grid instead. | |
--template-resampling-grid | |
Keyword (“native”, “1mm”, or “2mm”) or path to an existing file. Allows to define a reference grid for the resampling of BOLD images in template space. Keyword “native” will use the original BOLD grid as reference. Keywords “1mm” and “2mm” will use the corresponding isotropic template resolutions. If a path is given, the grid of that image will be used. It determines the field of view and resolution of the output images, but is not used in 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 |
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 |
Debugging¶
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.
All previous fmriprep
questions 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.
Not running on a local machine? - Data transfer¶
If you intend to run fmriprep
on a remote system, you will need to
make your data available within that system first.
For instance, here at the Poldrack Lab we use Stanford’s HPC system, called Sherlock. Sherlock enables the following data transfer options.
Alternatively, more comprehensive solutions such as Datalad will handle data transfers with the appropriate settings and commands. Datalad also performs version control over your data.