sketch of compute_tfr() API [ci skip]

refactor method_kw checking

cleaner imports

refactor _get_instance_type_string

WIP

many changes; raw.compute_tfr(multitaper, freqs) works!

add verbose to tfr_array_stockwell

add get_data() method

DRY / fixes for method=stockwell

partially handle ITC; comments

WIP [ci skip]

dedup

WIP AverageTFR

WIP sketch of iter_evoked

forgotten (temporary) import

rework evoked fixtures to provide uncropped evoked option

override plot() method for EpochsTFR

add nave to save/load roundtrip

move copy to base class, fix docstrings, work on iter_evoked

work on ITC handling; add ValueErrors for unsupported param combos; cleanup TODOs

move arg gymnastics into EpochsTFR init; get iter_evoked working

get TFR.average() working

working on making stockwell/ITC behave sanely

reorg for saner class behavior [ci skip]

cleanup/move util funcs

make plotting work for singleton EpochsTFR

docstring fixes; support comments for AverageTFR

fix stockwell bugs [ci skip]

fix attributes, fix docstring format, don't store method_kw in an attribute [ci skip]

fix import nesting

add forgotten utils file

add arithmetic methods [ci skip]

fix check_option for stockwell

get baseline and crop working

add loader func; allow both h5 and hdf5 extensions

get plot_topomap working [ci skip]

mne/conftest.py

@@ -401,22 +401,31 @@ def epochs_empty():
 
 
 @pytest.fixture(scope="session", params=[testing._pytest_param()])
-def _evoked():
-    # This one is session scoped, so be sure not to modify it (use evoked
-    # instead)
-    evoked = mne.read_evokeds(
-        fname_evoked, condition="Left Auditory", baseline=(None, 0)
-    )
-    evoked.crop(0, 0.2)
-    return evoked
+def _full_evoked():
+    # This is session scoped, so be sure not to modify its return value (use
+    # `full_evoked` fixture instead)
+    return mne.read_evokeds(fname_evoked, condition="Left Auditory", baseline=(None, 0))
+
+
+@pytest.fixture(scope="session", params=[testing._pytest_param()])
+def _evoked(_full_evoked):
+    # This is session scoped, so be sure not to modify its return value (use `evoked`
+    # fixture instead)
+    return _full_evoked.copy().crop(0, 0.2)
 
 
 @pytest.fixture()
 def evoked(_evoked):
-    """Get evoked data."""
+    """Get truncated evoked data."""
     return _evoked.copy()
 
 
+@pytest.fixture()
+def full_evoked(_full_evoked):
+    """Get full-duration evoked data (needed for, e.g., testing TFR)."""
+    return _full_evoked.copy()
+
+
 @pytest.fixture(scope="function", params=[testing._pytest_param()])
 def noise_cov():
     """Get a noise cov from the testing dataset."""

mne/epochs.py

@@ -73,6 +73,8 @@
 from .fixes import rng_uniform
 from .html_templates import _get_html_template
 from .parallel import parallel_func
+from .time_frequency._utils import _ensure_output_not_in_method_kw
+from .time_frequency.spectrogram import AverageTFR, EpochsTFR
 from .time_frequency.spectrum import EpochsSpectrum, SpectrumMixin, _validate_method
 from .utils import (
     ExtendedTimeMixin,
@@ -2503,6 +2505,122 @@ def compute_psd(
             **method_kw,
         )
 
+    @verbose
+    def compute_tfr(
+        self,
+        method,
+        freqs,
+        *,
+        tmin=None,
+        tmax=None,
+        picks=None,
+        proj=False,
+        average="auto",
+        return_itc=False,
+        decim=1,
+        n_jobs=None,
+        verbose=None,
+        **method_kw,
+    ):
+        """Compute a time-frequency representation of epoched data.
+
+        Parameters
+        ----------
+        %(method_tfr_epochs)s
+        %(freqs_tfr)s
+        %(tmin_tmax_psd)s
+        %(picks_good_data_noref)s
+        %(proj_psd)s
+        average : bool | "auto"
+            Whether to return average power across epochs (instead of single-trial
+            power). Default is "auto" which means ``True`` if method="stockwell" and
+            ``False`` otherwise.
+        return_itc : bool
+            Whether to return inter-trial coherence (ITC) as well as power estimates.
+            Default is ``False``.
+        %(decim_tfr)s
+        %(n_jobs)s
+        %(verbose)s
+        %(method_kw_tfr)s
+
+        Returns
+        -------
+        tfr : instance of EpochsTFR or AverageTFR
+            The time-frequency-resolved power estimates.
+        itc : instance of AverageTFR
+            The inter-trial coherence (ITC). Only returned if ``return_itc=True``.
+
+        Notes
+        -----
+        .. versionadded:: 1.6
+
+        References
+        ----------
+        .. footbibliography::
+        """
+        # construct `output` value from `average` and `return_itc`
+        _ensure_output_not_in_method_kw(self, method_kw)
+        method_kw["output"] = "power"
+        if average == "auto":  # stockwell method *must* average
+            average = method == "stockwell"
+        if average:
+            method_kw["output"] = "avg_power_itc" if return_itc else "avg_power"
+        else:
+            msg = (
+                "compute_tfr() got incompatible parameters `average=False` and `{}` "
+                "({} requires averaging over epochs)."
+            )
+            if return_itc:
+                raise ValueError(msg.format("return_itc=True", "computing ITC"))
+            if method == "stockwell":
+                raise ValueError(msg.format('method="stockwell"', "Stockwell method"))
+        if method == "stockwell":
+            method_kw["return_itc"] = return_itc
+            method_kw.pop("output")
+            if isinstance(freqs, str):
+                _check_option("freqs", freqs, "auto")
+            else:
+                _validate_type(freqs, "array-like")
+                _check_option("freqs", np.array(freqs).shape, ((2,),))
+        if average:
+            out = AverageTFR(
+                self,
+                method=method,
+                freqs=freqs,
+                tmin=tmin,
+                tmax=tmax,
+                picks=picks,
+                proj=proj,
+                decim=decim,
+                n_jobs=n_jobs,
+                verbose=verbose,
+                **method_kw,
+            )
+            # tfr_array_stockwell always returns ITC (but sometimes it's None)
+            if hasattr(out, "_itc"):
+                if out._itc is not None:
+                    state = out.__getstate__()
+                    state["data"] = out._itc
+                    state["data_type"] = "Inter-trial coherence"
+                    itc = AverageTFR(state, method=None, freqs=None)
+                    return out, itc
+                del out._itc  # if it's None, don't keep it around
+            return out
+        # now handle average=False
+        return EpochsTFR(
+            self,
+            method=method,
+            freqs=freqs,
+            tmin=tmin,
+            tmax=tmax,
+            picks=picks,
+            proj=proj,
+            decim=decim,
+            n_jobs=n_jobs,
+            verbose=verbose,
+            **method_kw,
+        )
+
     @verbose
     def plot_psd(
         self,

mne/evoked.py

@@ -46,6 +46,8 @@
 from .filter import FilterMixin, _check_fun, detrend
 from .html_templates import _get_html_template
 from .parallel import parallel_func
+from .time_frequency._utils import _ensure_output_not_in_method_kw
+from .time_frequency.spectrogram import AverageTFR
 from .time_frequency.spectrum import Spectrum, SpectrumMixin, _validate_method
 from .utils import (
     ExtendedTimeMixin,
@@ -1107,6 +1109,63 @@ def compute_psd(
             **method_kw,
         )
 
+    @verbose
+    def compute_tfr(
+        self,
+        method,
+        freqs,
+        *,
+        tmin=None,
+        tmax=None,
+        picks=None,
+        proj=False,
+        decim=1,
+        n_jobs=None,
+        verbose=None,
+        **method_kw,
+    ):
+        """Compute a time-frequency representation of evoked data.
+
+        Parameters
+        ----------
+        %(method_tfr)s
+        %(freqs_tfr)s
+        %(tmin_tmax_psd)s
+        %(picks_good_data_noref)s
+        %(proj_psd)s
+        %(decim_tfr)s
+        %(n_jobs)s
+        %(verbose)s
+        %(method_kw_tfr)s
+
+        Returns
+        -------
+        tfr : instance of AverageTFR
+            The time-frequency-resolved power estimates of the data.
+
+        Notes
+        -----
+        .. versionadded:: 1.6
+
+        References
+        ----------
+        .. footbibliography::
+        """
+        _ensure_output_not_in_method_kw(self, method_kw)
+        return AverageTFR(
+            self,
+            method=method,
+            freqs=freqs,
+            tmin=tmin,
+            tmax=tmax,
+            picks=picks,
+            proj=proj,
+            decim=decim,
+            n_jobs=n_jobs,
+            verbose=verbose,
+            **method_kw,
+        )
+
     @verbose
     def plot_psd(
         self,

mne/html_templates/repr/tfr.html.jinja

@@ -0,0 +1,54 @@
+<table class="table table-hover table-striped table-sm table-responsive small">
+    <tr>
+        <th>Data type</th>
+        <td>{{ tfr._data_type }}</td>
+    </tr>
+    {%- for unit in units %}
+    <tr>
+        {%- if loop.index == 1 %}
+        <th rowspan={{ units | length }}>Units</th>
+        {%- endif %}
+        <td class="justify">{{ unit }}</td>
+    </tr>
+    {%- endfor %}
+    <tr>
+        <th>Data source</th>
+        <td>{{ inst_type }}</td>
+    </tr>
+    {%- if inst_type == "Epochs" %}
+    <tr>
+        <th>Number of epochs</th>
+        <td>{{ tfr.shape[0] }}</td>
+    </tr>
+    {% endif -%}
+    <tr>
+        <th>Dims</th>
+        <td>{{ tfr._dims | join(", ") }}</td>
+    </tr>
+    <tr>
+        <th>Estimation method</th>
+        <td>{{ tfr.method }}</td>
+    </tr>
+    {% if "taper" in tfr._dims %}
+    <tr>
+        <th>Number of tapers</th>
+        <td>{{ tfr._mt_weights.size }}</td>
+    </tr>
+    {% endif %}
+    <tr>
+        <th>Number of channels</th>
+        <td>{{ tfr.ch_names|length }}</td>
+    </tr>
+    <tr>
+        <th>Number of timepoints</th>
+        <td>{{ tfr.times|length }}</td>
+    </tr>
+    <tr>
+        <th>Number of frequency bins</th>
+        <td>{{ tfr.freqs|length }}</td>
+    </tr>
+    <tr>
+        <th>Frequency range</th>
+        <td>{{ '%.2f'|format(tfr.freqs[0]) }} – {{ '%.2f'|format(tfr.freqs[-1]) }} Hz</td>
+    </tr>
+</table>

mne/io/base.py

@@ -80,6 +80,7 @@
 )
 from ..html_templates import _get_html_template
 from ..parallel import parallel_func
+from ..time_frequency.spectrogram import RawTFR
 from ..time_frequency.spectrum import Spectrum, SpectrumMixin, _validate_method
 from ..utils import (
     SizeMixin,
@@ -2208,6 +2209,65 @@ def compute_psd(
             **method_kw,
         )
 
+    @verbose
+    def compute_tfr(
+        self,
+        method,
+        freqs,
+        *,
+        tmin=None,
+        tmax=None,
+        picks=None,
+        proj=False,
+        reject_by_annotation=True,
+        decim=1,
+        n_jobs=None,
+        verbose=None,
+        **method_kw,
+    ):
+        """Compute a time-frequency representation of sensor data.
+
+        Parameters
+        ----------
+        %(method_tfr)s
+        %(freqs_tfr)s
+        %(tmin_tmax_psd)s
+        %(picks_good_data_noref)s
+        %(proj_psd)s
+        %(reject_by_annotation_tfr)s
+        %(decim_tfr)s
+        %(n_jobs)s
+        %(verbose)s
+        %(method_kw_tfr)s
+
+        Returns
+        -------
+        tfr : instance of RawTFR
+            The time-frequency-resolved power estimates of the data.
+
+        Notes
+        -----
+        .. versionadded:: 1.3
+
+        References
+        ----------
+        .. footbibliography::
+        """
+        return RawTFR(
+            self,
+            method=method,
+            freqs=freqs,
+            tmin=tmin,
+            tmax=tmax,
+            picks=picks,
+            proj=proj,
+            reject_by_annotation=reject_by_annotation,
+            decim=decim,
+            n_jobs=n_jobs,
+            verbose=verbose,
+            **method_kw,
+        )
+
     @verbose
     def to_data_frame(
         self,