DOC: Document CSS more completely (mne-tools#12726)

mne/preprocessing/_css.py

@@ -43,12 +43,12 @@ def cortical_signal_suppression(
         gradiometer, and EEG channels.
     %(picks_good_data)s
     mag_picks : array-like of int
-        Array of the magnetometer channel indices that will be used to find
-        the reference data. If None (default), all magnetometers will
+        Array of the first set of channel indices that will be used to find
+        the common temporal subspace. If None (default), all magnetometers will
         be used.
     grad_picks : array-like of int
-        Array of the gradiometer channel indices that will be used to find
-        the reference data. If None (default), all gradiometers will
+        Array of the second set of channel indices that will be used to find
+        the common temporal subspace. If None (default), all gradiometers will
         be used.
     n_proj : int
         The number of projection vectors.
@@ -57,15 +57,19 @@ def cortical_signal_suppression(
     Returns
     -------
     evoked_subcortical : instance of Evoked
-        The evoked object with cortical contributions to the EEG data
-        suppressed.
+        The evoked object with contributions from the ``mag_picks`` and ``grad_picks``
+        channels removed from the ``picks`` channels.
 
     Notes
     -----
-    This method removes the common signal subspace between the magnetometer
-    data and the gradiometer data from the EEG data. This is done by a temporal
-    projection using ``n_proj`` number of projection vectors. For reference,
-    see :footcite:`Samuelsson2019`.
+    This method removes the common signal subspace between two sets of
+    channels (``mag_picks`` and ``grad_picks``) from a set of channels
+    (``picks``) via a temporal projection using ``n_proj`` number of
+    projection vectors. In the reference publication :footcite:`Samuelsson2019`,
+    the joint subspace between magnetometers and gradiometers is used to
+    suppress the cortical signal in the EEG data. In principle, other
+    combinations of sensor types (or channels) could be used to suppress
+    signals from other sources.
 
     References
     ----------

mne/preprocessing/tests/test_css.py

@@ -34,11 +34,13 @@ def test_cortical_signal_suppression():
     ave.data[eeg_ind][1, :] = np.sin(2 * np.pi * 239 * ave.times) * np.mean(
         np.abs(ave.data[eeg_ind][1, :])
     )
-    ave_f = cortical_signal_suppression(ave)
-    cort_power = np.sum(np.abs(ave.data[eeg_ind][0, :]))
-    deep_power = np.sum(np.abs(ave.data[eeg_ind][1, :]))
-    cort_power_f = np.sum(np.abs(ave_f.data[eeg_ind][0, :]))
-    deep_power_f = np.sum(np.abs(ave_f.data[eeg_ind][1, :]))
-    rel_SNR_gain = (deep_power_f / deep_power) / (cort_power_f / cort_power)
-    assert rel_SNR_gain > 0
-    assert ave_f.data.shape == ave.data.shape
+    # include test for gh-12373, that you can use MAG+EEG if you want
+    for mag_picks, ind in ((None, eeg_ind), ("eeg", mag_ind)):
+        ave_f = cortical_signal_suppression(ave, mag_picks=mag_picks)
+        assert ave_f.data.shape == ave.data.shape
+        cort_power = np.linalg.norm(ave.data[ind][0, :])
+        deep_power = np.linalg.norm(ave.data[ind][1, :])
+        cort_power_f = np.linalg.norm(ave_f.data[ind][0, :])
+        deep_power_f = np.linalg.norm(ave_f.data[ind][1, :])
+        rel_SNR_gain = (deep_power_f / deep_power) / (cort_power_f / cort_power)
+        assert rel_SNR_gain > 3, mag_picks