From 46c9954f0c24a264541a518c58b12ef4bc29bbf0 Mon Sep 17 00:00:00 2001
From: Daniel McCloy <dan@mccloy.info>
Date: Mon, 18 Mar 2024 15:05:57 -0500
Subject: [PATCH] change zero_mean default (with deprecation cycle)

---
 doc/changes/devel/11282.api.rst                  |  1 +
 .../time_frequency/time_frequency_simulated.py   |  1 +
 mne/epochs.py                                    |  3 +++
 mne/time_frequency/tfr.py                        | 16 ++++++++++++++--
 4 files changed, 19 insertions(+), 2 deletions(-)
 create mode 100644 doc/changes/devel/11282.api.rst

diff --git a/doc/changes/devel/11282.api.rst b/doc/changes/devel/11282.api.rst
new file mode 100644
index 00000000000..9112db897cf
--- /dev/null
+++ b/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`_.
diff --git a/examples/time_frequency/time_frequency_simulated.py b/examples/time_frequency/time_frequency_simulated.py
index de96907190c..ebc877143e1 100644
--- a/examples/time_frequency/time_frequency_simulated.py
+++ b/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)
diff --git a/mne/epochs.py b/mne/epochs.py
index 26a3153a8c0..19282b6883f 100644
--- a/mne/epochs.py
+++ b/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,
diff --git a/mne/time_frequency/tfr.py b/mne/time_frequency/tfr.py
index 7ec90224c8e..600f3b23268 100644
--- a/mne/time_frequency/tfr.py
+++ b/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 "