diff --git a/doc/changes/dev/13591.other.rst b/doc/changes/dev/13591.other.rst new file mode 100644 index 00000000000..20831356a0a --- /dev/null +++ b/doc/changes/dev/13591.other.rst @@ -0,0 +1 @@ +Documentation improvement for eSSS in docstring :func:`mne.preprocessing.maxwell_filter` and in the MaxFilter example by `Simon Kern`_. diff --git a/doc/references.bib b/doc/references.bib index 3b7ddf6dc04..12d63458bd1 100644 --- a/doc/references.bib +++ b/doc/references.bib @@ -813,6 +813,17 @@ @book{Heiman2002 year = {2002} } +@ARTICLE{HelleEtAl2021, + author={Helle, Liisa and Nenonen, Jukka and Larson, Eric and Simola, Juha and Parkkonen, Lauri and Taulu, Samu}, + journal={IEEE Transactions on Biomedical Engineering}, + title={Extended Signal-Space Separation Method for Improved Interference Suppression in MEG}, + year={2021}, + volume={68}, + number={7}, + pages={2211-2221}, + doi={10.1109/TBME.2020.3040373} +} + @article{HippEtAl2011, author = {Hipp, Joerg F. and Engel, Andreas K. and Siegel, Markus}, doi = {10.1016/j.neuron.2010.12.027}, diff --git a/mne/utils/docs.py b/mne/utils/docs.py index fe1bc00d5ef..2adb6d12375 100644 --- a/mne/utils/docs.py +++ b/mne/utils/docs.py @@ -1559,7 +1559,14 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75): docdict["extended_proj_maxwell"] = """ extended_proj : list The empty-room projection vectors used to extend the external - SSS basis (i.e., use eSSS). + SSS basis (i.e., use eSSS). You can use any SSP projections that contain + pure *external* noise that you expect to be present in your signal. + Typically, this should be the case during an empty room recording. Get the + projections e.g. by calling:: + + proj = mne.compute_proj_raw( + raw_empty_room.pick('meg'), n_grad=3, n_mag=3, meg="combined" + ) .. versionadded:: 0.21 """ diff --git a/tutorials/preprocessing/60_maxwell_filtering_sss.py b/tutorials/preprocessing/60_maxwell_filtering_sss.py index 73c0bd5a73f..70d18dcde6a 100644 --- a/tutorials/preprocessing/60_maxwell_filtering_sss.py +++ b/tutorials/preprocessing/60_maxwell_filtering_sss.py @@ -307,6 +307,36 @@ # :func:`~mne.preprocessing.maxwell_filter` for details. # # +# Extended SSS (eSSS) +# ^^^^^^^^^^^^^^^^^^^ +# +# Extended SSS (eSSS) is a variant of SSS that improves suppression of external +# interference especially, when the “ideal” external model is not perfect +# (e.g., because of small calibration/geometry errors). It does this by +# extending the *external* part of the SSS model with interference patterns +# learned from a separate empty-room recording :footcite:`HelleEtAl2021`. +# +# Practical notes: +# +# - Keep the number of added components small (the ~8 in the original paper); +# adding too many can worsen numerical conditioning and increase noise. +# - Prefer empty-room data from the same session/environment. +# - eSSS can be combined with tSSS (“teSSS”, i.e. setting ``st_duration=X``). +# - You can get projections from an empty room recording via +# :func:`mne.compute_proj_raw` like:: +# +# proj = mne.compute_proj_raw( +# noise_raw, n_grad=3, n_mag=3, n_eeg=0, meg="combined", +# ) +# +# You can enable eSSS by setting ``extended_proj=proj`` in +# :func:`~mne.preprocessing.maxwell_filter`. +# +# An external example using spatiotemporal extended SSS (teSSS) with movement +# compensation can be found at +# `github.com/ilabsbrainteam/2022-Best-Practices-Infant-MEG`_. +# +# # Movement compensation # ^^^^^^^^^^^^^^^^^^^^^ # @@ -379,3 +409,4 @@ # .. LINKS # # .. _spherical harmonics: https://en.wikipedia.org/wiki/Spherical_harmonics +# .. _github.com/ilabsbrainteam/2022-Best-Practices-Infant-MEG: https://github.com/ilabsbrainteam/2022-Best-Practices-Infant-MEG/blob/c62019b4d37a20f0c82420b73595ea241b892a17/pipeline.py#L119-L147