ENH: Add eSSS (#762)

docs/source/settings/preprocessing/maxfilter.md

@@ -17,6 +17,8 @@ tags:
         - mf_reference_run
         - mf_cal_fname
         - mf_ctc_fname
+        - mf_esss
+        - mf_esss_reject
         - mf_mc
         - mf_mc_t_step_min
         - mf_mc_t_window

docs/source/v1.5.md.inc

@@ -4,6 +4,7 @@
 
 - Added support for annotating bad segments based on head movement velocity (#757 by @larsoner)
 - Added examples of T1 and FLASH BEM to website (#758 by @larsoner)
+- Added support for extended SSS (eSSS) in Maxwell filtering (#762 by @larsoner)
 - Output logging spacing improved (#764 by @larsoner)
 
 [//]: # (### :warning: Behavior changes)

mne_bids_pipeline/_config.py

@@ -681,6 +681,16 @@
     ```
 """  # noqa : E501
 
+mf_esss: int = 0
+"""
+Number of extended SSS (eSSS) basis projectors to use from empty-room data.
+"""
+
+mf_esss_reject: Optional[Dict[str, float]] = None
+"""
+Rejection parameters to use when computing the extended SSS (eSSS) basis.
+"""
+
 mf_mc: bool = False
 """
 If True, perform movement compensation on the data.

mne_bids_pipeline/_config_utils.py

@@ -615,3 +615,10 @@ def _bids_kwargs(*, config: SimpleNamespace) -> dict:
 
 def _do_mf_autobad(*, cfg: SimpleNamespace) -> bool:
     return cfg.find_noisy_channels_meg or cfg.find_flat_channels_meg
+
+
+# Adapted from MNE-Python
+def _pl(x, *, non_pl="", pl="s"):
+    """Determine if plural should be used."""
+    len_x = x if isinstance(x, (int, np.generic)) else len(x)
+    return non_pl if len_x == 1 else pl

mne_bids_pipeline/_import_data.py

@@ -2,7 +2,6 @@
 from typing import Dict, Optional, Iterable, Union, List, Literal
 
 import mne
-from mne.utils import _pl
 from mne_bids import BIDSPath, read_raw_bids, get_bids_path_from_fname
 import numpy as np
 import pandas as pd
@@ -14,6 +13,7 @@
     get_task,
     _bids_kwargs,
     _do_mf_autobad,
+    _pl,
 )
 from ._io import _read_json, _empty_room_match_path
 from ._logging import gen_log_kwargs, logger

mne_bids_pipeline/_run.py

@@ -220,7 +220,9 @@ def wrapper(*args, **kwargs):
                     emoji = "🔂"
                 else:
                     # Check our output file hashes
-                    out_files_hashes = memorized_func(*args, **kwargs)
+                    # Need to make a copy of kwargs["in_files"] in particular
+                    use_kwargs = copy.deepcopy(kwargs)
+                    out_files_hashes = memorized_func(*args, **use_kwargs)
                     for key, (fname, this_hash) in out_files_hashes.items():
                         fname = pathlib.Path(fname)
                         if not fname.exists():
@@ -302,8 +304,8 @@ def save_logs(*, config: SimpleNamespace, logs) -> None:  # TODO add type
 
 
 def _update_for_splits(
-    files_dict: Dict[str, BIDSPath],
-    key: str,
+    files_dict: Union[Dict[str, BIDSPath], BIDSPath],
+    key: Optional[str],
     *,
     single: bool = False,
     allow_missing: bool = False,

mne_bids_pipeline/steps/init/_02_find_empty_room.py

@@ -3,7 +3,6 @@
 from types import SimpleNamespace
 from typing import Dict, Optional
 
-from mne.utils import _pl
 from mne_bids import BIDSPath
 
 from ..._config_utils import (
@@ -12,6 +11,7 @@
     get_subjects,
     get_mf_reference_run,
     _bids_kwargs,
+    _pl,
 )
 from ..._io import _empty_room_match_path, _write_json
 from ..._logging import gen_log_kwargs, logger

mne_bids_pipeline/steps/preprocessing/_01_data_quality.py

@@ -6,7 +6,6 @@
 import pandas as pd
 
 import mne
-from mne.utils import _pl
 from mne_bids import BIDSPath
 
 from ..._config_utils import (
@@ -16,6 +15,7 @@
     get_sessions,
     get_runs_tasks,
     _do_mf_autobad,
+    _pl,
 )
 from ..._import_data import (
     _get_run_rest_noise_path,