[ENH, MRG] Add EpochsSpectrumArray and SpectrumArray classes

doc/changes/devel.rst

@@ -29,6 +29,7 @@ Enhancements
 - Added public :func:`mne.io.write_info` to complement :func:`mne.io.read_info` (:gh:`11918` by `Eric Larson`_)
 - Added option ``remove_dc`` to to :meth:`Raw.compute_psd() <mne.io.Raw.compute_psd>`, :meth:`Epochs.compute_psd() <mne.Epochs.compute_psd>`, and :meth:`Evoked.compute_psd() <mne.Evoked.compute_psd>`, to allow skipping DC removal when computing Welch or multitaper spectra (:gh:`11769` by `Nikolai Chapochnikov`_)
 - Add the possibility to provide a float between 0 and 1 as ``n_grad``, ``n_mag`` and ``n_eeg`` in `~mne.compute_proj_raw`, `~mne.compute_proj_epochs` and `~mne.compute_proj_evoked` to select the number of vectors based on the cumulative explained variance (:gh:`11919` by `Mathieu Scheltienne`_)
+- Add :class:`mne.time_frequency.EpochsSpectrumArray` and :class:`mne.time_frequency.SpectrumArray` to allow for instantiating power spectra from scratch (:gh:`11803` by `Alex Rockhill`_)
 
 Bugs
 ~~~~

doc/time_frequency.rst

@@ -17,7 +17,9 @@ Time-Frequency
    EpochsTFR
    CrossSpectralDensity
    Spectrum
+   SpectrumArray
    EpochsSpectrum
+   EpochsSpectrumArray
 
 Functions that operate on mne-python objects:
 

mne/conftest.py

@@ -297,6 +297,19 @@ def raw_ctf():
     return raw_ctf
 
 
+@pytest.fixture(scope="function")
+def raw_psds(raw):
+    """Get raw with power spectral density computed from mne.io.tests.data."""
+    return [
+        raw.compute_psd(
+            output="complex",
+            method=method,
+            **dict(average=None) if method == "welch" else dict(),
+        )
+        for method in ("welch", "multitaper")
+    ]
+
+
 @pytest.fixture(scope="function")
 def events():
     """Get events from mne.io.tests.data."""
@@ -349,6 +362,21 @@ def epochs_full():
     return _get_epochs(None).load_data()
 
 
+@pytest.fixture()
+def epochs_psds():
+    """Get epochs with power spectral density computed from mne.io.tests.data."""
+    return [
+        _get_epochs()
+        .load_data()
+        .compute_psd(
+            output="complex",
+            method=method,
+            **dict(average=False) if method == "welch" else dict(),
+        )
+        for method in ("welch", "multitaper")
+    ]
+
+
 @pytest.fixture(scope="session", params=[testing._pytest_param()])
 def _evoked():
     # This one is session scoped, so be sure not to modify it (use evoked

mne/epochs.py

@@ -3165,40 +3165,17 @@ class EpochsArray(BaseEpochs):
         measure.
     %(info_not_none)s Consider using :func:`mne.create_info` to populate this
         structure.
-    events : None | array of int, shape (n_events, 3)
-        The events typically returned by the read_events function.
-        If some events don't match the events of interest as specified
-        by event_id, they will be marked as 'IGNORED' in the drop log.
-        If None (default), all event values are set to 1 and event time-samples
-        are set to range(n_epochs).
-    tmin : float
-        Start time before event. If nothing provided, defaults to 0.
-    event_id : int | list of int | dict | None
-        The id of the event to consider. If dict,
-        the keys can later be used to access associated events. Example:
-        dict(auditory=1, visual=3). If int, a dict will be created with
-        the id as string. If a list, all events with the IDs specified
-        in the list are used. If None, all events will be used with
-        and a dict is created with string integer names corresponding
-        to the event id integers.
+    %(events_epochs)s
+    %(tmin_epochs)s
+    %(event_id)s
     %(reject_epochs)s
     %(flat)s
-    reject_tmin : scalar | None
-        Start of the time window used to reject epochs (with the default None,
-        the window will start with tmin).
-    reject_tmax : scalar | None
-        End of the time window used to reject epochs (with the default None,
-        the window will end with tmax).
+    %(epochs_reject_tmin_tmax)s
     %(baseline_epochs)s
         Defaults to ``None``, i.e. no baseline correction.
-    proj : bool | 'delayed'
-        Apply SSP projection vectors. See :class:`mne.Epochs` for details.
-    on_missing : str
-        See :class:`mne.Epochs` docstring for details.
-    metadata : instance of pandas.DataFrame | None
-        See :class:`mne.Epochs` docstring for details.
-
-        .. versionadded:: 0.16
+    %(proj_epochs)s
+    %(on_missing_epochs)s
+    %(metadata_epochs)s
     %(selection)s
     %(drop_log)s
 

mne/time_frequency/__init__.py

@@ -49,3 +49,14 @@
         ],
     },
 )
+from .ar import fit_iir_model_raw
+from .multitaper import dpss_windows, psd_array_multitaper, tfr_array_multitaper
+from .spectrum import (
+    EpochsSpectrum,
+    EpochsSpectrumArray,
+    Spectrum,
+    SpectrumArray,
+    read_spectrum,
+)
+from ._stft import stft, istft, stftfreq
+from ._stockwell import tfr_stockwell, tfr_array_stockwell