fix merge

.github/workflows/build.yml

@@ -6,20 +6,16 @@ on:
   push:
     branches: [ main ]
   pull_request:
-    branches: [ main ]
 
 jobs:
   build:
 
-    # Tag ubuntu version to 20.04, in order to support python 3.6
-    #   See issue: https://github.com/actions/setup-python/issues/544
-    #   When ready to drop 3.6, can revert from 'ubuntu-20.04' -> 'ubuntu-latest'
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-latest
     env:
       MODULE_NAME: specparam
     strategy:
       matrix:
-        python-version: ["3.6", "3.7", "3.8", "3.9", "3.10", "3.11", "3.12"]
+        python-version: ["3.7", "3.8", "3.9", "3.10", "3.11", "3.12"]
 
     steps:
     - uses: actions/checkout@v3

README.rst

@@ -28,7 +28,7 @@ Spectral Parameterization
 
 Spectral parameterization (`specparam`, formerly `fooof`) is a fast, efficient, and physiologically-informed tool to parameterize neural power spectra.
 
-WARNING: this Github repository has been updated to a major update / breaking change from the current release of the `fooof` module, and is no longer consistent with the `fooof` version of the code.
+WARNING: this Github repository has been updated to a major update / breaking change from previous releases, which were under the `fooof` name, and now contains major breaking update for the new `specparam` version of the code. The new version is not fully released, though a test version is available (see installation instructions below).
 
 Overview
 --------
@@ -47,11 +47,39 @@ specific bands of interest and controlling for the aperiodic component.
 The model also returns a measure of this aperiodic components of the signal, allowing for measuring and
 comparison of 1/f-like components of the signal within and between subjects.
 
+specparam (upcoming version)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+We are currently in the process of a major update to this tool, that includes a name changes (fooof -> specparam), and full rewrite of the code. This means that the new version will be incompatible with prior versions (in terms of the code having different names, and previous code no longer running as written), though note that the exact same procedures will be available (spectra can be fit in a way expected to give the same results), as well many new features.
+
+The new version is called `specparam` (spectral parameterization). There is a release candidate available for testing (see installation instructions).
+
+fooof (stable version)
+~~~~~~~~~~~~~~~~~~~~~~
+
+The fooof naming scheme, with most recent stable version 1.1 is the current main release, and is fully functional and stable, including everything that was introduced under the fooof name.
+
+Which version should I use?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The previous release version, fooof, is fully functional, and projects that are already using it might as well stick with that, unless any of the new functionality in specparam is particularly important. For projects that are just starting, the new specparam version may be of interest if some of the new features are of interest (e.g. time-resolved estimations), though note that as release candidates, the release are not guaranteed to be stable (future updates may make breaking changes). Note that for the same model and settings, fooof and specparam should be exactly equivalent, so in terms of outputs there should be no difference in choosing one or the other.
+
 Documentation
 -------------
 
+The `specparam` package includes a full set of code documentation.
+
+specparam (upcoming version)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To see the documentation for the candidate 2.0 release, see
+`here <https://specparam-tools.github.io/>`_.
+
+fooof (stable version)
+~~~~~~~~~~~~~~~~~~~~~~
+
 Documentation is available on the
-`documentation site <https://fooof-tools.github.io/fooof/index.html>`_.
+`documentation site <https://fooof-tools.github.io/>`_.
 
 This documentation includes:
 
@@ -73,7 +101,7 @@ This documentation includes:
 Dependencies
 ------------
 
-SpecParam is written in Python, and requires Python >= 3.6 to run.
+`specparam` is written in Python, and requires Python >= 3.7 to run.
 
 It has the following required dependencies:
 
@@ -92,6 +120,26 @@ We recommend using the `Anaconda <https://www.anaconda.com/distribution/>`_ dist
 Installation
 ------------
 
+specparam / fooof can be installed using pip.
+
+specparam (test version)
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+To install the current release candidate version for the new 2.0 version, you can do:
+
+.. code-block:: shell
+
+    $ pip install specparam
+
+The above will install the most recent release candidate.
+
+NOTE: specparam is currently available as a 'release candidate', meaning it is not finalized and fully released yet.
+This means it may not yet have all features that the ultimate 2.0 version will include, and things are not strictly
+guaranteed to stay the same (there may be further breaking changes in the ultimate 2.0 release).
+
+fooof (stable version)
+~~~~~~~~~~~~~~~~~~~~~~
+
 The current major release is the 1.X.X series, which is a breaking change from the prior 0.X.X series.
 
 Check the `changelog <https://fooof-tools.github.io/fooof/changelog.html>`_ for notes on updating to the new version.
@@ -142,7 +190,7 @@ If you wish to run specparam from another language, there are a couple potential
 - a `wrapper`, which allows for running the Python code from another language
 - a `reimplementation`, which reflects a new implementation of the specparam algorithm in another language
 
-Below are listed some examples of wrappers and/or reimplementations in other languages (non-exhaustive).
+Below are listed some examples of wrappers and/or re-implementations in other languages (non-exhaustive).
 
 Matlab
 ~~~~~~

doc/api.rst

@@ -40,6 +40,17 @@ The SpectralGroupModel object allows for parameterizing groups of power spectra.
 
    SpectralGroupModel
 
+Time & Event Objects
+~~~~~~~~~~~~~~~~~~~~
+
+The time & event objects allows for parameterizing power spectra organized across time and/or events.
+
+.. autosummary::
+   :toctree: generated/
+
+   SpectralTimeModel
+   SpectralTimeEventModel
+
 Object Utilities
 ~~~~~~~~~~~~~~~~
 
@@ -155,6 +166,7 @@ The following functions take in model objects directly, which is the typical use
 
     get_band_peak
     get_band_peak_group
+    get_band_peak_event
 
 **Array Inputs**
 
@@ -178,7 +190,7 @@ Code & utilities for simulating power spectra.
 Generate Power Spectra
 ~~~~~~~~~~~~~~~~~~~~~~
 
-Functions for simulating neural power spectra.
+Functions for simulating neural power spectra and spectrograms.
 
 .. currentmodule:: specparam.sim
 
@@ -187,6 +199,7 @@ Functions for simulating neural power spectra.
 
     sim_power_spectrum
     sim_group_power_spectra
+    sim_spectrogram
 
 Manage Parameters
 ~~~~~~~~~~~~~~~~~
@@ -242,14 +255,15 @@ Visualizations.
 Plot Power Spectra
 ~~~~~~~~~~~~~~~~~~
 
-Plots for visualizing power spectra.
+Plots for visualizing power spectra and spectrograms.
 
 .. currentmodule:: specparam.plts
 
 .. autosummary::
     :toctree: generated/
 
     plot_spectra
+    plot_spectrogram
 
 Plots for plotting power spectra with shaded regions.
 
@@ -311,7 +325,21 @@ Note that these are the same plotting functions that can be called from the mode
 .. autosummary::
     :toctree: generated/
 
-    plot_group
+    plot_group_model
+
+.. currentmodule:: specparam.plts.time
+
+.. autosummary::
+    :toctree: generated/
+
+    plot_time_model
+
+.. currentmodule:: specparam.plts.event
+
+.. autosummary::
+    :toctree: generated/
+
+    plot_event_model
 
 Annotated Plots
 ~~~~~~~~~~~~~~~
@@ -388,7 +416,9 @@ Input / Output (IO)
     :toctree: generated/
 
     load_model
-    load_group
+    load_group_model
+    load_time_model
+    load_event_model
 
 Methods Reports
 ~~~~~~~~~~~~~~~

examples/manage/plot_fit_models_3d.py

@@ -61,7 +61,7 @@
 from specparam.sim import sim_group_power_spectra
 from specparam.sim.utils import create_freqs
 from specparam.sim.params import param_sampler
-from specparam.utils.io import load_group
+from specparam.utils.io import load_group_model
 
 ###################################################################################################
 # Example Set-Up
@@ -229,7 +229,7 @@
 ###################################################################################################
 
 # Reload our list of SpectralGroupModels
-fgs = [load_group(file_name, file_path='results') \
+fgs = [load_group_model(file_name, file_path='results') \
     for file_name in os.listdir('results')]
 
 ###################################################################################################

setup.py

@@ -39,7 +39,6 @@
         'Operating System :: POSIX',
         'Operating System :: Unix',
         'Programming Language :: Python',
-        'Programming Language :: Python :: 3.6',
         'Programming Language :: Python :: 3.7',
         'Programming Language :: Python :: 3.8',
         'Programming Language :: Python :: 3.9',

specparam/__init__.py

@@ -3,5 +3,5 @@
 from .version import __version__
 
 from .bands import Bands
-from .objs import SpectralModel, SpectralGroupModel
+from .objs import SpectralModel, SpectralGroupModel, SpectralTimeModel, SpectralTimeEventModel
 from .objs.utils import fit_models_3d

specparam/analysis/__init__.py

@@ -1,4 +1,4 @@
 """Analysis sub-module for model parameters and related metrics."""
 
 from .error import compute_pointwise_error, compute_pointwise_error_group
-from .periodic import get_band_peak, get_band_peak_group
+from .periodic import get_band_peak, get_band_peak_group, get_band_peak_event

specparam/analysis/periodic.py

@@ -30,7 +30,7 @@ def get_band_peak(model, band, select_highest=True, threshold=None,
 
     Returns
     -------
-    1d or 2d array
+    peaks : 1d or 2d array
         Peak data. Each row is a peak, as [CF, PW, BW].
 
     Examples
@@ -67,7 +67,7 @@ def get_band_peak_group(group, band, threshold=None, thresh_param='PW', attribut
 
     Returns
     -------
-    2d array
+    peaks : 2d array
         Peak data. Each row is a peak, as [CF, PW, BW].
         Each row represents an individual model from the input object.
 
@@ -101,6 +101,40 @@ def get_band_peak_group(group, band, threshold=None, thresh_param='PW', attribut
                                    threshold, thresh_param)
 
 
+def get_band_peak_event(event, band, threshold=None, thresh_param='PW', attribute='peak_params'):
+    """Extract peaks from a band of interest from an event model object.
+
+    Parameters
+    ----------
+    event : SpectralTimeEventModel
+        Object to extract peak data from.
+    band : tuple of (float, float)
+        Frequency range for the band of interest.
+        Defined as: (lower_frequency_bound, upper_frequency_bound).
+    select_highest : bool, optional, default: True
+        Whether to return single peak (if True) or all peaks within the range found (if False).
+        If True, returns the highest power peak within the search range.
+    threshold : float, optional
+        A minimum threshold value to apply.
+    thresh_param : {'PW', 'BW'}
+        Which parameter to threshold on. 'PW' is power and 'BW' is bandwidth.
+    attribute : {'peak_params', 'gaussian_params'}
+        Which attribute of peak data to extract data from.
+
+    Returns
+    -------
+    peaks : 3d array
+        Array of peak data, organized as [n_events, n_time_windows, n_peak_params].
+    """
+
+    peaks = np.zeros([event.n_events, event.n_time_windows, 3])
+    for ind in range(event.n_events):
+        peaks[ind, :, :] = get_band_peak_group(\
+            event.get_group(ind, None, 'group'), band, threshold, thresh_param, attribute)
+
+    return peaks
+
+
 def get_band_peak_group_arr(peak_params, band, n_fits, threshold=None, thresh_param='PW'):
     """Extract peaks within a given band of interest, from peaks from a group fit.