update model objs for data / results & attribute defs

Author: TomDonoghue

specparam/models/event.py

@@ -3,8 +3,8 @@
 import numpy as np
 
 from specparam.models import SpectralModel, SpectralTimeModel
-from specparam.objs.results import BaseResults3D
-from specparam.objs.data import BaseData3D
+from specparam.objs.results import Results3D
+from specparam.objs.data import Data3D
 from specparam.plts.event import plot_event_model
 from specparam.data.conversions import event_group_to_dataframe, dict_to_df
 from specparam.data.utils import flatten_results_dict
@@ -22,6 +22,7 @@
 ###################################################################################################
 
 @replace_docstring_sections([docs_get_section(SpectralModel.__doc__, 'Parameters'),
+                             docs_get_section(SpectralModel.__doc__, 'Attributes'),
                              docs_get_section(SpectralModel.__doc__, 'Notes')])
 class SpectralTimeEventModel(SpectralTimeModel):
     """Model a set of event as a combination of aperiodic and periodic components.
@@ -37,20 +38,7 @@ class SpectralTimeEventModel(SpectralTimeModel):
 
     Attributes
     ----------
-    freqs : 1d array
-        Frequency values for the power spectra.
-    spectrograms : 3d array
-        Power values for the spectrograms, organized as [n_events, n_freqs, n_time_windows].
-        Power values are stored internally in log10 scale.
-    freq_range : list of [float, float]
-        Frequency range of the power spectra, as [lowest_freq, highest_freq].
-    freq_res : float
-        Frequency resolution of the power spectra.
-    event_group_results : list of list of FitResults
-        Full model results collected across all events and models.
-    event_time_results : dict
-        Results of the model fit across each time window, collected across events.
-        Each value in the dictionary stores a model fit parameter, as [n_events, n_time_windows].
+    % copied in from SpectralModel object
 
     Notes
     -----
@@ -69,9 +57,9 @@ def __init__(self, *args, **kwargs):
                                    verbose=kwargs.pop('verbose', True),
                                    **kwargs)
 
-        self.data = BaseData3D()
+        self.data = Data3D()
 
-        self.results = BaseResults3D(modes=self.modes,
+        self.results = Results3D(modes=self.modes,
                                      metrics=kwargs.pop('metrics', None),
                                      bands=kwargs.pop('bands', None))
 

specparam/models/group.py

@@ -8,8 +8,8 @@
 import numpy as np
 
 from specparam.models import SpectralModel
-from specparam.objs.data import BaseData2D
-from specparam.objs.results import BaseResults2D
+from specparam.objs.data import Data2D
+from specparam.objs.results import Results2D
 from specparam.objs.utils import run_parallel_group, pbar
 from specparam.plts.group import plot_group_model
 from specparam.io.models import save_group
@@ -25,6 +25,7 @@
 ###################################################################################################
 
 @replace_docstring_sections([docs_get_section(SpectralModel.__doc__, 'Parameters'),
+                             docs_get_section(SpectralModel.__doc__, 'Attributes'),
                              docs_get_section(SpectralModel.__doc__, 'Notes')])
 class SpectralGroupModel(SpectralModel):
 
@@ -41,27 +42,7 @@ class SpectralGroupModel(SpectralModel):
 
     Attributes
     ----------
-    freqs : 1d array
-        Frequency values for the power spectra.
-    power_spectra : 2d array
-        Power values for the group of power spectra, as [n_power_spectra, n_freqs].
-        Power values are stored internally in log10 scale.
-    freq_range : list of [float, float]
-        Frequency range of the power spectra, as [lowest_freq, highest_freq].
-    freq_res : float
-        Frequency resolution of the power spectra.
-    group_results : list of FitResults
-        Results of the model fit for each power spectrum.
-    has_data : bool
-        Whether data is loaded to the object.
-    has_model : bool
-        Whether model results are available in the object.
-    n_peaks_ : int
-        The number of peaks fit in the model.
-    n_null_ : int
-        The number of models that failed to fit and/or that are marked as null.
-    null_inds_ : list of int
-        The indices of any models that are null.
+    % copied in from SpectralModel object
 
     Notes
     -----
@@ -85,9 +66,9 @@ def __init__(self, *args, **kwargs):
                                verbose=kwargs.pop('verbose', True),
                                **kwargs)
 
-        self.data = BaseData2D()
+        self.data = Data2D()
 
-        self.results = BaseResults2D(modes=self.modes,
+        self.results = Results2D(modes=self.modes,
                                      metrics=kwargs.pop('metrics', None),
                                      bands=kwargs.pop('bands', None))
 
@@ -267,7 +248,7 @@ def load(self, file_name, file_path=None):
         self._reset_data_results(clear_spectrum=True, clear_results=True)
 
 
-    @copy_doc_func_to_method(BaseResults2D.get_params)
+    @copy_doc_func_to_method(Results2D.get_params)
     def get_params(self, name, field=None):
 
         return self.results.get_params(name, field)

specparam/models/model.py

@@ -8,8 +8,8 @@
 import numpy as np
 
 from specparam.models.base import BaseModel
-from specparam.objs.data import BaseData
-from specparam.objs.results import BaseResults
+from specparam.objs.data import Data
+from specparam.objs.results import Results
 from specparam.algorithms.spectral_fit import SpectralFitAlgorithm, SPECTRAL_FIT_SETTINGS
 from specparam.reports.save import save_model_report
 from specparam.reports.strings import gen_model_results_str
@@ -47,49 +47,25 @@ class SpectralModel(BaseModel):
 
     Attributes
     ----------
-    freqs : 1d array
-        Frequency values for the power spectrum.
-    power_spectrum : 1d array
-        Power values, stored internally in log10 scale.
-    freq_range : list of [float, float]
-        Frequency range of the power spectrum, as [lowest_freq, highest_freq].
-    freq_res : float
-        Frequency resolution of the power spectrum.
-    modeled_spectrum_ : 1d array
-        The full model fit of the power spectrum, in log10 scale.
-    aperiodic_params_ : 1d array
-        Fitted parameter values that define the aperiodic fit. As [Offset, (Knee), Exponent].
-        The knee parameter is only included if aperiodic component is fit with a knee.
-    peak_params_ : 2d array
-        Fitted parameter values for the peaks. Each row is a peak, as [CF, PW, BW].
-    gaussian_params_ : 2d array
-        Fitted parameter values that define the gaussian fit(s).
-        Each row is a gaussian, as [mean, height, standard deviation].
-    r_squared_ : float
-        R-squared of the fit between the input power spectrum and the full model fit.
-    error_ : float
-        Error of the full model fit.
-    n_peaks_ : int
-        The number of peaks fit in the model.
-    has_data : bool
-        Whether data is loaded to the object.
-    has_model : bool
-        Whether model results are available in the object.
-    _debug : bool
-        Whether the object is set in debug mode.
-        If in debug mode, an error is raised if model fitting is unsuccessful.
-        This should be controlled by using the `set_debug` method.
+    algorithm : Algorithm
+        Algorithm object with model fitting settings and procedures.
+    modes : Modes
+        Modes object with fit mode definitions.
+    data : Data
+        Data object with spectral data and metadata.
+    results : Results
+        Results object with model fit results and metrics.
 
     Notes
     -----
-    - Commonly used abbreviations used in this module include:
-      CF: center frequency, PW: power, BW: Bandwidth, AP: aperiodic
     - Input power spectra must be provided in linear scale.
       Internally they are stored in log10 scale, as this is what the model operates upon.
     - Input power spectra should be smooth, as overly noisy power spectra may lead to bad fits.
       For example, raw FFT inputs are not appropriate. Where possible and appropriate, use
       longer time segments for power spectrum calculation to get smoother power spectra,
       as this will give better model fits.
+    - Commonly used abbreviations used in this module include:
+      CF: center frequency, PW: power, BW: Bandwidth, AP: aperiodic
     - The gaussian params are those that define the gaussian of the fit, where as the peak
       params are a modified version, in which the CF of the peak is the mean of the gaussian,
       the PW of the peak is the height of the gaussian over and above the aperiodic component,
@@ -106,9 +82,9 @@ def __init__(self, peak_width_limits=(0.5, 12.0), max_n_peaks=np.inf, min_peak_h
                            periodic_mode=periodic_mode,
                            verbose=verbose)
 
-        self.data = BaseData()
+        self.data = Data()
 
-        self.results = BaseResults(modes=self.modes, metrics=metrics, bands=bands)
+        self.results = Results(modes=self.modes, metrics=metrics, bands=bands)
 
         self.algorithm = SpectralFitAlgorithm(
             peak_width_limits=peak_width_limits, max_n_peaks=max_n_peaks,
@@ -117,8 +93,8 @@ def __init__(self, peak_width_limits=(0.5, 12.0), max_n_peaks=np.inf, min_peak_h
             debug=debug, **model_kwargs)
 
 
-    @replace_docstring_sections([docs_get_section(BaseData.add_data.__doc__, 'Parameters'),
-                                 docs_get_section(BaseData.add_data.__doc__, 'Notes')])
+    @replace_docstring_sections([docs_get_section(Data.add_data.__doc__, 'Parameters'),
+                                 docs_get_section(Data.add_data.__doc__, 'Notes')])
     def add_data(self, freqs, power_spectrum, freq_range=None, clear_results=True):
         """Add data (frequencies, and power spectrum values) to the current object.
 
@@ -311,7 +287,7 @@ def load(self, file_name, file_path=None, regenerate=True):
                 self.results._regenerate_model(self.data.freqs)
 
 
-    @copy_doc_func_to_method(BaseResults.get_params)
+    @copy_doc_func_to_method(Results.get_params)
     def get_params(self, name, field=None):
 
         return self.results.get_params(name, field)

specparam/models/time.py

@@ -1,8 +1,8 @@
 """Time model object and associated code for fitting the model to spectrograms."""
 
 from specparam.models import SpectralModel, SpectralGroupModel
-from specparam.objs.results import BaseResults2DT
-from specparam.objs.data import BaseData2DT
+from specparam.objs.results import Results2DT
+from specparam.objs.data import Data2DT
 from specparam.data.conversions import group_to_dataframe, dict_to_df
 from specparam.data.utils import get_results_by_ind
 from specparam.io.models import save_time
@@ -17,6 +17,7 @@
 ###################################################################################################
 
 @replace_docstring_sections([docs_get_section(SpectralModel.__doc__, 'Parameters'),
+                             docs_get_section(SpectralModel.__doc__, 'Attributes'),
                              docs_get_section(SpectralModel.__doc__, 'Notes')])
 class SpectralTimeModel(SpectralGroupModel):
     """Model a spectrogram as a combination of aperiodic and periodic components.
@@ -32,17 +33,7 @@ class SpectralTimeModel(SpectralGroupModel):
 
     Attributes
     ----------
-    freqs : 1d array
-        Frequency values for the spectrogram.
-    spectrogram : 2d array
-        Power values for the spectrogram, as [n_freqs, n_time_windows].
-        Power values are stored internally in log10 scale.
-    freq_range : list of [float, float]
-        Frequency range of the spectrogram, as [lowest_freq, highest_freq].
-    freq_res : float
-        Frequency resolution of the spectrogram.
-    time_results : dict
-        Results of the model fit across each time window.
+    % copied in from SpectralModel object
 
     Notes
     -----
@@ -66,9 +57,9 @@ def __init__(self, *args, **kwargs):
                                     verbose=kwargs.pop('verbose', True),
                                     **kwargs)
 
-        self.data = BaseData2DT()
+        self.data = Data2DT()
 
-        self.results = BaseResults2DT(modes=self.modes,
+        self.results = Results2DT(modes=self.modes,
                                       metrics=kwargs.pop('metrics', None),
                                       bands=kwargs.pop('bands', None))