Add combine_tfr to API

doc/api/time_frequency.rst

@@ -31,6 +31,7 @@ Functions that operate on mne-python objects:
 .. autosummary::
    :toctree: ../generated/
 
+   combine_tfr
    csd_tfr
    csd_fourier
    csd_multitaper

doc/changes/devel/12910.bugfix.rst

@@ -0,0 +1 @@
+:func:`mne.time_frequency.combine_tfr` now raises an error when passed data with a tapers dimension, by `Thomas Binns`_.

doc/changes/devel/12910.newfeature.rst

@@ -0,0 +1 @@
+Added the option to return taper weights from :func:`mne.time_frequency.tfr_array_multitaper`, and taper weights are now stored in the :class:`mne.time_frequency.BaseTFR` objects, by `Thomas Binns`_.

doc/changes/devel/13054.other.rst

@@ -0,0 +1 @@
+Added :func:`mne.time_frequency.combine_tfr` to the documentation, by `Thomas Binns`_.

mne/time_frequency/__init__.pyi

@@ -11,6 +11,7 @@ __all__ = [
     "RawTFRArray",
     "Spectrum",
     "SpectrumArray",
+    "combine_tfr",
     "csd_array_fourier",
     "csd_array_morlet",
     "csd_array_multitaper",
@@ -71,6 +72,7 @@ from .tfr import (
     EpochsTFRArray,
     RawTFR,
     RawTFRArray,
+    combine_tfr,
     fwhm,
     morlet,
     read_tfrs,

mne/time_frequency/multitaper.py

@@ -471,6 +471,7 @@ def tfr_array_multitaper(
     output="complex",
     n_jobs=None,
     *,
+    return_weights=False,
     verbose=None,
 ):
     """Compute Time-Frequency Representation (TFR) using DPSS tapers.
@@ -502,8 +503,14 @@ def tfr_array_multitaper(
         * ``'itc'`` : inter-trial coherence.
         * ``'avg_power_itc'`` : average of single trial power and inter-trial
           coherence across trials.
+
     %(n_jobs)s
         The parallelization is implemented across channels.
+    return_weights : bool, default False
+        If True, return the taper weights. Only applies if ``output='complex'`` or
+        ``'phase'``.
+
+        .. versionadded:: 1.10.0
     %(verbose)s
 
     Returns
@@ -520,6 +527,9 @@ def tfr_array_multitaper(
         If ``output`` is ``'avg_power_itc'``, the real values in ``out``
         contain the average power and the imaginary values contain the
         inter-trial coherence: :math:`out = power_{avg} + i * ITC`.
+    weights : array of shape (n_tapers, n_freqs)
+        The taper weights. Only returned if ``output='complex'`` or ``'phase'`` and
+        ``return_weights=True``.
 
     See Also
     --------
@@ -550,6 +560,7 @@ def tfr_array_multitaper(
         use_fft=use_fft,
         decim=decim,
         output=output,
+        return_weights=return_weights,
         n_jobs=n_jobs,
         verbose=verbose,
     )