Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

ENH: Add MP-PCA/NORDIC denoising through dwidenoise #3395

Draft
wants to merge 21 commits into
base: master
Choose a base branch
from
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .circleci/config.yml
Original file line number Diff line number Diff line change
Expand Up @@ -755,6 +755,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:
Expand Down
26 changes: 26 additions & 0 deletions docs/workflows.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 3 additions & 0 deletions env.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -37,6 +38,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
Expand Down
19 changes: 18 additions & 1 deletion fmriprep/cli/parser.py
Original file line number Diff line number Diff line change
Expand Up @@ -337,7 +337,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)',
)
Expand Down Expand Up @@ -447,6 +456,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(
Expand Down
2 changes: 2 additions & 0 deletions fmriprep/config.py
Original file line number Diff line number Diff line change
Expand Up @@ -624,6 +624,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:
Expand Down
49 changes: 49 additions & 0 deletions fmriprep/data/boilerplate.bib
Original file line number Diff line number Diff line change
Expand Up @@ -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}
}
1 change: 1 addition & 0 deletions fmriprep/data/tests/config.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down
Loading
Loading