[WIP] - Add explicit {aperiodic, periodic} 'Modes' support

doc/api.rst

@@ -56,7 +56,7 @@ Object Utilities
 
 Functions to manipulate, examine, and analyze model objects.
 
-.. currentmodule:: specparam.objs
+.. currentmodule:: specparam.models
 
 .. autosummary::
    :toctree: generated/
@@ -65,14 +65,9 @@ Functions to manipulate, examine, and analyze model objects.
    combine_model_objs
    average_group
    average_reconstructions
-
-.. currentmodule:: specparam
-
-.. autosummary::
-   :toctree: generated/
-
    fit_models_3d
 
+
 Data Objects
 ------------
 
@@ -102,8 +97,9 @@ Objects to store settings, metadata and results for power spectrum models.
    :template: data_object.rst
 
    SpectrumMetaData
+   ModelModes
    ModelSettings
-   ModelRunModes
+   ModelChecks
    FitResults
 
 Simulation Parameters
@@ -163,7 +159,7 @@ Functions for analyzing the error of model fits.
 
 The following functions take in model objects directly.
 
-.. currentmodule:: specparam.measures.error
+.. currentmodule:: specparam.measures.pointwise
 
 .. autosummary::
     :toctree: generated/
@@ -175,7 +171,7 @@ The following functions take in model objects directly.
 
 The following functions operate on arrays of models and data, which may be useful for more custom work-flows.
 
-.. currentmodule:: specparam.measures.error
+.. currentmodule:: specparam.measures.pointwise
 
 .. autosummary::
     :toctree: generated/

examples/analyses/plot_dev_demo.py

@@ -45,7 +45,7 @@
 from specparam.plts.aperiodic import plot_aperiodic_params, plot_aperiodic_fits
 
 # Import functions to examine frequency-by-frequency error of model fits
-from specparam.measures.error import compute_pointwise_error, compute_pointwise_error_group
+from specparam.measures.pointwise import compute_pointwise_error, compute_pointwise_error_group
 
 # Import helper utility to access data
 from specparam.utils.download import fetch_example_data
@@ -127,12 +127,12 @@
 ###################################################################################################
 
 # Access the model fit parameters from the model object
-print('Aperiodic parameters: \n', fm.aperiodic_params_, '\n')
-print('Peak parameters: \n', fm.peak_params_, '\n')
+print('Aperiodic parameters: \n', fm.results.aperiodic_params_, '\n')
+print('Peak parameters: \n', fm.results.peak_params_, '\n')
 print('Goodness of fit:')
-print('Error - ', fm.error_)
-print('R^2   - ', fm.r_squared_, '\n')
-print('Number of fit peaks: \n', fm.n_peaks_)
+print('Error - ', fm.results.error_)
+print('R^2   - ', fm.results.r_squared_, '\n')
+print('Number of fit peaks: \n', fm.results.n_peaks_)
 
 ###################################################################################################
 #
@@ -181,15 +181,16 @@
 plt_log = False
 
 # Do an initial aperiodic fit - a robust fit, that excludes outliers
-init_ap_fit = gen_aperiodic(fm.freqs, fm._robust_ap_fit(fm.freqs, fm.power_spectrum))
+init_ap_fit = gen_aperiodic(\
+    fm.data.freqs, fm.algorithm._robust_ap_fit(fm.data.freqs, fm.data.power_spectrum))
 
 # Recompute the flattened spectrum using the initial aperiodic fit
-init_flat_spec = fm.power_spectrum - init_ap_fit
+init_flat_spec = fm.data.power_spectrum - init_ap_fit
 
 ###################################################################################################
 
 # Plot the flattened the power spectrum
-plot_spectra(fm.freqs, init_flat_spec, plt_log, label='Flattened spectrum', color='black')
+plot_spectra(fm.data.freqs, init_flat_spec, plt_log, label='Flattened spectrum', color='black')
 
 ###################################################################################################
 #
@@ -247,7 +248,7 @@
 
 # Note that the average of this error is the same as the global error stored
 print('Average freq-by-freq error:\t {:1.3f}'.format(np.mean(errs_fm)))
-print('Total model fit error: \t\t {:1.3f}'.format(fm.error_))
+print('Total model fit error: \t\t {:1.3f}'.format(fm.results.error_))
 
 ###################################################################################################
 # Fitting a Group of Power Spectra
@@ -329,7 +330,7 @@
 ###################################################################################################
 
 # Check the average number of fit peaks, per model
-print('Average number of fit peaks: ', np.mean(fg.n_peaks_))
+print('Average number of fit peaks: ', np.mean(fg.results.n_peaks_))
 
 ###################################################################################################
 
@@ -341,9 +342,9 @@
 ###################################################################################################
 
 # Extract band-limited peaks information
-thetas = get_band_peak_group(fg, bands.theta)
-alphas = get_band_peak_group(fg, bands.alpha)
-betas = get_band_peak_group(fg, bands.beta)
+thetas = get_band_peak_group(fg, bands['theta'])
+alphas = get_band_peak_group(fg, bands['alpha'])
+betas = get_band_peak_group(fg, bands['beta'])
 
 ###################################################################################################
 #
@@ -377,7 +378,7 @@
 # Plot reconstructions of model components
 _, axes = plt.subplots(1, 2, figsize=(14, 6))
 plot_peak_fits(alphas, ax=axes[0])
-plot_aperiodic_fits(aps, fg.freq_range, ax=axes[1])
+plot_aperiodic_fits(aps, fg.data.freq_range, ax=axes[1])
 
 ###################################################################################################
 # Tuning the specparam algorithm
@@ -424,6 +425,9 @@
 m1_peak_height = 0.05
 m2_peak_height = 0.10
 
+# Define `` for both models
+peak_threshold = 2.0
+
 ###################################################################################################
 #
 # Next, we set frequency ranges for each model.
@@ -455,7 +459,7 @@
 fg1.fit(m1_freq, m1_spectra)
 
 # Create individual reports for model 1 settings (these could be saved and checked)
-for ind in range(len(fg1)):
+for ind in range(len(fg1.results)):
     temp_model = fg1.get_model(ind, regenerate=True)
 
 ###################################################################################################
@@ -471,7 +475,7 @@
 fg2.fit(m2_freq, m2_spectra)
 
 # Create individual reports for model 2 settings (these could be saved and checked)
-for ind in range(len(fg2)):
+for ind in range(len(fg2.results)):
     temp_model = fg2.get_model(ind, regenerate=True)
 
 ###################################################################################################
@@ -486,19 +490,20 @@
 
 # Define settings for model 1
 settings1 = ModelSettings(peak_width_limits=m1_peak_width, max_n_peaks=m1_n_peaks,
-                          min_peak_height=m1_peak_height, peak_threshold=2.,
-                          aperiodic_mode='fixed')
+                          min_peak_height=m1_peak_height, peak_threshold=peak_threshold)
 
 # Define settings for model 2
 settings2 = ModelSettings(peak_width_limits=m2_peak_width, max_n_peaks=m2_n_peaks,
-                          min_peak_height=m2_peak_height, peak_threshold=2.,
-                          aperiodic_mode='fixed')
+                          min_peak_height=m2_peak_height, peak_threshold=peak_threshold)
+
+# Define aperiodic mode to use
+aperiodic_mode = 'fixed'
 
 ###################################################################################################
 
 # Initialize model objects for spectral parameterization, with some settings
-fg1 = SpectralGroupModel(**settings1._asdict())
-fg2 = SpectralGroupModel(**settings2._asdict())
+fg1 = SpectralGroupModel(**settings1._asdict(), aperiodic_mode=aperiodic_mode)
+fg2 = SpectralGroupModel(**settings2._asdict(), aperiodic_mode=aperiodic_mode)
 
 ###################################################################################################
 #
@@ -562,7 +567,7 @@
 # Extract all fits that are above some error threshold, for further examination.
 underfit_error_threshold = 0.100
 underfit_check = []
-for ind, res in enumerate(fg):
+for ind, res in enumerate(fg.results):
     if res.error > underfit_error_threshold:
         underfit_check.append(fg.get_model(ind, regenerate=True))
 
@@ -582,7 +587,7 @@
 # Extract all fits that are below some error threshold, for further examination.
 overfit_error_threshold = 0.02
 overfit_check = []
-for ind, res in enumerate(fg):
+for ind, res in enumerate(fg.results):
     if res.error < overfit_error_threshold:
         overfit_check.append(fg.get_model(ind, regenerate=True))
 
@@ -641,25 +646,25 @@
 errs_fg = compute_pointwise_error_group(fg, plot_errors=False, return_errors=True)
 
 # Check which frequency has the highest error
-f_max_err = fg.freqs[np.argmax(np.mean(errs_fg, 0))]
+f_max_err = fg.data.freqs[np.argmax(np.mean(errs_fg, 0))]
 print('Frequency with highest mean error: \t\t\t', f_max_err)
 
 # Check which frequency has the largest standard deviation of error
-f_max_std = fg.freqs[np.argmax(np.std(errs_fg, 0))]
+f_max_std = fg.data.freqs[np.argmax(np.std(errs_fg, 0))]
 print('Frequency with highest standard deviation of error: \t', f_max_std)
 
 ###################################################################################################
 #
 # In some cases, it may be necessary to drop poor (or failed) model fits from the group object.
-# This can be done using the `fg.drop` function, as shown here.
+# This can be done using the `fg.results.drop` function, as shown here.
 # In this case, we remove a participant who has a MAE greater than 0.10.
 # The error threshold will vary depending on sample characteristics and data quality.
 #
 
 ###################################################################################################
 
 # Drop poor model fits based on MAE
-fg.drop(fg.get_params('error') > 0.10)
+fg.results.drop(fg.get_params('error') > 0.10)
 
 ###################################################################################################
 # Conclusions

examples/analyses/plot_mne_example.py

@@ -183,7 +183,7 @@ def check_nans(data, nan_policy='zero'):
 ###################################################################################################
 
 # Extract alpha peaks
-alphas = get_band_peak_group(fg, bands.alpha)
+alphas = get_band_peak_group(fg, bands['alpha'])
 
 # Extract the power values from the detected peaks
 alpha_pw = alphas[:, 1]
@@ -282,10 +282,10 @@ def check_nans(data, nan_policy='zero'):
 # Compare the power spectra between low and high exponent channels
 fig, ax = plt.subplots(figsize=(8, 6))
 
-spectra = [fg.get_model(np.argmin(exps)).power_spectrum,
-           fg.get_model(np.argmax(exps)).power_spectrum]
+spectra = [fg.get_model(np.argmin(exps)).data.power_spectrum,
+           fg.get_model(np.argmax(exps)).data.power_spectrum]
 
-plot_spectra(fg.freqs, spectra, ax=ax, labels=['Low Exponent', 'High Exponent'])
+plot_spectra(fg.data.freqs, spectra, ax=ax, labels=['Low Exponent', 'High Exponent'])
 
 ###################################################################################################
 # Conclusion

examples/manage/plot_failed_fits.py

@@ -66,8 +66,8 @@
 ###################################################################################################
 
 # Check for failed model fits
-print('Number of Null models  : \t', fg.n_null_)
-print('Indices of Null models : \t', fg.null_inds_)
+print('Number of Null models  : \t', fg.results.n_null_)
+print('Indices of Null models : \t', fg.results.null_inds_)
 
 ###################################################################################################
 # Inducing Model Fit Failures
@@ -102,8 +102,8 @@
 ###################################################################################################
 
 # Check how many model fit failures we have failed model fits
-print('Number of Null models  : \t', fg.n_null_)
-print('Indices of Null models : \t', fg.null_inds_)
+print('Number of Null models  : \t', fg.results.n_null_)
+print('Indices of Null models : \t', fg.results.null_inds_)
 
 ###################################################################################################
 # Debug Mode
@@ -130,7 +130,7 @@
 ###################################################################################################
 
 # Set SpectralGroupModel into debug mode
-fg.set_debug_mode(True)
+fg.algorithm.set_debug(True)
 
 ###################################################################################################
 

examples/manage/plot_fit_models_3d.py

@@ -57,7 +57,7 @@
 from specparam import SpectralGroupModel
 
 # Import utilities for working with model objects
-from specparam.objs import fit_models_3d, combine_model_objs
+from specparam.models import fit_models_3d, combine_model_objs
 
 # Import simulation & IO utilities to help with the example
 from specparam.sim import sim_group_power_spectra

examples/manage/plot_manipulating_models.py

@@ -29,7 +29,7 @@
 from specparam.bands import Bands
 
 # Import utility functions for working with model objects
-from specparam.objs.utils import average_group, combine_model_objs, compare_model_objs
+from specparam.models.utils import average_group, combine_model_objs, compare_model_objs
 
 # Import simulation functions to create our example data
 from specparam.sim import sim_power_spectrum
@@ -87,7 +87,7 @@
 
 # Check the number of models in the object
 #   Note that the length of a SpectralGroupModel object is defined as the number of model fits
-print('Number of model fits: ', len(fg))
+print('Number of model fits: ', len(fg.results))
 
 ###################################################################################################
 # Note on Manipulating Model Objects
@@ -141,7 +141,7 @@
 nfg = fg.get_group(inds)
 
 # Check how many models our new SpectralGroupModel object contains
-print('Number of model fits: ', len(nfg))
+print('Number of model fits: ', len(nfg.results))
 
 ###################################################################################################
 #
@@ -154,7 +154,7 @@
 # -------------------------------------
 #
 # Another option is to 'drop' model fits from a SpectralGroupModel object. You can do this with
-# the :meth:`~specparam.SpectralGroupModel.drop` method from a
+# the :meth:`~specparam.SpectralGroupModel.results.drop` method from a
 # :class:`~specparam.SpectralGroupModel` object.
 #
 # This can be used, for example, for a quality control step. If you have checked through
@@ -168,7 +168,7 @@
 ###################################################################################################
 
 # Drop all model fits above an error threshold
-fg.drop(fg.get_params('error') > 0.01)
+fg.results.drop(fg.get_params('error') > 0.01)
 
 ###################################################################################################
 # Note on Dropped or Failed Fits
@@ -186,25 +186,25 @@
 ###################################################################################################
 
 # Check information on null models (dropped models)
-print('Number of Null models  : \t', fg.n_null_)
-print('Indices of Null models : \t', fg.null_inds_)
+print('Number of Null models  : \t', fg.results.n_null_)
+print('Indices of Null models : \t', fg.results.null_inds_)
 
 # Despite the dropped model, the total number of models in the object is the same
 #   This means that the indices are still the same as before dropping models
-print('Number of model fits: ', len(fg))
+print('Number of model fits: ', len(fg.results))
 
 ###################################################################################################
 
 # Null models are defined as all NaN (not a number)
-for ind in fg.null_inds_:
-    print(fg[ind])
+for ind in fg.results.null_inds_:
+    print(fg.results[ind])
 
 ###################################################################################################
 # Note on Selecting from SpectralModel Objects
 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 #
 # Both the :meth:`~specparam.SpectralGroupModel.get_group` and
-# :meth:`~specparam.SpectralGroupModel.drop` methods take an input of the indices of the
+# :meth:`~specparam.SpectralGroupModel.results.drop` methods take an input of the indices of the
 # model(s) to select or drop.
 #
 # In both cases, the input can be defined in multiple ways, including directly indicating