[ENH] - Define new object organization (Data / Results / Base / Algorithm)

.github/workflows/build.yml

@@ -18,9 +18,9 @@ jobs:
         python-version: ["3.7", "3.8", "3.9", "3.10", "3.11", "3.12"]
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
     - name: Install dependencies
@@ -37,4 +37,6 @@ jobs:
       run: |
         pytest --doctest-modules --ignore=$MODULE_NAME/tests $MODULE_NAME
     - name: Upload coverage to Codecov
-      uses: codecov/codecov-action@v3
+      uses: codecov/codecov-action@v4
+      env:
+        CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

.gitignore

@@ -45,3 +45,4 @@ doc/auto_examples/*
 doc/auto_tutorials/*
 doc/auto_motivations/*
 doc/generated/*
+doc/sg_execution_times.rst

doc/_static/my-styles.css

@@ -0,0 +1,3 @@
+.navbar-form {
+  margin-right: -75px;
+}

doc/changelog.rst

@@ -8,6 +8,94 @@ This page primarily notes changes for major version updates.
 For notes on the specific updates for minor releases, see the
 `release page <https://github.com/fooof-tools/fooof/releases>`_.
 
+2.0.0 (in development)
+----------------------
+
+WARNING: the specparam 2.0 release is not yet a a stable release, and may still change!
+
+Note that the new `specparam 2.0` version includes a significant refactoring or the internals of the module, and broad changes to the naming of entities (including classes, functions, methods, etc) across the module. As such, this update is a major, breaking change to the module (see below for updates). See below for notes on the major updates, and relationships to previous versions of the module.
+
+Key Updates
+~~~~~~~~~~~
+
+The `specparam` 2.0 version contains the following notable feature updates:
+
+- an extension of the module to support time-resolved and event-related analyses
+
+  - these analyses are now supported by the ``SpectralTimeModel`` and ``SpectralTimeEventModel`` objects
+
+- an update to procedures for functions that are fit to power spectra
+
+  - these updates allow for flexibly using and defining different fit functions [WIP]
+
+- an update to procedures for defining and applying spectral fitting algorithms
+
+  - these updates allow for choosing, tuning, and changing the fitting algorithm that is applied [WIP]
+
+- extensions and updates to the module
+
+  - this includes updates to parameter management, goodness-of-fit evaluations, visualizations, and more
+
+The above notes the major changes and updates to the module - for further details on the changes, see the
+`release page <https://github.com/fooof-tools/fooof/releases>`_.
+
+Relationship to fooof
+~~~~~~~~~~~~~~~~~~~~~
+
+As compared to the fooof releases, the specparam module is an extension of the spectral parameterization approach, including the same functionality as the original module, with significant extensions. This means that, for example, if choosing the same fit functions and algorithms in specparam 2.0 as are used in fooof 1.X, the results should be functionally identical.
+
+Notably, there are no changes to the default settings and models in specparam 2.0, such that fitting a spectral model with the default settings in specparam should provide the same as doing the equivalent in fooof 1.X.
+
+Naming Updates
+~~~~~~~~~~~~~~
+
+The following functions, objects, and attributes have changed name in the new version:
+
+Model Objects:
+
+- FOOOF -> SpectralModel
+- FOOOFGroup -> SpectralGroupModel
+
+Model Object methods & attributes:
+
+- FOOOF.fooofed_spectrum\_ -> SpectralModel.modeled_spectrum\_
+- FOOOFGroup.get_fooof -> SpectralGroupModel.get_model
+
+Data objects:
+
+- FOOOFResults -> FitResults
+- FOOOFSettings -> ModelSettings
+- FOOOFMetaData -> SpectrumMetaData
+
+Functions:
+
+- combine_fooofs -> combine_model_objs
+- compare_info -> compare_model_objs
+- average_fg -> average_group
+- fit_fooof_3d -> fit_models_3d
+
+- get_band_peak_fm -> get_band_peak
+- get_band_peak_fg -> get_band_peak_group
+- get_band_peak -> get_band_peak_arr
+- get_band_peak_group -> get_band_peak_group_arr
+
+- compute_pointwise_error_fm -> compute_pointwise_error
+- compute_pointwise_error_fg -> compute_pointwise_error_group
+- compute_pointwise_error -> compute_pointwise_error_arr
+
+- save_fm -> save_model
+- save_fg -> save_group
+
+- fetch_fooof_data -> fetch_example_data
+- load_fooof_data -> load_example_data
+
+- gen_power_spectrum -> sim_power_spectrum
+- gen_group_power_spectra -> sim_group_power_spectra
+
+Function inputs:
+
+- fooof_obj -> model_obj
+
 1.1.0
 -----
 

doc/conf.py

@@ -119,6 +119,12 @@
 html_copy_source = False
 html_show_sourcelink = False
 
+# Add link to custom css
+html_static_path = ["_static"]
+
+# Add function for stylesheets path
+def setup(app):
+   app.add_css_file("my-styles.css")
 
 # -- Extension configuration -------------------------------------------------
 

examples/analyses/plot_dev_demo.py

@@ -498,8 +498,8 @@
 ###################################################################################################
 
 # Initialize model objects for spectral parameterization, with some settings
-fg1 = SpectralGroupModel(*settings1)
-fg2 = SpectralGroupModel(*settings2)
+fg1 = SpectralGroupModel(**settings1._asdict())
+fg2 = SpectralGroupModel(**settings2._asdict())
 
 ###################################################################################################
 #

specparam/core/io.py

@@ -236,6 +236,125 @@ def save_event(event, file_name, file_path=None, append=False,
                     save_settings=save_settings, save_data=save_data)
 
 
+def load_model(file_name, file_path=None, regenerate=True, model=None):
+    """Load a SpectralModel object.
+
+    Parameters
+    ----------
+    Parameters
+    ----------
+    file_name : str
+        File(s) to load data from.
+    file_path : str, optional
+        Path to directory to load from. If None, loads from current directory.
+    regenerate : bool, optional, default: True
+        Whether to regenerate the model fit from the loaded data, if data is available.
+    model : SpectralModel
+        xx
+
+    Returns
+    -------
+    model : SpectralModel
+        Loaded model object with data from file.
+    """
+
+    # Check for model object, import (avoid circular) and initialize if not
+    if not model:
+        from specparam.objs import SpectralModel
+        model = SpectralModel()
+
+    model.load(file_name, file_path, regenerate)
+
+    return model
+
+
+def load_group(file_name, file_path=None, group=None):
+    """Load a SpectralGroupModel object.
+
+    Parameters
+    ----------
+    file_name : str
+        File(s) to load data from.
+    file_path : str, optional
+        Path to directory to load from. If None, loads from current directory.
+    group : SpectralGroupModel
+        xx
+
+    Returns
+    -------
+    group : SpectralGroupModel
+        Loaded model object with data from file.
+    """
+
+    # Check for model object, import (avoid circular) and initialize if not
+    if not group:
+        from specparam.objs import SpectralGroupModel
+        group = SpectralGroupModel()
+
+    group.load(file_name, file_path)
+
+    return group
+
+
+def load_time(file_name, file_path=None, peak_org=None, time=None):
+    """Load a SpectralTimeModel object.
+
+    Parameters
+    ----------
+    file_name : str
+        File(s) to load data from.
+    file_path : str, optional
+        Path to directory to load from. If None, loads from current directory.
+    peak_org : int or Bands, optional
+        How to organize peaks.
+        If int, extracts the first n peaks.
+        If Bands, extracts peaks based on band definitions.
+
+    Returns
+    -------
+    time : SpectralTimeModel
+        Loaded model object with data from file.
+    """
+
+    # Check for model object, import (avoid circular) and initialize if not
+    if not time:
+        from specparam.objs import SpectralTimeModel
+        time = SpectralTimeModel()
+
+    time.load(file_name, file_path, peak_org)
+
+    return time
+
+def load_event(file_name, file_path=None, peak_org=None, event=None):
+    """Load a SpectralTimeEventModel object.
+
+    Parameters
+    ----------
+    file_name : str
+        File(s) to load data from.
+    file_path : str, optional
+        Path to directory to load from. If None, loads from current directory.
+    peak_org : int or Bands, optional
+        How to organize peaks.
+        If int, extracts the first n peaks.
+        If Bands, extracts peaks based on band definitions.
+
+    Returns
+    -------
+    event : SpectralTimeEventModel
+        Loaded model object with data from file.
+    """
+
+    # Check for model object, import (avoid circular) and initialize if not
+    if not event:
+        from specparam.objs import SpectralTimeEventModel
+        event = SpectralTimeEventModel()
+
+    event.load(file_name, file_path, peak_org)
+
+    return event
+
+
 def load_json(file_name, file_path):
     """Load json file.
 

specparam/data/utils.py

@@ -35,7 +35,7 @@ def get_model_params(fit_results, name, col=None):
     if name in ['aperiodic', 'peak', 'gaussian']:
         name = name + '_params'
 
-    # Extract the request data field from object
+    # Extract the requested data field from object
     out = getattr(fit_results, name)
 
     # Periodic values can be empty arrays and if so, replace with NaN array

specparam/objs/__init__.py

@@ -1,6 +1,6 @@
 """Objects sub-module, for model objects and functions that operate on model objects."""
 
-from .fit import SpectralModel
+from .model import SpectralModel
 from .group import SpectralGroupModel
 from .time import SpectralTimeModel
 from .event import SpectralTimeEventModel