A modular pipeline for correcting CSF-related artifacts in subcortical fMRI to improve signal sensitivity and reduce physiological confounds in ultra-high field (7T) imaging.
Subcortical regions are vulnerable to noise due to low signal-to-noise ratio (SNR), small size, and proximity to cerebrospinal fluid (CSF) [1, 2]. Standard CSF correction averages signals across anatomically distinct CSF compartments, which can fail to capture region-specific noise and reduce sensitivity.
To overcome these challenges, this pipeline introduces a localized CSF correction strategy that is region-specific, extracting and modeling CSF signals found directly adjacent to each subcortical region of interest (ROI).
For an overview of initial findings and methodological validation, see supporting material.
local_csf_pipeline/
├── pipeline.py # Main script to run the full pipeline
├── example_pipeline_demo.ipynb # Example demo of pipeline
├── requirements.txt # Python dependencies
├── README.md # Project overview and usage
└── utils/ # Utility functions grouped by functionality
├── __init__.py
├── process_roi.py # ROI loading, resampling, thresholding, dilation
├── extract_csf.py # Local CSF mask extraction and time series
└── compute_timeseries.py # Functional time series extraction and regression
This pipeline is designed to be used with preprocessed fMRI data (e.g., from fMRIPrep).
To run the pipeline, you will need the following inputs:
-
Preprocessed BOLD images (NifTI)
Ex:
'sub-*_task-rest_run-01_bold_space-MNI152NLin2009cAsym_preproc.nii.gz' -
Confound files (TSV)
Ex:
'sub-*_task-rest_run-01_bold_confounds.tsv' -
CSF probability tissue masks (NifTI)
Ex:
'sub-*_T1w_space-MNI152NLin2009cAsym_class-CSF_probtissue.nii.gz' -
MNI template (NifTI)
Ex:
'mni_icbm152_t1_tal_nlin_asym_09c.nii.gz' -
ROI masks
The pipeline requires the following Python packages (see requirements.txt):
numpy==2.0.2pandas==2.2.3nibabel==5.3.2nilearn==0.10.4scipy==1.13.1
To install the required packages:
pip install -r requirements.txtEach step in the pipeline is handled by a modular function located in the /utils folder.
-
process_roi_mask– Loads and resamples ROIs to MNI spaceNote: This step can be skipped if the ROI is already in the same space as the functional data
-
threshold_roi_mask– Binarizes probabilistic ROI masksNote: This step can be skipped if the ROI is already binary
-
dilate_binary_roi_mask– Expands binary ROIs outward to define a local search region
extract_local_csf_mask– Identifies CSF voxels within the dilated mask but outside the gray matter ROIextract_local_csf_time_series– Extracts average local CSF time series from the functional imageadd_local_csf_time_series_to_confound_file– Appends local CSF regressors to fMRIPrep confounds
compute_timeseries.py– Applies nuisance regression and returns cleaned functional signals
See the example notebook example_pipeline_demo.ipynb for a step-by-step walkthrough.
The following table outlines the step-by-step input files and corresponding output files generated by each function in the local CSF processing pipeline, organized by module.
| Step | Function | Module | Input(s) | Output(s) |
|---|---|---|---|---|
| 1 | process_roi_mask() |
process_roi.py |
|
|
| 2 | threshold_roi_mask() |
process_roi.py |
|
|
| 3 | dilate_binary_roi_mask() |
process_roi.py |
|
|
| 4 | extract_local_csf_mask() |
extract_csf.py |
|
|
| 5 | extract_local_csf_time_series() |
extract_csf.py |
|
|
| 6 | add_local_csf_time_series_to_confound_file() |
extract_csf.py |
|
|
| 7 | compute_timeseries() |
compute_timeseries.py |
|
|
Each subfolder corresponds to a step in the pipeline.
output/
├── 1.proc_roi/ # Resampled ROI masks
├── 2.thresh_roi/ # Thresholded binary ROI masks
├── 3.dilated_roi/ # Dilated ROI masks
├── 4.local_csf_mask/ # Extracted local CSF masks
├── 5.local_csf_ts/ # Local CSF time series
├── 6.mod_confounds/ # Confounds with CSF appended
└── 7.corrected_ts/ # Final denoised ROI time series
Note: The pipeline was developed and tested on preprocessed 7T fMRI data (resting-state fMRI: N = 81; task-fMRI: N = 39), acquired at 1.1 mm isotropic resolution with a TR of 2.34 seconds . For details on the MRI acquisition protocol, see Fischbach et al., 2024.
While the code is resolution-independent, results may vary depending on voxel size and temporal resolution.
[1] Brooks, J. C. W. P., Faull, O. K., Pattinson, K. T. S. Dp. F., & Jenkinson, M. P. (2013). Physiological Noise in Brainstem fMRI. Frontiers in Human Neuroscience, 7. https://doi.org/10.3389/fnhum.2013.00623
[2] Sclocco, R., Beissner, F., Bianciardi, M., Polimeni, J. R., & Napadow, V. (2018). Challenges and opportunities for brainstem neuroimaging with ultrahigh field MRI. NeuroImage, 168, 412–426. https://doi.org/10.1016/j.neuroimage.2017.02.052
This project is licensed under the terms of the MIT License. This means you can freely use, modify, and distribute the code, as long as you provide attribution to the original authors and source.
- First public release of the Local CSF Correction Pipeline
If you use this pipeline in your work, please cite:
Fischbach, A.K., & Noble, S. (2025). Local CSF Correction Pipeline for fMRI (Version 1.0.0) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.15236635
Note: For full citation metadata, see the CITATION.cff file included in this repository.
-
Alexandra Fischbach, M.S., Ph.D. Candidate 1,2
- Conceptualization, Method Development, Software Implementation, Documentation
-
Stephanie Noble, Ph.D. 1,2,3
- Project Supervision, Conceptual Guidance, Methodological Oversight
[1]Department of Psychology, Northeastern University
[2]The Institute for Cognitive and Brain Health, Northeastern University
[3]Department of Bioengineering, Northeastern University
This pipeline was developed by Alexandra Fischbach, a 6th year Ph.D Candidate (expected 2026), in the Neuroscience Precision Research & Idiographic Statistical Methods (NeuroPRISM) Lab at Northeastern University, under the mentorship of Stephanie Noble.
For questions, feedback, opportunities, or collaboration inquiries: fischbach.a@northeastern.edu
