[ENH, MRG] Add EpochsSpectrumArray and SpectrumArray classes

doc/changes/latest.inc

@@ -32,6 +32,7 @@ Enhancements
 - Added :func:`mne.preprocessing.eyetracking.interpolate_blinks` to linear interpolate eyetrack signals during blink periods. (:gh:`11740` by `Scott Huberty`_)
 - Added a section for combining eye-tracking and EEG data to the preprocessing tutorial "working with eye tracker data in MNE-Python" (:gh:`11770` by `Scott Huberty`_)
 - Add :meth:`mne.Annotations.count` and :func:`mne.count_annotations` to count unique annotations (:gh:`11796` by `Clemens Brunner`_)
+- Add :class:`mne.time_frequency.spectrum.EpochsSpectrumArray` and :class:`mne.time_frequency.spectrum.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/time_frequency/__init__.py

@@ -27,6 +27,12 @@
 )
 from .ar import fit_iir_model_raw
 from .multitaper import dpss_windows, psd_array_multitaper, tfr_array_multitaper
-from .spectrum import EpochsSpectrum, Spectrum, read_spectrum
+from .spectrum import (
+    EpochsSpectrum,
+    EpochsSpectrumArray,
+    Spectrum,
+    SpectrumArray,
+    read_spectrum,
+)
 from ._stft import stft, istft, stftfreq
 from ._stockwell import tfr_stockwell, tfr_array_stockwell

mne/time_frequency/spectrum.py

@@ -1179,6 +1179,56 @@ def __getitem__(self, item):
         return BaseRaw._getitem(self, item, return_times=False)
 
 
+@fill_doc
+class SpectrumArray(Spectrum):
+    """Spectrum object from numpy array.
+
+    Parameters
+    ----------
+    data : array, shape (n_channels, n_freqs)
+        The channels' power spectral density for each epoch.
+    %(info_not_none)s
+    %(freqs_tfr)s
+    %(method_psd)s
+    %(verbose)s
+
+    See Also
+    --------
+    mne.create_info
+    mne.EpochsArray
+    mne.EvokedArray
+    mne.io.RawArray
+    EpochsSpectrumArray
+
+    Notes
+    -----
+        .. versionadded:: 1.5.0
+    """
+
+    @verbose
+    def __init__(
+        self,
+        data,
+        info,
+        freqs,
+        method=None,
+        *,
+        verbose=None,
+    ):
+        self.__setstate__(
+            dict(
+                method=method,
+                data=data,
+                sfreq=info["sfreq"],
+                dims=("channel", "freq"),
+                freqs=freqs,
+                inst_type_str="Raw",
+                data_type="Average Power Spectrum",
+                info=info,
+            )
+        )
+
+
 @fill_doc
 class EpochsSpectrum(BaseSpectrum, GetEpochsMixin):
     """Data object for spectral representations of epoched data.
@@ -1368,6 +1418,84 @@ def average(self, method="mean"):
         return Spectrum(state, **defaults)
 
 
+@fill_doc
+class EpochsSpectrumArray(EpochsSpectrum):
+    """EpochsSpectrum object from numpy array.
+
+    Parameters
+    ----------
+    data : array, shape (n_epochs, n_channels, n_freqs)
+        The channels' power spectral density for each epoch.
+    %(info_not_none)s
+    %(freqs_tfr)s
+    %(method_psd)s
+    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).
+    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.
+    metadata : instance of pandas.DataFrame | None
+        See :class:`mne.Epochs` docstring for details.
+    %(selection)s
+    %(drop_log)s
+    %(verbose)s
+
+    See Also
+    --------
+    mne.create_info
+    mne.EpochsArray
+    mne.EvokedArray
+    mne.io.RawArray
+    SpectrumArray
+
+    Notes
+    -----
+        .. versionadded:: 1.5.0
+    """
+
+    @verbose
+    def __init__(
+        self,
+        data,
+        info,
+        freqs,
+        method=None,
+        events=None,
+        event_id=None,
+        metadata=None,
+        selection=None,
+        drop_log=None,
+        *,
+        verbose=None,
+    ):
+        self.__setstate__(
+            dict(
+                method=method,
+                data=data,
+                sfreq=info["sfreq"],
+                dims=("epoch", "channel", "freq"),
+                freqs=freqs,
+                inst_type_str="Epochs",
+                data_type="Epochs Power Spectra",
+                info=info,
+                events=events,
+                event_id=event_id,
+                metadata=metadata,
+                selection=selection,
+                drop_log=drop_log,
+            )
+        )
+
+
 def read_spectrum(fname):
     """Load a :class:`mne.time_frequency.Spectrum` object from disk.
 

mne/time_frequency/tests/test_spectrum.py

@@ -10,6 +10,7 @@
 from mne import Annotations
 from mne.time_frequency import read_spectrum
 from mne.time_frequency.multitaper import _psd_from_mt
+from mne.time_frequency.spectrum import SpectrumArray, EpochsSpectrumArray
 
 
 def test_spectrum_errors(raw):
@@ -386,3 +387,31 @@ def test_spectrum_kwarg_triaging(raw):
         raw.plot_psd(axes=axes)
     # `ax` is the correct legacy param name
     raw.plot_psd(ax=axes)
+
+
+def test_spectrumarray_raw(raw):
+    """Test SpectrumArray for Raw-derived spectra."""
+    spect = raw.compute_psd()
+    spect2 = SpectrumArray(
+        data=spect.get_data(), freqs=spect.freqs, info=spect.info, method=spect.method
+    )
+    assert_array_equal(spect.get_data(), spect2.get_data())
+    assert_array_equal(spect.freqs, spect2.freqs)
+
+
+def test_epochsspectrumaray(epochs):
+    """Test EpochsSpectrumArray for Epochs-derived spectra."""
+    spect = epochs.compute_psd()
+    spect2 = EpochsSpectrumArray(
+        data=spect.get_data(),
+        freqs=spect.freqs,
+        info=spect.info,
+        method=spect.method,
+        events=epochs.events,
+        event_id=epochs.event_id,
+        metadata=epochs.metadata,
+        selection=epochs.selection,
+        drop_log=epochs.drop_log,
+    )
+    assert_array_equal(spect.get_data(), spect2.get_data())
+    assert_array_equal(spect.freqs, spect2.freqs)

tutorials/simulation/10_array_objs.py

@@ -224,39 +224,7 @@
 
 psd_ave = psd.mean(0)
 
-# map to `~mne.time_frequency.Spectrum` class and explore API
-
-
-def spectrum_from_array(
-    data: np.ndarray,  # spectral features
-    freqs: np.ndarray,  # frequencies
-    inst_info: mne.Info,  # the meta data of MNE instance
-) -> mne.time_frequency.Spectrum:  # Spectrum object
-    """Create MNE averaged power spectrum object from custom data"""
-    state = dict(
-        method="my_welch",
-        data=data,
-        sfreq=inst_info["sfreq"],
-        dims=("channel", "freq"),
-        freqs=freqs,
-        inst_type_str="Raw",
-        data_type="Averaged Power Spectrum",
-        info=inst_info,
-    )
-    defaults = dict(
-        method=None,
-        fmin=None,
-        fmax=None,
-        tmin=None,
-        tmax=None,
-        picks=None,
-        proj=None,
-        reject_by_annotation=None,
-        n_jobs=None,
-        verbose=None,
-    )
-    return mne.time_frequency.Spectrum(state, **defaults)
-
-
-spectrum = spectrum_from_array(data=psd_ave, freqs=freqs, inst_info=info)
+spectrum = mne.time_frequency.spectrum.SpectrumArray(
+    data=psd_ave, freqs=freqs, info=info, method="my_welch"
+)
 spectrum.plot(picks=[0, 1], spatial_colors=False, exclude="bads")