DOCSEARCHbyAlgolia
Submit Docs

fMRIPrep

repository·master·Indexed 20 days ago

https://github.com/nipreps/fmriprep

A robust pipeline for preprocessing diverse fMRI data. It provides a Python wrapper for running the pipeline within Docker containers, abstracting Docker CLI complexity. The tool includes modules for internal configuration (fmriprep.config) and workflow logic (fmriprep.workflows), supports BIDS input filtering, and integrates with TemplateFlow for spatial normalization. Documentation covers performance benchmarks, resource allocation, and troubleshooting for memory issues, FreeSurfer outputs, and BIDS indexing.

Tokens
16.5K
Snippets
46
Records
76
Agent score
73%

What's inside fmriprep

  1. Overview of fMRIPrep

    master

    fMRIPrep is a robust preprocessing pipeline for task-based and resting-state functional MRI (fMRI) data. It is part of the NiPreps (NeuroImaging PREProcessing toolS) ecosystem and is designed to be a state-of-the-art, easily accessible interface that minimizes user input while providing comprehensive error and output reporting.

    Key capabilities include:

    • Transforming raw fMRI data into a fully preprocessed form.
    • Integrating tools from multiple software packages (FSL, ANTs, FreeSurfer, and AFNI) to achieve optimal processing quality.
    • Generating preprocessing quality reports for visual inspection of results.
    • Providing verbose output and meaningful error reporting for each subject.
    • Automating and parallelizing processing steps for increased speed.

    Note: fMRIPrep performs 'minimal preprocessing', which includes motion correction, field unwarping, normalization, bias field correction, and brain extraction.

  2. Overview of the fMRIPrep Docker wrapper

    master
    The fmriprep-docker package is a lightweight Python wrapper designed to run the fMRIPrep preprocessing pipeline within a Docker environment. It simplifies the process by automatically generating the necessary Docker commands, providing an intuitive interface for executing the fMRIPrep workflow while handling the complexities of Docker command construction.

  3. Overview of fMRIPrep capabilities

    master

    fMRIPrep is an analysis-agnostic preprocessing pipeline designed for both task-based and resting-state fMRI data. It automates a best-in-breed workflow to handle coregistration, normalization, unwarping, noise component extraction, segmentation, and skullstripping.

    Key features include:

    • Automated Workflow: Adapts to dataset idiosyncrasies without manual intervention.
    • High-Quality Outputs: Produces data ready for group-level analyses (task-based, resting-state, graph theory, surface/volume-based statistics).
    • Assessment Reports: Generates preprocessing-assessment reports to help users identify data quality issues.
    • Parallelization: Supports automated and parallelized processing for increased speed.
    • Transparency: Provides verbose output regarding preprocessing stages and meaningful error messages.

    The workflow is built on Nipype and integrates tools from FSL, ANTs, FreeSurfer, AFNI, and Nilearn.

  5. Understand the three classes of fMRIPrep outputs

    master

    fMRIPrep generates three main types of outcomes that conform to the BIDS Derivatives specification:

    1. Visual QA (quality assessment) reports: An HTML file per subject for visual assessment of processing quality and transparency.
    2. Derivatives (preprocessed data): The input fMRI data ready for analysis (e.g., INU-corrected T1w images, brain masks, or BOLD images after motion/slice-timing correction).
    3. Confounds: A special family of derivatives used to inform subsequent denoising steps.

    Note on Denoising: fMRIPrep remains agnostic to subsequent analysis and does not perform denoising (like spatial smoothing) itself, with the exception of CompCor regressors, which are calculated after temporal high-pass filtering.

  6. Reuse precomputed derivatives

    master

    As of version 23.2.0, fMRIPrep can reuse precomputed derivatives that follow BIDS Derivatives conventions. This is an experimental feature used to enable 'minimal' processing modes, integrate with larger pipelines, or substitute custom derivatives (e.g., custom brain extraction tools).

    Use the --derivatives (or -d) flag one or more times to provide these paths. You can use the --level flag in conjunction with this to control which derivatives are generated.

    fmriprep <args> --derivatives <path_to_derivatives>
# or
fmriprep <args> -d <path_to_derivatives>

  7. Reuse FreeSurfer and partial executions

    master

    Reusing partial executions

    fMRIPrep can pick up from a previous execution if the work directory (-w) points to the same location and has not been modified. Note that some workflow nodes will always rerun.

    Reusing FreeSurfer outputs

    fMRIPrep automatically reuses FreeSurfer runs if a freesurfer/ directory is found within the output directory (<output_dir>/freesurfer). It checks for completeness and only recomputes missing components. You can specify a custom location for these outputs using the --fs-subjects-dir flag.

  8. fMRIPrep command-line interface structure

    master

    The fmriprep command-line adheres to BIDS-Apps recommendations. The structure depends on whether you are running a bare-metal installation or using a container.

    Bare-metal structure

    Used when fMRIPrep is installed directly in your environment: fmriprep <input_bids_path> <derivatives_path> <analysis_level> <named_options>

    Containerized structure

    When running via a container (without the fmriprep-docker wrapper), the command includes a preamble for the container engine and the image name: <container_command_and_options> <container_image> <input_bids_path> <derivatives_path> <analysis_level> <fmriprep_named_options>

    # Bare-metal
$ fmriprep <input_bids_path> <derivatives_path> <analysis_level> <named_options>

# Containerized (manual)
$ <container_command_and_options> <container_image> <input_bids_path> <derivatives_path> <analysis_level> <fmriprep_named_options>

  9. Core principles of fMRIPrep

    master

    fMRIPrep is built upon three foundational principles:

    1. Robustness: The pipeline automatically adapts preprocessing steps based on the input dataset, ensuring high-quality results regardless of scanner manufacturer, scanning parameters, or the presence of additional correction scans (like fieldmaps).
    2. Ease of use: By relying on the BIDS (Brain Imaging Data Structure) standard, the pipeline reduces the need for manual parameter input, allowing for highly automated execution.
    3. "Glass box" philosophy: While the pipeline is automated, it emphasizes transparency. It provides detailed visual reports for every subject, allowing researchers to inspect the accuracy of critical processing steps and make informed decisions about data inclusion for group-level analyses.

  10. How internal space expansion works with --cifti-outputs and --use-syn-sdc

    master

    Certain flags trigger the use of specific template spaces for internal modules (e.g., generating HCP-compatible grayordinates or fieldmap-less distortion correction).

    When you use --cifti-outputs or --use-syn-sdc, fMRIPrep will automatically expand the list of internal spaces to include the required identifiers if they aren't already in your --output-spaces list.

    Crucially: These implicitly added spaces are used for processing but will not be saved to the derivatives directory. Only spaces explicitly listed in --output-spaces are exported.

  11. Understand and use fMRIPrep confounds

    master

    fMRIPrep generates a large array of potential nuisance regressors (confounds) to help researchers perform denoising (removing non-neuronal fluctuations like head motion, scanner noise, or physiological effects). These are stored in desc-confounds_timeseries.tsv files, with one column per variable.

    CRITICAL: Do not include all columns from desc-confounds_timeseries.tsv in your design matrix. You must filter the table to include only the specific confounds relevant to your analysis.

    Common categories of confounds include:

    • Basic motion parameters: 6 rigid-body parameters (trans_x, trans_y, trans_z, rot_x, rot_y, rot_z).
    • Global signals: csf, white_matter, and global_signal.
    • Motion parameter expansion: 24 parameters including temporal derivatives (_derivative1) and quadratic terms (_power2) for motion and global signals.
    • Outlier detection: Metrics like framewise_displacement, rmsd, dvars, and std_dvars, as well as specific motion_outlier_XX columns.
    • Discrete cosine-basis regressors: cosine_XX columns used to account for low-frequency drifts.
    • CompCor (Component Based Noise Correction): PCA-based noise components (a_comp_cor_XX for anatomical and t_comp_cor_XX for temporal).
    • Brain edge (crown) confounds: Principal components extracted from the brain's outer edge.

  12. Use TemplateFlow modifiers for resolution and cohorts

    master

    When specifying standard spaces via --output-spaces, you can use TemplateFlow modifiers separated by a colon (:) to customize the output.

    Common Modifiers:

    • Resolution (res-): Selects a specific resolution index from the template. Note that res-2 is an index, not necessarily a 2mm resolution. Use :res-native to keep the original BOLD resolution.
    • Cohort (cohort-): Selects a specific sub-group/cohort within a template (e.g., age groups in pediatric templates).
    • Density (den-): Preferred for surface spaces (e.g., fsaverage:den-10k instead of the legacy fsaverage5).

    Combinatorial Behavior: Modifiers are combinatorial. If you provide multiple cohorts and resolutions, fMRIPrep will generate all possible combinations of those selections.

    # Example: Select cohort 2, resolution 1 of the template, and the native resolution
--output-spaces MNIPediatricAsym:res-1:cohort-2

# Example: Combinatorial modifiers (generates 4 combinations)
--output-spaces MNIPediatricAsym:cohort-1:cohort-2:res-native:res-1