test(dss): harden Evoked covariance kwargs

Author: snesmaeili

mne_denoise/dss/utils/covariance.py

@@ -155,6 +155,8 @@ def compute_evoked_covariance(
     **kwargs
         Additional keyword arguments forwarded to
         :func:`mne.compute_covariance` (e.g. ``rank``, ``verbose``).
+        ``keep_sample_mean`` may be omitted or set to ``True``; ``False`` is
+        invalid because the temporary Epochs object has only one average.
 
     Returns
     -------
@@ -173,6 +175,13 @@ def compute_evoked_covariance(
             "Evoked must have at least 2 time samples to estimate a covariance."
         )
 
+    keep_sample_mean = kwargs.pop("keep_sample_mean", True)
+    if keep_sample_mean is not True:
+        raise ValueError(
+            "keep_sample_mean must be True for an Evoked covariance because "
+            "the temporary Epochs object contains only one averaged response."
+        )
+
     # Wrap the single averaged response as a one-trial Epochs so MNE's
     # covariance machinery applies. ``keep_sample_mean=True`` stops MNE from
     # subtracting the (single) evoked response, which would otherwise zero the

tests/utils/test_covariance.py

@@ -264,6 +264,19 @@ def test_compute_evoked_covariance_raises_on_too_few_samples():
         compute_evoked_covariance(evoked)
 
 
+def test_compute_evoked_covariance_requires_sample_mean():
+    """A one-Evoked wrapper cannot subtract an across-epoch sample mean."""
+    evoked, _ = _make_evoked()
+
+    cov = compute_evoked_covariance(
+        evoked, keep_sample_mean=True, method="empirical", verbose=False
+    )
+    assert isinstance(cov, mne.Covariance)
+
+    with pytest.raises(ValueError, match="keep_sample_mean must be True"):
+        compute_evoked_covariance(evoked, keep_sample_mean=False)
+
+
 def test_compute_evoked_covariance_rejects_non_2d_data():
     """Non-2D evoked data is rejected before reaching MNE."""