Merge pull request #284 from fooof-tools/docs

[DOC] - Update documentation

doc/conf.py

@@ -100,6 +100,7 @@
         ("Motivations", "auto_motivations/index"),
         ("Tutorials", "auto_tutorials/index"),
         ("Examples", "auto_examples/index"),
+        ("Visualizers", "visualizers"),
         ("Reference", "reference"),
         ("GitHub", "https://github.com/fooof-tools/fooof", True),
     ],
@@ -125,8 +126,9 @@
 sphinx_gallery_conf = {
     'examples_dirs': ['../examples', '../tutorials', '../motivations'],
     'gallery_dirs': ['auto_examples', 'auto_tutorials', 'auto_motivations'],
-    'subsection_order' : ExplicitOrder(['../examples/manage',
-                                        '../examples/processing',
+    'subsection_order' : ExplicitOrder(['../examples/processing',
+                                        '../examples/manage',
+                                        '../examples/models',
                                         '../examples/plots',
                                         '../examples/sims',
                                         '../examples/analyses',

doc/contents.rst

@@ -9,6 +9,7 @@ Table of Contents
    glossary.rst
    reference.rst
    changelog.rst
+   visualizers.rst
    auto_tutorials/index.rst
    auto_examples/index.rst
    auto_motivations/index.rst

doc/reference.rst

@@ -30,7 +30,7 @@ The code for the simulations and applications is indexed and available in the
 `Paper repository <https://github.com/fooof-tools/Paper>`_.
 
 You can also find the full list of articles that cite the `Parameterizing Neural Power Spectra` paper at this
-`Google scholar link <https://scholar.google.com/scholar?oi=bibs&hl=en&cites=1591416229268020768,15214833138798132105,12543969463602123647>`_.
+`Google scholar link <https://scholar.google.com/scholar?cites=1871208307712966933&as_sdt=5,33&sciodt=0,33&hl=en>`_.
 
 Methods Reporting
 ~~~~~~~~~~~~~~~~~
@@ -54,7 +54,7 @@ In addition, we recommend that reports should include information on:
 Reporting Template & Example
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To assist in reporting on using FOOOF, we have created some templates for reporting on spectral parameterization methods. There are also some utilities included in the code to collected the required information. 
+To assist in reporting on using FOOOF, we have created some templates for reporting on spectral parameterization methods. There are also some utilities included in the code to collect the required information.
 
 The following box is an example of what a methods report might look like (where all of the *X*'s should be filled in with the relevant information).
 
@@ -65,6 +65,18 @@ The following box is an example of what a methods report might look like (where
     peak threshold : *XX*; and aperiodic mode : *XX*. Power spectra were parameterized across
     the frequency range *XX* to *XX* Hz.
 
+Checking module version
+~~~~~~~~~~~~~~~~~~~~~~~
+
+If you are not sure which version of the module you have installed, you can
+check the `__version__` from Python, using the following code:
+
+.. code-block:: python
+
+    # Check the version of the tool
+    from fooof import __version__ as fooof_version
+    print('Current fooof version:', fooof_version)
+
 Generating Methods Reports
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 

doc/visualizers.rst

@@ -0,0 +1,14 @@
+Visualizers
+===========
+
+This page includes animated visualizers to explore topics related to spectral parameterization.
+
+The source code to create these visualizations is in the
+`visualizers repository <https://github.com/fooof-tools/Visualizers/>`_.
+
+Spectral Rotation
+-----------------
+
+Animated visualizer showing spectral rotation, emphasizing why offset and exponent are often correlated:
+
+.. image:: https://raw.githubusercontent.com/fooof-tools/Visualizers/main/gifs/specrot.gif

examples/manage/plot_data_exporting.py

@@ -0,0 +1,174 @@
+"""
+Exporting Model Results
+=======================
+
+This example covers utilities for extracting and exporting model fit results.
+
+Note that the functionality to export to pandas DataFrames was added in version 1.1,
+and requires the optional dependency `pandas` to be installed.
+"""
+
+###################################################################################################
+
+# Import model objects, and Bands object to define bands of interest
+from fooof import FOOOF, FOOOFGroup, Bands
+
+# Import simulation functions to create some example data
+from fooof.sim import gen_power_spectrum, gen_group_power_spectra
+
+###################################################################################################
+# Exporting Results
+# -----------------
+#
+# In this example we will explore available functionality for extracting model fit results,
+# specifically the options available for exporting results to pandas objects.
+#
+# Note that the main use case of exporting models to pandas DataFrames is for
+# analysis across models. If you are just trying to access the model fit results from
+# a fit model, you may want the :meth:`~fooof.FOOOF.get_results` and/or
+# :meth:`~fooof.FOOOF.get_params` methods.
+#
+# Defining Oscillation Bands
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~
+#
+# A difficulty with exporting and collecting model results across model fits is that the
+# models may be different sizes - most notably, they may contain different numbers of peaks.
+#
+# This means that we need to define some kind of strategy to organize the peak
+# parameters across different models. Across these examples, this will include using the
+# :class:`~fooof.Bands` object to define oscillations bands of interest.
+#
+
+###################################################################################################
+
+# Initialize bands object, defining alpha band
+bands1 = Bands({'alpha' : [7, 14]})
+
+# Initialize model object
+fm = FOOOF()
+
+###################################################################################################
+
+# Simulate example power spectrum
+freqs, powers = gen_power_spectrum([1, 50], [0, 10, 1], [10, 0.25, 2], freq_res=0.25)
+
+# Fit model to power spectrum
+fm.fit(freqs, powers)
+
+###################################################################################################
+#
+# The :meth:`~fooof.FOOOF.to_df` method supports exporting model fit results to pandas objects.
+#
+
+###################################################################################################
+
+# Export results
+fm.to_df(None)
+
+###################################################################################################
+#
+# In the above, we export the model fit results to a pandas Series.
+#
+# Note that we explicitly passed in `None` to the `peak_org` argument, meaning we did not define
+# a strategy for managing peaks. Because of this, the export did not include any peak parameters.
+#
+# Next, let's can try exporting again, this time passing in an integer to define the number
+# of peaks to extract.
+#
+
+###################################################################################################
+
+# Export results - extracting 1 peak
+fm.to_df(1)
+
+###################################################################################################
+# Using Band Definitions
+# ~~~~~~~~~~~~~~~~~~~~~~
+#
+# In the above, we extract the results specifying to extract 1 peak. By default, this approach
+# will extract the dominant (highest power) peak.
+#
+# Notably, specifying a set number of peaks to extract does allow for combining across peaks
+# (in terms of enforcing the same model size), but may not be the ideal way to examine across
+# peaks (since the dominant extract peak may vary across model fits).
+#
+# Therefore, we may often want to instead define a set of band definitions to organize peaks,
+# as can be done by passing a `Bands` object in to the `to_df` method.
+#
+
+###################################################################################################
+
+# Export results - extracting peaks based on bands object
+fm.to_df(bands1)
+
+###################################################################################################
+#
+# Note that there are limitations to using the bands definitions - notably that doing so
+# necessarily requires extracting at most 1 peak per band. In doing so, the extraction will
+# select the dominant peak per band. However, this may not fully reflect the full model fit
+# if there are, for example, multiple peaks fit within a band.
+#
+
+###################################################################################################
+# Example on Group Object
+# ~~~~~~~~~~~~~~~~~~~~~~~
+#
+# In the above, we used the model object to show the basic exporting functionalities.
+#
+# This functionality is more useful when considering multiple model fits together, such
+# as can be done using the :meth:`~fooof.FOOOFGroup.to_df` method from the Group object,
+# which allows for exporting DataFrames of organized model fit parameters across power spectra.
+#
+# As with the above, keep in mind that for some cases you may want the
+# :meth:`~fooof.FOOOFGroup.get_results` and/or :meth:`~fooof.FOOOFGroup.get_params` methods
+# instead of doing a DataFrame export.
+#
+
+###################################################################################################
+
+# Simulate an example group of power spectra
+freqs, powers = gen_group_power_spectra(5, [1, 50], [0, 1], [10, 0.25, 2])
+
+# Initialize a group model object and fit power spectra
+fg = FOOOFGroup(verbose=False)
+fg.fit(freqs, powers)
+
+###################################################################################################
+
+# Export results to dataframe, with no peak definition
+fg.to_df(None)
+
+###################################################################################################
+
+# Export results to dataframe, specifying to export a single peak
+fg.to_df(1)
+
+###################################################################################################
+
+# Export results to dataframe, using bands definition with defines the alpha band
+fg.to_df(bands1)
+
+###################################################################################################
+#
+# In the above examples, we showed the same exports on the Group object as we previously
+# explored on the single spectrum in the model object.
+#
+# Note that we can also define new bands objects to change the peak output organization,
+# as demonstrated in the following example.
+#
+
+###################################################################################################
+
+# Define a new bands object, specifying both the alpha and beta band
+bands2 = Bands({'alpha' : [7, 14],
+                'beta' : [15, 30]})
+
+###################################################################################################
+
+# Export results to dataframe, using bands object with alpha & beta
+fg.to_df(bands2)
+
+###################################################################################################
+#
+# That covers the pandas export functionality available from the model objects.
+#

examples/models/README.txt

@@ -0,0 +1,4 @@
+Models & Parameters
+-------------------
+
+Examples of evaluating and exploring model fits and parameters.