Merge branch 'main' into sensitivity_map_doc_imp

Author: 1himan

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/changes/dev/13593.other.rst

@@ -0,0 +1 @@
+make :func:`mne.sys_info` work on Windows systems with Powershell version 7+, by `Marijn van Vliet`_

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/io/egi/events.py

@@ -68,7 +68,7 @@ def _read_mff_events(filename, sfreq):
             marker = {
                 "name": event["code"],
                 "start": start,
-                "start_sample": int(np.fix(start * sfreq)),
+                "start_sample": int(np.trunc(start * sfreq)),
                 "end": start + float(event["duration"]) / 1e9,
                 "chan": None,
             }

mne/preprocessing/infomax_.py

@@ -247,7 +247,7 @@ def infomax(
                     oldsigns = signs
 
                     if signcount >= signcount_threshold:
-                        ext_blocks = np.fix(ext_blocks * signcount_step)
+                        ext_blocks = np.trunc(ext_blocks * signcount_step)
                         signcount = 0
 
         # here we continue after the for loop over the ICA training blocks

mne/utils/config.py

@@ -681,11 +681,9 @@ def _get_gpu_info():
 def _get_total_memory():
     """Return the total memory of the system in bytes."""
     if platform.system() == "Windows":
+        ps = shutil.which("pwsh") or shutil.which("powershell")
         o = subprocess.check_output(
-            [
-                "powershell.exe",
-                "(Get-CimInstance Win32_ComputerSystem).TotalPhysicalMemory",
-            ]
+            [ps, "-c", "(Get-CimInstance Win32_ComputerSystem).TotalPhysicalMemory"]
         ).decode()
         # Can get for example a "running scripts is disabled on this system"
         # error where "o" will be a long string rather than an int
@@ -708,8 +706,9 @@ def _get_total_memory():
 def _get_cpu_brand():
     """Return the CPU brand string."""
     if platform.system() == "Windows":
+        ps = shutil.which("pwsh") or shutil.which("powershell")
         o = subprocess.check_output(
-            ["powershell.exe", "(Get-CimInstance Win32_Processor).Name"]
+            [ps, "-c", "(Get-CimInstance Win32_Processor).Name"]
         ).decode()
         cpu_brand = o.strip().splitlines()[-1]
     elif platform.system() == "Linux":

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

mne/viz/utils.py

@@ -1926,7 +1926,7 @@ def _setup_ax_spines(
 
         def log_fix(tval):
             exp = np.log10(np.abs(tval))
-            return np.sign(tval) * 10 ** (np.fix(exp) - (exp < 0))
+            return np.sign(tval) * 10 ** (np.trunc(exp) - (exp < 0))
 
         xlims = np.array([xmin, xmax])
         temp_ticks = log_fix(xlims)

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