Repository: mne-tools/mne-python

Issue:
FIX/API: deprecate ICA.detect_artifacts 
In response to the recent [forum discussion](https://mne.discourse.group/t/cant-obtain-graph-when-using-detect-artifacts/3862/5) I would suggest to deprecate that ICA method.

cc @cbrnr @agramfort @hoechenberger 


Discussion:
alternative: re-inject some love and re-imagine this as a method to run the entire ICA workflow ... (love needed). anyways that won't work without deprecating a lot.
I'd say we deprecate it and after 0.24 has been released, we take a few minutes and see if there's any remaining functionality worth keeping, and reconvene :)

Resolving patch:
diff --git a/mne/preprocessing/ica.py b/mne/preprocessing/ica.py
--- a/mne/preprocessing/ica.py
+++ b/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,


Test patch:
diff --git a/mne/preprocessing/tests/test_ica.py b/mne/preprocessing/tests/test_ica.py
--- a/mne/preprocessing/tests/test_ica.py
+++ b/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
diff --git a/mne/utils/tests/test_docs.py b/mne/utils/tests/test_docs.py
--- a/mne/utils/tests/test_docs.py
+++ b/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():