[WIP] - Update tutorials

specparam/metrics/definitions.py

@@ -71,3 +71,11 @@
     'gof_adjrsquared' : gof_adjrsquared,
 
 }
+
+
+def check_metrics():
+    """Check the set of available metrics."""
+
+    print('Available metrics:')
+    for metric in METRICS.values():
+        print('    {:8s} {:12s} : {:s}'.format(metric.category, metric.measure, metric.description))

tutorials/plot_01-ModelDescription.py

@@ -2,7 +2,7 @@
 01: Model Description
 =====================
 
-A description of and introduction to the power spectrum model.
+A description of and introduction to the spectral parameterization module.
 """
 
 ###################################################################################################
@@ -11,8 +11,8 @@
 #
 # Welcome to the tutorials!
 #
-# In this first tutorial, we will introduce an overview and description of power spectrum
-# model, as well as visualizing some examples.
+# In this first tutorial, we will introduce an overview and description of the
+# spectral parameterization module, as well as visualizing some examples.
 #
 # Keep in mind as you go, that if you want more information that describes, motivates, and
 # justifies our modeling approach, you can also check out the associated
@@ -29,15 +29,15 @@
 # First, we will import and run some code to simulate some example power spectra, and
 # fit some power spectrum models to them, to use as examples.
 #
-# For the purpose of this tutorial, you don't need to know how this code works
-# yet, and can skip past reading the code itself.
+# Note that for the purpose of this tutorial, you don't need to know exactly how this code works
+# yet, as the details of what is happening will be clarified across the rest of the tutorials.
 #
 
 ###################################################################################################
 
 # sphinx_gallery_thumbnail_number = 5
 
-# Import required code for visualizing example models
+# Import required code for simulating and visualizing example models
 from specparam import SpectralModel
 from specparam.sim import sim_power_spectrum
 from specparam.sim.utils import set_random_seed
@@ -207,26 +207,6 @@
 # to describe this component of the data.
 #
 
-###################################################################################################
-# Mathematical Description of the Periodic Component
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# To fit this periodic activity - the regions of power over above the aperiodic component,
-# or 'peaks' - the model uses Gaussians. As we've seen, there can be multiple peaks in the model.
-#
-# Each Gaussian, :math:`n`, referred to as :math:`G(F)_n`, is of the form:
-#
-# .. math::
-#    G(F)_n = a * exp (\frac{- (F - c)^2}{2 * w^2})
-#
-# This describes each peak in terms of parameters `a`, `c` and `w`, where:
-#
-# - :math:`a` is the height of the peak, over and above the aperiodic component
-# - :math:`c` is the center frequency of the peak
-# - :math:`w` is the width of the peak
-# - :math:`F` is the array of frequency values
-#
-
 ###################################################################################################
 # Aperiodic Component
 # -------------------
@@ -257,43 +237,6 @@
 # Note that diagonal labels indicate unit-less measures (in neither units of frequency or power).
 #
 
-###################################################################################################
-# Mathematical Description of the Aperiodic Component
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# To fit the aperiodic component, we will use the function :math:`L`:
-#
-# .. math::
-#    L(F) = b - \log(k + F^\chi)
-#
-# Note that this function is fit on the semi-log power spectrum, meaning linear frequencies
-# and :math:`log_{10}` power values.
-#
-# In this formulation, the parameters :math:`b`, :math:`k`, and :math:`\chi`
-# define the aperiodic component, as:
-#
-# - :math:`b` is the broadband 'offset'
-# - :math:`k` is the 'knee'
-# - :math:`\chi` is the 'exponent' of the aperiodic fit
-# - :math:`F` is the array of frequency values
-#
-# Note that fitting the knee parameter is optional. If used, the knee parameter defines a
-# 'bend' in the aperiodic `1/f` like component of the data. If not used, the 'knee'
-# parameter is set to zero.
-#
-# This function form is technically described as a Lorentzian function. We use the option
-# of adding a knee parameter, since even though neural data is often discussed in terms
-# of having `1/f` activity, there is often not a single `1/f` characteristic, especially
-# across broader frequency ranges. Therefore, using this function form allows for modeling
-# bends in the power spectrum of the aperiodic component, if and when they occur.
-#
-# Note that if we were to want the equivalent function in linear power, using :math:`AP`
-# to indicate the aperiodic component in linear spacing, it would be:
-#
-# .. math::
-#    AP(F) = 10^b * \frac{1}{(k + F^\chi)}
-#
-
 ###################################################################################################
 # A Note on Logging
 # ~~~~~~~~~~~~~~~~~
@@ -316,33 +259,6 @@
 # Plot the power spectrum model, in log-log space
 plot_annotated_model(fm1, plt_log=True)
 
-###################################################################################################
-# Relating Exponents to Power Spectrum Slope
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# Another way to measure 1/f properties in neural power spectra is to measure the slope
-# of the spectrum in log-log spacing, fitting a linear equation as:
-#
-# .. math::
-#    L(log(F)) = aF + b
-#
-# Where:
-#
-# - :math:`a` is the power spectrum slope
-# - :math:`b` is the offset
-# - :math:`F` is the array of frequency values
-#
-# In this formulation, the data is considered in log-log space, meaning the frequency values
-# are also in log space. Since 1/f is a straight line in log-log spacing, this approach captures
-# 1/f activity.
-#
-# This is equivalent to the power spectrum model in this module, when fitting with no knee,
-# with a direct relationship between the slope (:math:`a`) and the exponent (:math:`\chi`):
-#
-# .. math::
-#    \chi = -a
-#
-
 ###################################################################################################
 # Fitting Knees
 # ~~~~~~~~~~~~~
@@ -374,14 +290,19 @@
 #
 # So far, we have explored how neural power spectra, :math:`NPS`, across a set of frequencies
 # :math:`F` can be modeled as a combination of an aperiodic component, :math:`L`, and the
-# periodic component, which is comprised of `N` peaks, where each :math:`G_n` is a Gaussian.
+# periodic component (P), which is comprised of a group of `N` peaks.
 #
-# To summarize, the full model is:
+# To summarize, the full model, in abstract terms, is:
 #
 # .. math::
-#    NPS(F) = L(F) + G(F)_n
+#    NPS(F) = L(F) + P(F)_n
+#
+# In further tutorials we will dig into the details of choosing specific fit functions
+# to instantiate this model. For now, using the defaults as above, we have
+# been fitting a model that uses fits the the aperiodic component as a Lorentzian,
+# and the periodic component as Gaussians.
 #
-# where:
+# Using these fit functions, the model has this form:
 #
 # .. math::
 #    L(F) = b - \log(k + F^\chi) \quad \quad G(F)_n = a * exp (\frac{- (F - c)^2}{2 * w^2})

tutorials/plot_02-PSDModel.py

@@ -177,41 +177,6 @@
 print(template.format(error=err, exponent=exp,
                       cfs=' & '.join(map(str, [round(cf, 2) for cf in cfs]))))
 
-###################################################################################################
-# Notes on Interpreting Peak Parameters
-# -------------------------------------
-#
-# Peak parameters are labeled as:
-#
-# - CF: center frequency of the extracted peak
-# - PW: power of the peak, over and above the aperiodic component
-# - BW: bandwidth of the extracted peak
-#
-# Note that the peak parameters that are returned are not exactly the same as the
-# parameters of the Gaussians used internally to fit the peaks.
-#
-# Specifically:
-#
-# - CF is the exact same as mean parameter of the Gaussian
-# - PW is the height of the model fit above the aperiodic component [1],
-#   which is not necessarily the same as the Gaussian height
-# - BW is 2 * the standard deviation of the Gaussian [2]
-#
-# [1] Since the Gaussians are fit together, if any Gaussians overlap,
-# than the actual height of the fit at a given point can only be assessed
-# when considering all Gaussians. To be better able to interpret heights
-# for individual peaks, we re-define the peak height as above, and label it
-# as 'power', as the units of the input data are expected to be units of power.
-#
-# [2] Gaussian standard deviation is '1 sided', where as the returned BW is '2 sided'.
-#
-
-###################################################################################################
-#
-# The underlying gaussian parameters are also available from the model object,
-# in the ``gaussian_params_`` attribute.
-#
-
 ###################################################################################################
 
 # Compare the 'peak_params_' to the underlying gaussian parameters

tutorials/plot_03-Algorithm.py

@@ -273,27 +273,27 @@
 #
 # Stored model components:
 #
-# - Aperiodic Component: ``_ap_fit``
+# - Aperiodic Component (``SpectralModel.results.model.get_component('aperiodic')``)
 #
 #   - This is the aperiodic-only fit of the data.
 #   - It is computed by generating a reconstruction of the measured aperiodic parameters
 #
-# - Periodic Component: ``_peak_fit``
+# - Periodic Component: (``SpectralModel.results.model.get_component('peak')``)
 #
 #   - This is the periodic-only (or peak) fit of the data.
 #   - It is computed by generating a reconstruction of the measured periodic (peak) parameters
 #
 # Stored data attributes:
 #
-# - Flattened Spectrum: ``_spectrum_flat``
+# - Flattened Spectrum: (``SpectralModel.get_data('aperiodic')``)
 #
 #   - The original data, with the aperiodic component removed
-#   - This is computed as ``power_spectrum`` - ``_ap_fit``
+#   - This is computed as the power_spectrum minus the model aperiodic fit
 #
-# - Peak Removed Spectrum: ``_spectrum_peak_rm``
+# - Peak Removed Spectrum: (``SpectralModel.get_data('aperiodic')``)
 #
 #   - The original data, with the periodic component (peaks) removed
-#   - This is computed as ``power_spectrum`` - ``_peak_fit``
+#   - This is computed as the power_spectrum minus the model peak fit
 #
 
 ###################################################################################################