change zero_mean default (with deprecation cycle)

doc/changes/devel/11282.api.rst

@@ -0,0 +1 @@
+The default value of the ``zero_mean`` parameter of :func:`mne.time_frequency.tfr_array_morlet` will change from ``False`` to ``True`` in version 1.8, for consistency with related functions. By `Daniel McCloy`_.

examples/time_frequency/time_frequency_simulated.py

@@ -264,6 +264,7 @@
     freqs=freqs,
     n_cycles=n_cycles,
     output="avg_power",
+    zero_mean=False,
 )
 # Baseline the output
 rescale(power, epochs.times, (0.0, 0.1), mode="mean", copy=False)

mne/epochs.py

@@ -2655,6 +2655,9 @@ def compute_tfr(
                 _check_option(
                     "freqs", np.array(freqs).shape, ((2,),), extra=" (wrong shape)."
                 )
+        # preserve backcompat with `tfr_morlet()` function
+        if method == "morlet":
+            method_kw.setdefault("zero_mean", True)
         if average:
             out = AverageTFR(
                 inst=self,

mne/time_frequency/tfr.py

@@ -941,7 +941,7 @@ def tfr_array_morlet(
     sfreq,
     freqs,
     n_cycles=7.0,
-    zero_mean=False,
+    zero_mean=None,
     use_fft=True,
     decim=1,
     output="complex",
@@ -962,8 +962,13 @@ def tfr_array_morlet(
         Sampling frequency of the data.
     %(freqs_tfr_array)s
     %(n_cycles_tfr)s
-    zero_mean : bool
+    zero_mean : bool | None
         If True, make sure the wavelets have a mean of zero. default False.
+
+        .. versionchanged:: 1.8
+            The default will change from ``zero_mean=False`` in 1.6 to ``True`` in
+            1.8, and (if not set explicitly) will raise a ``FutureWarning`` in 1.7.
+
     use_fft : bool
         Use the FFT for convolutions or not. default True.
     %(decim_tfr)s
@@ -1018,6 +1023,13 @@ def tfr_array_morlet(
     ----------
     .. footbibliography::
     """
+    if zero_mean is None:
+        warn(
+            "The default value of `zero_mean` will change from `False` to `True` "
+            "in version 1.8. Set the value explicitly to avoid this warning.",
+            FutureWarning,
+        )
+        zero_mean = False
     if epoch_data is not None:
         warn(
             "The parameter for providing data will be switched from `epoch_data` to "