Switch from epoch_data to data for TFR array functions (#12308)

mne-tools · Dec 19, 2023 · 4742914 · 4742914
1 parent f1a8120
commit 4742914
Show file tree

Hide file tree

Showing 3 changed files with 33 additions and 9 deletions.
diff --git a/doc/changes/devel.rst b/doc/changes/devel.rst
@@ -52,4 +52,4 @@ Bugs
 
 API changes
 ~~~~~~~~~~~
-- None yet
+- The parameter for providing data to :func:`mne.time_frequency.tfr_array_morlet` and :func:`mne.time_frequency.tfr_array_multitaper` has been switched from ``epoch_data`` to ``data``. Only use the ``data`` parameter to avoid a warning (:gh:`12308` by `Thomas Binns`_)
diff --git a/mne/time_frequency/multitaper.py b/mne/time_frequency/multitaper.py
@@ -465,7 +465,7 @@ def psd_array_multitaper(
 
 @verbose
 def tfr_array_multitaper(
-    epoch_data,
+    data,
     sfreq,
     freqs,
     n_cycles=7.0,
@@ -477,6 +477,7 @@ def tfr_array_multitaper(
     n_jobs=None,
     *,
     verbose=None,
+    epoch_data=None,
 ):
     """Compute Time-Frequency Representation (TFR) using DPSS tapers.
 
@@ -486,7 +487,7 @@ def tfr_array_multitaper(
 
     Parameters
     ----------
-    epoch_data : array of shape (n_epochs, n_channels, n_times)
+    data : array of shape (n_epochs, n_channels, n_times)
         The epochs.
     sfreq : float
         Sampling frequency of the data in Hz.
@@ -509,11 +510,15 @@ def tfr_array_multitaper(
           coherence across trials.
     %(n_jobs)s
     %(verbose)s
+    epoch_data : None
+        Deprecated parameter for providing epoched data as of 1.7, will be replaced with
+        the ``data`` parameter in 1.8. New code should use the ``data`` parameter. If
+        ``epoch_data`` is not ``None``, a warning will be raised.
 
     Returns
     -------
     out : array
-        Time frequency transform of ``epoch_data``.
+        Time frequency transform of ``data``.
 
         - if ``output in ('complex',' 'phase')``, array of shape
           ``(n_epochs, n_chans, n_tapers, n_freqs, n_times)``
@@ -543,8 +548,15 @@ def tfr_array_multitaper(
     """
     from .tfr import _compute_tfr
 
+    if epoch_data is not None:
+        warn(
+            "The parameter for providing data will be switched from `epoch_data` to "
+            "`data` in 1.8. Use the `data` parameter to avoid this warning.",
+            FutureWarning,
+        )
+
     return _compute_tfr(
-        epoch_data,
+        data,
         freqs,
         sfreq=sfreq,
         method="multitaper",

diff --git a/mne/time_frequency/tfr.py b/mne/time_frequency/tfr.py
@@ -973,7 +973,7 @@ def tfr_morlet(
 
 @verbose
 def tfr_array_morlet(
-    epoch_data,
+    data,
     sfreq,
     freqs,
     n_cycles=7.0,
@@ -983,6 +983,7 @@ def tfr_array_morlet(
     output="complex",
     n_jobs=None,
     verbose=None,
+    epoch_data=None,
 ):
     """Compute Time-Frequency Representation (TFR) using Morlet wavelets.
 
@@ -991,7 +992,7 @@ def tfr_array_morlet(
 
     Parameters
     ----------
-    epoch_data : array of shape (n_epochs, n_channels, n_times)
+    data : array of shape (n_epochs, n_channels, n_times)
         The epochs.
     sfreq : float | int
         Sampling frequency of the data.
@@ -1015,11 +1016,15 @@ def tfr_array_morlet(
         The number of epochs to process at the same time. The parallelization
         is implemented across channels. Default 1.
     %(verbose)s
+    epoch_data : None
+        Deprecated parameter for providing epoched data as of 1.7, will be replaced with
+        the ``data`` parameter in 1.8. New code should use the ``data`` parameter. If
+        ``epoch_data`` is not ``None``, a warning will be raised.
 
     Returns
     -------
     out : array
-        Time frequency transform of epoch_data.
+        Time frequency transform of ``data``.
 
         - if ``output in ('complex', 'phase', 'power')``, array of shape
           ``(n_epochs, n_chans, n_freqs, n_times)``
@@ -1049,8 +1054,15 @@ def tfr_array_morlet(
     ----------
     .. footbibliography::
     """
+    if epoch_data is not None:
+        warn(
+            "The parameter for providing data will be switched from `epoch_data` to "
+            "`data` in 1.8. Use the `data` parameter to avoid this warning.",
+            FutureWarning,
+        )
+
     return _compute_tfr(
-        epoch_data=epoch_data,
+        epoch_data=data,
         freqs=freqs,
         sfreq=sfreq,
         method="morlet",