ENH: Add MP-PCA/NORDIC denoising through dwidenoise

.circleci/config.yml

@@ -648,6 +648,7 @@ jobs:
                 ${FASTRACK_ARG} \
                 --fs-no-reconall --sloppy \
                 --output-spaces MNI152NLin2009cAsym:res-2 anat func \
+                --thermal-denoise-method mppca \
                 --mem-mb 14336 --nthreads 4 -vv --debug compcor
       - run: *check_outputs
       - run:
@@ -755,6 +756,7 @@ jobs:
                 --fs-no-reconall --use-syn-sdc --ignore slicetiming \
                 --dummy-scans 1 --sloppy --write-graph \
                 --output-spaces MNI152NLin2009cAsym \
+                --thermal-denoise-method mppca \
                 --mem-mb 14336 --nthreads 4 -vv
       - run: *check_outputs
       - run:

.circleci/ds054_fasttrack_outputs.txt

@@ -33,6 +33,7 @@ sub-100185/func/sub-100185_task-machinegame_run-01_desc-hmc_boldref.json
 sub-100185/func/sub-100185_task-machinegame_run-01_desc-hmc_boldref.nii.gz
 sub-100185/func/sub-100185_task-machinegame_run-01_desc-preproc_bold.json
 sub-100185/func/sub-100185_task-machinegame_run-01_desc-preproc_bold.nii.gz
+sub-100185/func/sub-100185_task-machinegame_run-01_desc-noise_boldmap.nii.gz
 sub-100185/func/sub-100185_task-machinegame_run-01_from-boldref_to-auto00000_mode-image_xfm.json
 sub-100185/func/sub-100185_task-machinegame_run-01_from-boldref_to-auto00000_mode-image_xfm.txt
 sub-100185/func/sub-100185_task-machinegame_run-01_from-boldref_to-T1w_mode-image_desc-coreg_xfm.json
@@ -61,6 +62,7 @@ sub-100185/func/sub-100185_task-machinegame_run-02_desc-hmc_boldref.json
 sub-100185/func/sub-100185_task-machinegame_run-02_desc-hmc_boldref.nii.gz
 sub-100185/func/sub-100185_task-machinegame_run-02_desc-preproc_bold.json
 sub-100185/func/sub-100185_task-machinegame_run-02_desc-preproc_bold.nii.gz
+sub-100185/func/sub-100185_task-machinegame_run-02_desc-noise_boldmap.nii.gz
 sub-100185/func/sub-100185_task-machinegame_run-02_from-boldref_to-auto00000_mode-image_xfm.json
 sub-100185/func/sub-100185_task-machinegame_run-02_from-boldref_to-auto00000_mode-image_xfm.txt
 sub-100185/func/sub-100185_task-machinegame_run-02_from-boldref_to-T1w_mode-image_desc-coreg_xfm.json

.circleci/ds054_outputs.txt

@@ -43,6 +43,7 @@ sub-100185/func/sub-100185_task-machinegame_run-01_desc-hmc_boldref.json
 sub-100185/func/sub-100185_task-machinegame_run-01_desc-hmc_boldref.nii.gz
 sub-100185/func/sub-100185_task-machinegame_run-01_desc-preproc_bold.json
 sub-100185/func/sub-100185_task-machinegame_run-01_desc-preproc_bold.nii.gz
+sub-100185/func/sub-100185_task-machinegame_run-01_desc-noise_boldmap.nii.gz
 sub-100185/func/sub-100185_task-machinegame_run-01_from-boldref_to-auto00000_mode-image_xfm.json
 sub-100185/func/sub-100185_task-machinegame_run-01_from-boldref_to-auto00000_mode-image_xfm.txt
 sub-100185/func/sub-100185_task-machinegame_run-01_from-boldref_to-T1w_mode-image_desc-coreg_xfm.json
@@ -71,6 +72,7 @@ sub-100185/func/sub-100185_task-machinegame_run-02_desc-hmc_boldref.json
 sub-100185/func/sub-100185_task-machinegame_run-02_desc-hmc_boldref.nii.gz
 sub-100185/func/sub-100185_task-machinegame_run-02_desc-preproc_bold.json
 sub-100185/func/sub-100185_task-machinegame_run-02_desc-preproc_bold.nii.gz
+sub-100185/func/sub-100185_task-machinegame_run-02_desc-noise_boldmap.nii.gz
 sub-100185/func/sub-100185_task-machinegame_run-02_from-boldref_to-auto00000_mode-image_xfm.json
 sub-100185/func/sub-100185_task-machinegame_run-02_from-boldref_to-auto00000_mode-image_xfm.txt
 sub-100185/func/sub-100185_task-machinegame_run-02_from-boldref_to-T1w_mode-image_desc-coreg_xfm.json

docs/workflows.rst

@@ -391,6 +391,32 @@ For a more accurate estimation of head-motion, we calculate its parameters
 before any time-domain filtering (i.e., :ref:`slice-timing correction <bold_stc>`),
 as recommended in [Power2017]_.
 
+
+Thermal noise removal
+~~~~~~~~~~~~~~~~~~~~~
+:py:func:`~fmriprep.workflows.bold.denoise.init_bold_dwidenoise_wf`
+
+.. workflow::
+    :graph2use: colored
+    :simple_form: yes
+
+    from fmriprep.workflows.bold.denoise import init_bold_dwidenoise_wf
+
+    wf = init_bold_dwidenoise_wf(
+        has_phase=True,
+        has_norf=True,
+        mem_gb=1,
+    )
+
+Functional MRI exhibits low signal-to-noise, which is exacerbated by thermal noise,
+especially at higher field strengths.
+Thermal noise removal with the ``dwidenoise`` tool from MRtrix3 can be enabled
+with the ``--thermal-denoise-method`` parameter.
+fMRIPrep will automatically leverage phase data, when available, to improve the
+denoising process.
+This can be disabled with the ``--ignore phase`` command line argument.
+
+
 .. _bold_stc:
 
 Slice time correction

env.yml

@@ -2,6 +2,7 @@ name: fmriprep
 channels:
   - https://fsl.fmrib.ox.ac.uk/fsldownloads/fslconda/public/
   - conda-forge
+  - mrtrix3
 # Update this ~yearly; last updated Jan 2024
 dependencies:
   - python=3.11
@@ -39,6 +40,8 @@ dependencies:
   - fsl-mcflirt=2111.0
   - fsl-miscmaths=2203.2
   - fsl-topup=2203.5
+  # Workflow dependencies: mrtrix3
+  - mrtrix3=3.0.4
   - pip
   - pip:
     - -r requirements.txt

fmriprep/cli/parser.py

@@ -334,7 +334,16 @@ def _slice_time_ref(value, parser):
         action='store',
         nargs='+',
         default=[],
-        choices=['fieldmaps', 'slicetiming', 'sbref', 't2w', 'flair', 'fmap-jacobian'],
+        choices=[
+            'fieldmaps',
+            'slicetiming',
+            'sbref',
+            't2w',
+            'flair',
+            'fmap-jacobian',
+            'phase',
+            'norf',
+        ],
         help='Ignore selected aspects of the input dataset to disable corresponding '
         'parts of the workflow (a space delimited list)',
     )
@@ -444,6 +453,14 @@ def _slice_time_ref(value, parser):
             'It is faster and less memory intensive, but may be less accurate.'
         ),
     )
+    g_conf.add_argument(
+        '--thermal-denoise-method',
+        action='store',
+        dest='thermal_denoise_method',
+        default=None,
+        choices=['mppca'],
+        help='Apply MP-PCA denoising to the BOLD data to remove thermal noise',
+    )
 
     g_outputs = parser.add_argument_group('Options for modulating outputs')
     g_outputs.add_argument(

fmriprep/config.py

@@ -623,6 +623,8 @@ class workflow(_Config):
     in the absence of any alternatives."""
     me_t2s_fit_method = 'curvefit'
     """The method by which to estimate T2*/S0 for multi-echo data"""
+    thermal_denoise_method = None
+    """Apply NORDIC or MP-PCA denoising to the BOLD data to remove thermal noise."""
 
 
 class loggers:

fmriprep/data/boilerplate.bib

@@ -365,3 +365,52 @@ @article{patriat_improved_2017
     keywords = {Motion, Correction, Methods, Rs-fMRI},
     pages = {74--82},
 }
+
+@article{cordero2019complex,
+  title={Complex diffusion-weighted image estimation via matrix recovery under general noise models},
+  author={Cordero-Grande, Lucilio and Christiaens, Daan and Hutter, Jana and Price, Anthony N and Hajnal, Jo V},
+  journal={Neuroimage},
+  volume={200},
+  pages={391--404},
+  year={2019},
+  publisher={Elsevier},
+  url={https://doi.org/10.1016/j.neuroimage.2019.06.039},
+  doi={10.1016/j.neuroimage.2019.06.039}
+}
+
+@article{tournier2019mrtrix3,
+  title={MRtrix3: A fast, flexible and open software framework for medical image processing and visualisation},
+  author={Tournier, J-Donald and Smith, Robert and Raffelt, David and Tabbara, Rami and Dhollander, Thijs and Pietsch, Maximilian and Christiaens, Daan and Jeurissen, Ben and Yeh, Chun-Hung and Connelly, Alan},
+  journal={Neuroimage},
+  volume={202},
+  pages={116137},
+  year={2019},
+  publisher={Elsevier},
+  url={https://doi.org/10.1016/j.neuroimage.2019.116137},
+  doi={10.1016/j.neuroimage.2019.116137}
+}
+
+@article{vizioli2021lowering,
+  title={Lowering the thermal noise barrier in functional brain mapping with magnetic resonance imaging},
+  author={Vizioli, Luca and Moeller, Steen and Dowdle, Logan and Ak{\c{c}}akaya, Mehmet and De Martino, Federico and Yacoub, Essa and U{\u{g}}urbil, Kamil},
+  journal={Nature communications},
+  volume={12},
+  number={1},
+  pages={5181},
+  year={2021},
+  publisher={Nature Publishing Group UK London},
+  url={https://doi.org/10.1038/s41467-021-25431-8},
+  doi={10.1038/s41467-021-25431-8}
+}
+
+@article{moeller2021noise,
+  title={NOise reduction with DIstribution Corrected (NORDIC) PCA in dMRI with complex-valued parameter-free locally low-rank processing},
+  author={Moeller, Steen and Pisharady, Pramod Kumar and Ramanna, Sudhir and Lenglet, Christophe and Wu, Xiaoping and Dowdle, Logan and Yacoub, Essa and U{\u{g}}urbil, Kamil and Ak{\c{c}}akaya, Mehmet},
+  journal={Neuroimage},
+  volume={226},
+  pages={117539},
+  year={2021},
+  publisher={Elsevier},
+  url={https://doi.org/10.1016/j.neuroimage.2020.117539},
+  doi={10.1016/j.neuroimage.2020.117539}
+}

fmriprep/data/tests/config.toml

@@ -47,6 +47,7 @@ run_reconall = true
 skull_strip_fixed_seed = false
 skull_strip_template = "OASIS30ANTs"
 t2s_coreg = false
+thermal_denoise_method = "mppca"
 use_aroma = false
 
 [nipype]