[ENH] add warning message to illogical parameter combination passed t…

…o `signal.clean` (#3003)

* ENH add warning message to illogical inputs

when standardize_confounds=False, detrend=False, raise warning
and remind users to either apply the option or demean the signal

* Update what's new entry

* LINT Typo and unused variable removed

* Apply suggestions from code review

Co-authored-by: Gensollen <nicolas.gensollen@gmail.com>

Co-authored-by: Gensollen <nicolas.gensollen@gmail.com>

doc/whats_new.rst

@@ -18,6 +18,12 @@ Enhancements
   When `two_sided` is `False`, only values greater than or equal to the threshold
   are retained.
 
+- :func:`nilearn.signal.clean` raises a warning when the user sets 
+  parameters `detrend` and `standardize_confound` to False.
+  The user is suggested to set one of
+  those options to `True`, or standardize/demean the confounds before using the 
+  function.
+
 Changes
 -------
 

nilearn/signal.py

@@ -529,6 +529,10 @@ def clean(signals, runs=None, detrend=True, standardize='zscore',
     --------
         nilearn.image.clean_img
     """
+    # Raise warning for some parameter combinations when confounds present
+    if confounds is not None:
+        _check_signal_parameters(detrend, standardize_confounds)
+
     # Read confounds and signals
     signals, runs, confounds = _sanitize_inputs(
         signals, runs, confounds, sample_mask, ensure_finite
@@ -824,3 +828,15 @@ def _sanitize_signals(signals, ensure_finite):
         if mask.any():
             signals[mask] = 0
     return _ensure_float(signals)
+
+
+def _check_signal_parameters(detrend, standardize_confounds):
+    """Raise warning if the combination is illogical"""
+    if not detrend and not standardize_confounds:
+        warnings.warn("When confounds are provided, one must perform detrend "
+                      "and/or standarize confounds. You provided detrend={0}, "
+                      "standardize_confounds={1}. If confounds were not "
+                      "standardized or demeaned before passing to signal.clean"
+                      " signal will not be correctly cleaned. ".format(
+                          detrend, standardize_confounds)
+                      )

nilearn/tests/test_signal.py

@@ -505,13 +505,17 @@ def test_clean_confounds():
 
     # Test without standardizing that constant parts of confounds are
     # accounted for
-    np.testing.assert_almost_equal(nisignal.clean(np.ones((20, 2)),
-                                                  standardize=False,
-                                                  confounds=np.ones(20),
-                                                  standardize_confounds=False,
-                                                  detrend=False,
-                                                  ).mean(),
-                                   np.zeros((20, 2)))
+    # passing standardize_confounds=False, detrend=False should raise warning
+    warning_message = r"must perform detrend and/or standarize confounds"
+    with pytest.warns(UserWarning, match=warning_message):
+        np.testing.assert_almost_equal(
+            nisignal.clean(np.ones((20, 2)),
+                           standardize=False,
+                           confounds=np.ones(20),
+                           standardize_confounds=False,
+                           detrend=False,
+                           ).mean(),
+            np.zeros((20, 2)))
 
     # Test to check that confounders effects are effectively removed from
     # the signals when having a detrending and filtering operation together.