MRG: Deprecate ICA.detect_artifacts (#9909)

* Deprecate ICA.detect_artifacts

Fixes #9906

* FIX: Revert extra warning

Co-authored-by: Eric Larson <[email protected]>

doc/changes/latest.inc

@@ -325,7 +325,7 @@ API changes
 
 - :func:`mne.inverse_sparse.mixed_norm` now simply warns when source estimates contain no dipole, e.g. if data are too noisy and alpha is based on SURE (:gh:`9685` by `Alex Gramfort`_)
 
-- deprecate functions :samp:`mne.datasets.{DATASET_NAME}.has_{DATASET_NAME}_data()` for these datasets: ``epilepsy_ecog``, ``fnirs_motor``, ``multimodal``, ``opm``, ``phantom_4dbti``, ``refmeg_noise``, ``sample``, ``somato``, and ``ssvep``. Use the generic :func:`mne.datasets.has_dataset` instead (:gh:`9781` by `Daniel McCloy`_ and `Adam Li`_)
+- Deprecate functions :samp:`mne.datasets.{DATASET_NAME}.has_{DATASET_NAME}_data()` for these datasets: ``epilepsy_ecog``, ``fnirs_motor``, ``multimodal``, ``opm``, ``phantom_4dbti``, ``refmeg_noise``, ``sample``, ``somato``, and ``ssvep``. Use the generic :func:`mne.datasets.has_dataset` instead (:gh:`9781` by `Daniel McCloy`_ and `Adam Li`_)
 
 - :class:`mne.Report` modernization has led to multiple deprecations (:gh:`9754` by `Richard Höchenberger`_):
 
@@ -352,3 +352,5 @@ API changes
 - Deprecate ``mne.viz.utils.center_cmap`` (:gh:`9851` by `Clemens Brunner`_)
 
 - The default partial pathlength factor of :func:`mne.preprocessing.nirs.beer_lambert_law` will change from 0.1 in 0.24 to 6.0 in the next release (:gh:`9843` by `Robert Luke`_)
+
+- :meth:`mne.preprocessing.ICA.detect_artifacts` has been deprecated. Please use `~mne.preprocessing.ICA.find_bads_eog` and `~mne.preprocessing.ICA.find_bads_ecg` instead (:gh:`9909` by `Richard Höchenberger`_)

mne/preprocessing/ica.py

@@ -55,7 +55,7 @@
                      copy_function_doc_to_method_doc, _pl, warn, Bunch,
                      _check_preload, _check_compensation_grade, fill_doc,
                      _check_option, _PCA, int_like,
-                     _check_all_same_channel_names)
+                     _check_all_same_channel_names, deprecated)
 
 from ..fixes import _get_args, _safe_svd
 from ..filter import filter_data
@@ -1978,6 +1978,7 @@ def plot_overlay(self, inst, exclude=None, picks=None, start=None,
                                 start=start, stop=stop, title=title, show=show,
                                 n_pca_components=n_pca_components)
 
+    @deprecated(extra='Use ICA.find_bads_eog and ICA.find_bads_ecg instead.')
     def detect_artifacts(self, raw, start_find=None, stop_find=None,
                          ecg_ch=None, ecg_score_func='pearsonr',
                          ecg_criterion=0.1, eog_ch=None,

mne/preprocessing/tests/test_ica.py

@@ -799,18 +799,24 @@ def f(x, y):
     params += [(None, -1, slice(2), [0, 1])]  # variance, kurtosis params
     params += [(None, 'MEG 1531')]  # ECG / EOG channel params
     for idx, ch_name in product(*params):
-        ica.detect_artifacts(raw, start_find=0, stop_find=50, ecg_ch=ch_name,
-                             eog_ch=ch_name, skew_criterion=idx,
-                             var_criterion=idx, kurt_criterion=idx)
+        with pytest.warns(DeprecationWarning, match='detect_artifacts is dep'):
+            ica.detect_artifacts(
+                raw, start_find=0, stop_find=50, ecg_ch=ch_name,
+                eog_ch=ch_name, skew_criterion=idx,
+                var_criterion=idx, kurt_criterion=idx
+            )
 
     # Make sure detect_artifacts marks the right components.
     # For int criterion, the doc says "E.g. range(2) would return the two
     # sources with the highest score". Assert that's what it does.
     # Only test for skew, since it's always the same code.
     ica.exclude = []
-    ica.detect_artifacts(raw, start_find=0, stop_find=50, ecg_ch=None,
-                         eog_ch=None, skew_criterion=0,
-                         var_criterion=None, kurt_criterion=None)
+    with pytest.warns(DeprecationWarning, match='detect_artifacts is depreca'):
+        ica.detect_artifacts(
+            raw, start_find=0, stop_find=50, ecg_ch=None,
+            eog_ch=None, skew_criterion=0,
+            var_criterion=None, kurt_criterion=None
+        )
     assert np.abs(scores[ica.exclude]) == np.max(np.abs(scores))
 
     evoked = epochs.average()
@@ -1018,9 +1024,13 @@ def test_detect_artifacts_replacement_of_run_ica(method, idx, ch_name):
     raw = read_raw_fif(raw_fname).crop(1.5, stop).load_data()
     ica = ICA(n_components=2, method=method)
     ica.fit(raw)
-    ica.detect_artifacts(raw, start_find=0, stop_find=5, ecg_ch=ch_name,
-                         eog_ch=ch_name, skew_criterion=idx,
-                         var_criterion=idx, kurt_criterion=idx)
+
+    with pytest.warns(DeprecationWarning, match='detect_artifacts is depreca'):
+        ica.detect_artifacts(
+            raw, start_find=0, stop_find=5, ecg_ch=ch_name,
+            eog_ch=ch_name, skew_criterion=idx,
+            var_criterion=idx, kurt_criterion=idx
+        )
 
 
 @requires_sklearn

mne/utils/tests/test_docs.py

@@ -28,23 +28,35 @@ def new_func():
     assert 'deprecated' not in new_func.__doc__
 
 
-@deprecated('message')
+@deprecated('bad func')
 def deprecated_func():
     """Do something."""
     pass
 
 
-@deprecated('message')
+@deprecated('bad class')
 class deprecated_class(object):
 
     def __init__(self):
         pass
 
+    @deprecated('bad method')
+    def bad(self):
+        pass
+
 
 def test_deprecated():
     """Test deprecated function."""
-    pytest.deprecated_call(deprecated_func)
-    pytest.deprecated_call(deprecated_class)
+    assert 'DEPRECATED' in deprecated_func.__doc__
+    with pytest.deprecated_call(match='bad func'):
+        deprecated_func()
+    assert 'DEPRECATED' in deprecated_class.__init__.__doc__
+    with pytest.deprecated_call(match='bad class'):
+        dep = deprecated_class()
+    assert 'DEPRECATED' in deprecated_class.bad.__doc__
+    assert 'DEPRECATED' in dep.bad.__doc__
+    with pytest.deprecated_call(match='bad method'):
+        dep.bad()
 
 
 def test_copy_doc():