Add more information to eSSS in examples and docsstring (#13591)

Co-authored-by: Eric Larson <[email protected]>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: 3 people

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`_.

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},

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
 """

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