fMRI Denoising BIDS App for fMRIPrep Outputs
Features | Installation | Quick Start | Strategies | References
fmridenoiser applies denoising (confound regression + temporal filtering) and optional FD-based temporal censoring to fMRI data preprocessed with fMRIPrep. It produces BIDS-compliant denoised outputs that can be used as input to downstream tools like connectomix (connectomix version 4.0.0 and onwards).
- 9 predefined denoising strategies based on neuroimaging best practices (Wang et al. 2024)
- FD-based motion censoring with configurable threshold, extension, and segment filtering (scrubbing)
- Geometric consistency checking and resampling across subjects
- Automatic brain mask resampling to reference geometry when functional images are resampled
- BIDS-compliant outputs with JSON sidecars for provenance tracking
- HTML quality reports with denoising histograms, confound time series, and FD traces
- Brain mask copying from fMRIPrep outputs (both anatomical and functional masks)
- Wildcard support for confound selection (e.g.,
a_comp_cor_*)
git clone https://github.com/ln2t/fmridenoiser.git
cd fmridenoiser
pip install -e .# Basic denoising with a predefined strategy
fmridenoiser /path/to/fmriprep /path/to/fmridenoiser_output participant --strategy csfwm_6p
# Process a specific subject
fmridenoiser /path/to/fmriprep /path/to/fmridenoiser_output participant --participant-label 01 --strategy minimal
# With FD-based motion censoring
fmridenoiser /path/to/fmriprep /path/to/fmridenoiser_output participant --strategy csfwm_6p --fd-threshold 0.5
# Using scrubbing5 strategy (includes FD censoring)
fmridenoiser /path/to/fmriprep /path/to/fmridenoiser_output participant --strategy scrubbing5| Strategy | Confounds | Description |
|---|---|---|
minimal | 6 motion params | Motion parameters only |
csfwm_6p | CSF + WM + 6 motion | Standard physiological + motion |
csfwm_12p | CSF + WM + 12 motion | With motion derivatives |
gs_csfwm_6p | GS + CSF + WM + 6 motion | With global signal regression |
gs_csfwm_12p | GS + CSF + WM + 12 motion | GSR + motion derivatives |
csfwm_24p | CSF + WM + 24 motion | Full motion model |
compcor_6p | 6 aCompCor + 6 motion | Data-driven + motion |
simpleGSR | GS + CSF + WM + 24 motion | Preserves time series continuity |
scrubbing5 | CSF/WM deriv + 24 motion + FD=0.5cm + scrub=5 | Maximum denoising quality |
Temporal censoring (volume removal) is applied after denoising. Denoising via confound regression and temporal filtering (nilearn.image.clean_img) is performed on the full time series first, then volumes are removed based on motion thresholds if censoring is enabled.
Brain masks from fMRIPrep are copied to the output directory for quality assurance and downstream analysis. When geometric inconsistencies are detected across the dataset (varying voxel dimensions or field of view), the following sequence is applied:
- Functional images are resampled to a reference geometry
- Brain masks are automatically resampled on-the-fly to match the reference geometry using nearest-neighbor interpolation
- Both resampled images and masks maintain binary integrity (values remain 0 or 1 after resampling)
- Copied masks are resampled in-place (original fMRIPrep masks are never modified)
This ensures spatial consistency between your functional data and brain masks, which is critical for:
- Connectivity analysis (downstream tools like connectomix)
- Group-level statistics (requires aligned geometries)
- Quality control (masked reports accurately reflect processed data)
fmridenoiser is designed to work as a preprocessing step before connectomix:
# Step 1: Denoise with fmridenoiser
fmridenoiser /path/to/fmriprep /path/to/fmridenoiser_output participant --strategy csfwm_6p
# Step 2: Compute connectivity with connectomix
connectomix /path/to/fmridenoiser_output /path/to/connectomix_output participant \
--method roiToRoi --atlas schaefer2018n100- fMRIPrep: Esteban et al. (2019). fMRIPrep: a robust preprocessing pipeline for functional MRI. Nature Methods, 16, 111-116.
- Nilearn: Abraham et al. (2014). Machine learning for neuroimaging with scikit-learn. Frontiers in Neuroinformatics, 8, 14.
- Denoising strategies: Wang et al. (2024). Benchmarking fMRI denoising strategies for functional connectomics.
- Motion scrubbing: Power et al. (2012). Spurious but systematic correlations in functional connectivity MRI networks arise from subject motion. NeuroImage, 59, 2142-2154.
fmridenoiser is built on Nilearn, a powerful Python library for analyzing neuroimaging data. For questions, refer to the Nilearn documentation.
AGPLv3 License - See LICENSE file for details.