Small fixes on tutorials

Author: TomDonoghue

tutorials/plot_01-ModelDescription.py

@@ -2,7 +2,7 @@
 01: Model Description
 =====================
 
-A description and introduction to the power spectrum model.
+A description of and introduction to the power spectrum model.
 """
 
 ###################################################################################################
@@ -57,15 +57,15 @@
 
 ###################################################################################################
 
-# Initialize a power spectrum models and fit the power spectra
+# Initialize power spectrum model objects and fit the power spectra
 fm1 = FOOOF(min_peak_height=0.05, verbose=False)
 fm2 = FOOOF(min_peak_height=0.05, aperiodic_mode='knee', verbose=False)
 fm1.fit(freqs1, powers1)
 fm2.fit(freqs2, powers2)
 
 ###################################################################################################
 #
-# Now, we have some data & models to work with.
+# Now, we have some data and models to work with.
 #
 # To start with, we can plot one of our simulated power spectra.
 #
@@ -74,8 +74,8 @@
 #
 # In the plot, we see a power spectrum in which there is decreasing power across increasing
 # frequencies. In some frequency regions, there is a 'peak' of power, over and above the general
-# trend across frequencies. These properties - a pattern of power across all frequencies, with
-# overlying peaks - are considered to be hallmarks of neural field data.
+# trend across frequencies. These properties - a pattern of decreasing power across frequencies,
+# with overlying peaks - are considered to be hallmarks of neural field data.
 #
 
 ###################################################################################################
@@ -96,7 +96,7 @@
 #
 # By components, we mean that we are going to conceptualize neural field data as consisting
 # of a combination of periodic (oscillatory) and aperiodic activity. Restated, we could say
-# that neural data contains both periodic and aperiodic components (or activity).
+# that neural data contains both periodic and aperiodic components.
 #
 # The goal of the model is to measure these components, separately and explicitly,
 # from frequency representations of neural field data (neural power spectra).
@@ -124,21 +124,21 @@
 # Given the full model, in red, we can then describe this spectrum in terms of the
 # 'components' that make up the model fit, which are:
 #
-# - `aperiodic`: activity, with no characteristic frequency (or 'non-frequency specific' activity)
+# - `aperiodic`: activity with no characteristic frequency (or 'non-frequency specific' activity)
 #
 #   - in power spectra, this looks like a trend across all frequencies
-#   - in the plot above, this is what's captured by the dashed blue line
-# - `periodic` : activity, with a characteristic frequency
+#   - in the plot above, this is what is captured by the dashed blue line
+# - `periodic` : activity with a characteristic frequency
 #
 #   - in power spectra, this looks like a 'peak', or 'bump', reflecting frequency specific power
-#   - in the plot above, this is what's captured by the green shaded peaks
+#   - in the plot above, this is what is captured by the green shaded peaks
 #
-# Each of these components also has different 'features' or 'properties', that we can and
-# want to describe and measure. Since these 'features' are things that we will be fitting in
+# Each of these components also has different 'features' or 'properties', that we want to
+# describe and measure. Since these 'features' are things that we will be fitting in
 # the model, we will call them `parameters` (as in, the 'model parameters').
 #
 # The full model of the power spectrum is the combination of the two components:
-# the aperiodic component and the periodic component, which is the set of peaks.
+# the aperiodic component and the periodic component (the set of peaks).
 #
 # The goal of the model is to measure these two components, to create the full model
 # fit, in a way that accurately and quantitatively describes the data.
@@ -148,10 +148,9 @@
 # Mathematical Description of Overall Model
 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 #
-# To enact the conceptual idea and description above, we will need to formalize the
-# model described above. To do so, throughout the rest of this tutorial, we will lay out the
-# mathematical description of how neural power spectra can be modeled as a combination of
-# periodic and aperiodic activity.
+# To enact the conceptual idea described above, we will need to formalize the model. To do
+# so, throughout the rest of this tutorial, we will lay out the mathematical description of
+# how neural power spectra can be modeled as a combination of periodic and aperiodic activity.
 #
 # Overall, the goal is to describe a neural power spectrum, described as :math:`NPS`, as
 # a combination of periodic and aperiodic components. We will describe each of these
@@ -177,7 +176,7 @@
 #
 # To measure the periodic activity, we would like to describe these peaks, without our
 # measures of these peaks being influenced by co-occurring aperiodic activity.
-# This is important, since as we can see in the plots above, the aperiodic and periodic
+# This is important, since, as we can see in the plots above, the aperiodic and periodic
 # components of the data can 'overlap', in frequency space. This means the total power
 # at a given frequency may have contributions from both components. To measure periodic power,
 # specifically, we need to measure the power relative to the aperiodic component of the data.
@@ -202,7 +201,7 @@
 #
 # - the `center frequency` of the peak, in units of frequency
 # - the `power` of the peak, over the aperiodic component, in units of power
-# - the `bandwidth`, or the width of the peak, units of frequency
+# - the `bandwidth`, or the width of the peak, in units of frequency
 #
 # Wherever we detect a peak, these are the parameters that we will fit to the peak,
 # to describe this component of the data.
@@ -212,7 +211,7 @@
 # Mathematical Description of the Periodic Component
 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 #
-# To fit these periodic components - the regions of power over above the aperiodic 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:
@@ -239,7 +238,7 @@
 # the power across frequencies decreases with a :math:`\frac{1}{F^\chi}` relationship.
 #
 # To measure the aperiodic activity, we would like to describe the pattern of activity
-# across all frequencies, without our measure being influenced by any co-occurring periodic
+# across all frequencies, without our measure being influenced by co-occurring periodic
 # activity (peaks).
 #
 
@@ -274,7 +273,7 @@
 # define the aperiodic component, as:
 #
 # - :math:`b` is the broadband 'offset'
-# - :math:`k` relates to the 'knee'
+# - :math:`k` is the 'knee'
 # - :math:`\chi` is the 'exponent' of the aperiodic fit
 # - :math:`F` is the array of frequency values
 #
@@ -284,9 +283,9 @@
 #
 # 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, across broader frequency ranges, there is typically not a single
-# `1/f` characteristic. Using this form allows for modeling bends in the power spectrum of
-# the aperiodic component, if and when they occur.
+# 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:
@@ -308,7 +307,7 @@
 # not affect how the data is stored and/or how models are fit.
 #
 # Below we can see the same spectrum again, with all the annotations on, plotted in log-log.
-# The most notable difference, is that the aperiodic component is a straight line in log-log
+# The most notable difference is that the aperiodic component is a straight line in log-log
 # spacing. This is a hallmark of `1/f` activity.
 #
 

tutorials/plot_02-FOOOF.py

@@ -10,24 +10,24 @@
 # Import the FOOOF object
 from fooof import FOOOF
 
-# Import utility to download and load example data
+# Import a utility to download and load example data
 from fooof.utils.download import load_fooof_data
 
 ###################################################################################################
 
-# Download examples data files needed for this example
+# Download example data files needed for this example
 freqs = load_fooof_data('freqs.npy', folder='data')
 spectrum = load_fooof_data('spectrum.npy', folder='data')
 
 ###################################################################################################
 # FOOOF Object
 # ------------
 #
-# At the core of the module, which is object oriented, is the :class:`~fooof.FOOOF` object,
-# which holds relevant data and settings as attributes, and contains methods to run the
-# algorithm to parameterize neural power spectra.
+# At the core of the module is the :class:`~fooof.FOOOF` object, which holds relevant data
+# and settings as attributes, and contains methods to run the algorithm to parameterize
+# neural power spectra.
 #
-# The organization is similar to sklearn:
+# The organization and use of the model object is similar to scikit-learn:
 #
 # - A model object is initialized, with relevant settings
 # - The model is used to fit the data
@@ -39,7 +39,7 @@
 # ~~~~~~~~~~~~~~~~~~~~~~~~~
 #
 # The :class:`~fooof.FOOOF` object fits models to power spectra. The module itself does not
-# compute power spectra, and so computing power spectra needs to be done prior to using
+# compute power spectra. Computing power spectra needs to be done prior to using
 # the FOOOF module.
 #
 # The model is broadly agnostic to exactly how power spectra are computed. Common
@@ -79,7 +79,7 @@
 #
 # - :meth:`~fooof.FOOOF.fit`: fits the power spectrum model
 # - :meth:`~fooof.FOOOF.print_results`: prints out the results
-# - :meth:`~fooof.FOOOF.plot`: plots to data and model fit
+# - :meth:`~fooof.FOOOF.plot`: plots the data and model fit
 #
 # Each of these methods can also be called individually.
 #
@@ -100,7 +100,7 @@
 # Once the power spectrum model has been calculated, the model fit parameters are stored
 # as object attributes that can be accessed after fitting.
 #
-# Following the sklearn convention, attributes that are fit as a result of
+# Following scikit-learn conventions, attributes that are fit as a result of
 # the model have a trailing underscore, for example:
 #
 # - ``aperiodic_params_``
@@ -144,7 +144,7 @@
 # Extract a model parameter with `get_params`
 err = fm.get_params('error')
 
-# Extract parameters, indicating sub-selections of parameter
+# Extract parameters, indicating sub-selections of parameters
 exp = fm.get_params('aperiodic_params', 'exponent')
 cfs = fm.get_params('peak_params', 'CF')
 
@@ -161,7 +161,7 @@
 #
 # As a reminder, you can access the documentation for a function using '?' in a
 # Jupyter notebook (ex: `fm.get_params?`), or more generally with the `help` function
-# in general Python (ex: `help(get_params)`).
+# in general Python (ex: `help(fm.get_params)`).
 #
 
 ###################################################################################################
@@ -187,7 +187,7 @@
 # [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 single peak fits, we re-define the peak height as above, and label it
+# 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'.
@@ -237,7 +237,7 @@
 # From FOOOFResults, you can access the different results
 print('Aperiodic Parameters: \n', fres.aperiodic_params)
 
-# Check the r^2 and error of the model fit
+# Check the R^2 and error of the model fit
 print('R-squared: \n {:5.4f}'.format(fm.r_squared_))
 print('Fit error: \n {:5.4f}'.format(fm.error_))
 
@@ -248,6 +248,5 @@
 # In this tutorial, we have explored the basics of the :class:`~fooof.FOOOF` object,
 # fitting power spectrum models, and extracting parameters.
 #
-# Before we move on to controlling the fit procedure, and interpreting the results,
-# in the next tutorial, we will first explore how this model is actually fit.
+# In the next tutorial, we will explore how this algorithm actually works to fit the model.
 #

tutorials/plot_03-FOOOFAlgorithm.py

@@ -2,7 +2,7 @@
 03: Fitting Algorithm
 =====================
 
-A step by step overview of the algorithm for parameterizing neural power spectra.
+A step-by-step overview of the algorithm for parameterizing neural power spectra.
 """
 
 ###################################################################################################
@@ -16,10 +16,10 @@
 #
 # Broadly, the steps in the algorithm are:
 #
-# - 1) An initial fit of the aperiodic component is taken of the power spectrum
+# - 1) An initial fit of the aperiodic component is computed from the power spectrum
 # - 2) This aperiodic fit is subtracted from the power spectrum, creating a flattened spectrum
 # - 3) An iterative process identifies peaks in this flattened spectrum
-# - 4) A full peak fit is created of all peak candidates found
+# - 4) A full peak fit is re-fit from all of the identified peak candidates
 # - 5) The peak fit is subtracted from the original power spectrum,
 #      creating a peak-removed power spectrum
 # - 6) A final fit of the aperiodic component is taken of the peak-removed power spectrum
@@ -38,13 +38,13 @@
 from fooof import FOOOF
 
 # Import some internal functions
-#   These are used here to demonstrate the algorithm.
-#   You do not need to import these functions for standard use of the algorithm
+#   These are used here to demonstrate the algorithm
+#   You do not need to import these functions for standard usage of the module
 from fooof.sim.gen import gen_aperiodic
 from fooof.plts.spectra import plot_spectrum
 from fooof.plts.annotate import plot_annotated_peak_search
 
-# Import utility to download and load example data
+# Import a utility to download and load example data
 from fooof.utils.download import load_fooof_data
 
 ###################################################################################################
@@ -67,8 +67,8 @@
 ###################################################################################################
 #
 # Note that data can be added to a FOOOF object independent of fitting the model, using the
-# :meth:`~fooof.FOOOF.add_data` method. FOOOF objects can also be used to plot input data,
-# without having fit any models.
+# :meth:`~fooof.FOOOF.add_data` method. FOOOF objects can also be used to plot data,
+# prior to fitting any models.
 #
 
 ###################################################################################################
@@ -98,8 +98,8 @@
 # Step 1: Initial Aperiodic Fit
 # ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 #
-# We start by taking an initial aperiodic fit. The goal of this fit is to be
-# able to use this fit to remove our estimate of the aperiodic component from the data.
+# We start by taking an initial aperiodic fit. This goal of this fit is to get an initial
+# fit that is good enough to get started with the fitting process.
 #
 
 ###################################################################################################
@@ -119,9 +119,10 @@
 # Step 2: Flatten the Spectrum
 # ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 #
-# The initial fit is then used to create a flattened spectrum. The initial aperiodic
-# fit is subtracted out from the original data, leaving a flattened version of the data
-# which no longer contains the aperiodic component.
+# The initial fit is then used to create a flattened spectrum.
+#
+# The initial aperiodic fit is subtracted out from the original data, leaving a flattened
+# version of the data which no longer contains the aperiodic component.
 #
 
 ###################################################################################################
@@ -144,10 +145,10 @@
 #
 # For each iteration:
 #
-# - The maximum point of the flattened spectrum is found.
+# - The maximum point of the flattened spectrum is found
 #
 #   - If this point fails to pass the relative or absolute height threshold,
-#     the procedure halts.
+#     the procedure halts
 # - A Gaussian is fit around this maximum point
 # - This 'guess' Gaussian is then subtracted from the flatted spectrum
 # - The procedure continues to a new iteration with the new version of the flattened spectrum,
@@ -228,13 +229,26 @@
 plot_spectrum(fm.freqs, fm.fooofed_spectrum_, plt_log,
               label='Full Model', color='red')
 
+###################################################################################################
+#
+# The last stage is to calculate the goodness of fit metrics, meaning the fit error & R^2.
+#
+# At the end of the fitting process, the model object also organizes parameters, such as
+# updating gaussian parameters to be peak parameters,
+#
+# These results are part of what are stored, and printed, as the model results.
+#
+
 ###################################################################################################
 
-# The last stage is to calculate the goodness of fit metrics (fit error & R^2)
-#  and organize parameters, such as updating gaussian parameters -> peak parameters
-#  These results are part of what are stored, and printed, as the model results
+# Print out the model results
 fm.print_results()
 
+###################################################################################################
+#
+# Altogether, the full model fit is now available, and can be plotted.
+#
+
 ###################################################################################################
 
 # Plot the full model fit of the power spectrum
@@ -283,7 +297,9 @@
 # Conclusion
 # ----------
 #
-# In this tutorial we have stepped through the parameterization algorithm fitting
-# power spectrum models. Next, we will continue to explore the FOOOF object,
-# properly introducing the settings and further exploring the parameters.
+# In this tutorial we have stepped through the parameterization algorithm for fitting
+# power spectrum models.
+#
+# Next, we will continue to explore the FOOOF object by properly introducing and more
+# fully describing the settings for the algorithm.
 #