change default for info to use for inverse #905 (#919)

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

Author: 3 people

docs/source/v1.9.md.inc

@@ -8,6 +8,9 @@
 
 ### :warning: Behavior changes
 
+- Changed default for `source_info_path_update` to `None`.  In `_04_make_forward.py` 
+  and `_05_make_inverse.py`, we retrieve the info from the file from which 
+  the `noise_cov` is computed (#919 by @SophieHerbst)
 - The [`depth`][mne_bids_pipeline._config.depth] parameter doesn't accept `None`
   anymore. Please use `0` instead. (#915 by @hoechenberger)
 

mne_bids_pipeline/_config.py

@@ -2098,22 +2098,35 @@ def noise_cov(bids_path):
 of `mne.compute_covariance` for details.
 """
 
-source_info_path_update: dict[str, str] | None = dict(suffix="ave")
+source_info_path_update: dict[str, str] | None = None
 """
-When computing the forward and inverse solutions, by default the pipeline
-retrieves the `mne.Info` object from the cleaned evoked data. However, in
-certain situations you may wish to use a different `Info`.
-
+When computing the forward and inverse solutions, it is important to
+provide the `mne.Info` object from the data on which the noise covariance was
+computed, to avoid problems resulting from mismatching ranks.
 This parameter allows you to explicitly specify from which file to retrieve the
 `mne.Info` object. Use this parameter to supply a dictionary to
 `BIDSPath.update()` during the forward and inverse processing steps.
+If set to `None` (default), the info will be retrieved either from the raw
+file specified in `noise_cov`, or the cleaned evoked
+(if `noise_cov` is None or `ad-hoc`).
 
 ???+ example "Example"
     Use the `Info` object stored in the cleaned epochs:
     ```python
     source_info_path_update = {'processing': 'clean',
                                'suffix': 'epo'}
     ```
+
+    Use the `Info` object stored in a raw file (e.g. resting state):
+    ```python
+    source_info_path_update = {'processing': 'clean',
+                                'suffix': 'raw',
+                                'task': 'rest'}
+    ```
+    If you set `noise_cov = 'rest'` and `source_path_info = None`,
+    then the behavior is identical to that above
+    (it will automatically use the resting state data).
+
 """
 
 inverse_targets: list[Literal["evoked"]] = ["evoked"]

mne_bids_pipeline/_config_import.py

@@ -344,7 +344,6 @@ def _default_factory(key, val):
     allowlist = [
         {"n_mag": 1, "n_grad": 1, "n_eeg": 1},  # n_proj_*
         {"custom": (8, 24.0, 40)},  # decoding_csp_freqs
-        {"suffix": "ave"},  # source_info_path_update
         ["evoked"],  # inverse_targets
         [4, 8, 16],  # autoreject_n_interpolate
     ]

mne_bids_pipeline/steps/source/_04_make_forward.py

@@ -23,7 +23,7 @@
 from ..._logging import gen_log_kwargs, logger
 from ..._parallel import get_parallel_backend, parallel_func
 from ..._report import _open_report, _render_bem
-from ..._run import _prep_out_files, failsafe_run, save_logs
+from ..._run import _prep_out_files, _sanitize_callable, failsafe_run, save_logs
 
 
 def _prepare_trans_template(
@@ -102,7 +102,18 @@ def get_input_fnames_forward(*, cfg, subject, session):
         check=False,
     )
     in_files = dict()
-    in_files["info"] = bids_path.copy().update(**cfg.source_info_path_update)
+    # for consistency with 05_make_inverse, read the info from the
+    # data used for the noise_cov
+    if cfg.source_info_path_update is None:
+        if cfg.noise_cov in ("rest", "noise"):
+            source_info_path_update = dict(
+                processing="clean", suffix="raw", task=cfg.noise_cov
+            )
+        else:
+            source_info_path_update = dict(suffix="ave")
+    else:
+        source_info_path_update = cfg.source_info_path_update
+    in_files["info"] = bids_path.copy().update(**source_info_path_update)
     bem_path = cfg.fs_subjects_dir / cfg.fs_subject / "bem"
     _, tag = _get_bem_conductivity(cfg)
     in_files["bem"] = bem_path / f"{cfg.fs_subject}-{tag}-bem-sol.fif"
@@ -242,6 +253,7 @@ def get_config(
         use_template_mri=config.use_template_mri,
         adjust_coreg=config.adjust_coreg,
         source_info_path_update=config.source_info_path_update,
+        noise_cov=_sanitize_callable(config.noise_cov),
         ch_types=config.ch_types,
         fs_subject=get_fs_subject(config=config, subject=subject),
         fs_subjects_dir=get_fs_subjects_dir(config),

mne_bids_pipeline/steps/source/_05_make_inverse.py

@@ -48,7 +48,19 @@ def get_input_fnames_inverse(
         check=False,
     )
     in_files = dict()
-    in_files["info"] = bids_path.copy().update(**cfg.source_info_path_update)
+    # make sure the info matches the data from which the noise cov
+    # is computed to avoid rank-mismatch
+    if cfg.source_info_path_update is None:
+        if cfg.noise_cov in ("rest", "noise"):
+            source_info_path_update = dict(
+                processing="clean", suffix="raw", task=cfg.noise_cov
+            )
+        else:
+            source_info_path_update = dict(suffix="ave")
+            # XXX is this the right solution also for noise_cov = 'ad-hoc'?
+    else:
+        source_info_path_update = cfg.source_info_path_update
+    in_files["info"] = bids_path.copy().update(**source_info_path_update)
     in_files["forward"] = bids_path.copy().update(suffix="fwd")
     if cfg.noise_cov != "ad-hoc":
         in_files["cov"] = get_noise_cov_bids_path(