Skip to content

Commit 8be1ed2

Browse files
authored
Merge pull request #284 from fooof-tools/docs
[DOC] - Update documentation
2 parents fe7a755 + c43942c commit 8be1ed2

File tree

13 files changed

+971
-5
lines changed

13 files changed

+971
-5
lines changed

doc/conf.py

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,7 @@
100100
("Motivations", "auto_motivations/index"),
101101
("Tutorials", "auto_tutorials/index"),
102102
("Examples", "auto_examples/index"),
103+
("Visualizers", "visualizers"),
103104
("Reference", "reference"),
104105
("GitHub", "https://github.com/fooof-tools/fooof", True),
105106
],
@@ -125,8 +126,9 @@
125126
sphinx_gallery_conf = {
126127
'examples_dirs': ['../examples', '../tutorials', '../motivations'],
127128
'gallery_dirs': ['auto_examples', 'auto_tutorials', 'auto_motivations'],
128-
'subsection_order' : ExplicitOrder(['../examples/manage',
129-
'../examples/processing',
129+
'subsection_order' : ExplicitOrder(['../examples/processing',
130+
'../examples/manage',
131+
'../examples/models',
130132
'../examples/plots',
131133
'../examples/sims',
132134
'../examples/analyses',

doc/contents.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ Table of Contents
99
glossary.rst
1010
reference.rst
1111
changelog.rst
12+
visualizers.rst
1213
auto_tutorials/index.rst
1314
auto_examples/index.rst
1415
auto_motivations/index.rst

doc/reference.rst

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ The code for the simulations and applications is indexed and available in the
3030
`Paper repository <https://github.com/fooof-tools/Paper>`_.
3131

3232
You can also find the full list of articles that cite the `Parameterizing Neural Power Spectra` paper at this
33-
`Google scholar link <https://scholar.google.com/scholar?oi=bibs&hl=en&cites=1591416229268020768,15214833138798132105,12543969463602123647>`_.
33+
`Google scholar link <https://scholar.google.com/scholar?cites=1871208307712966933&as_sdt=5,33&sciodt=0,33&hl=en>`_.
3434

3535
Methods Reporting
3636
~~~~~~~~~~~~~~~~~
@@ -54,7 +54,7 @@ In addition, we recommend that reports should include information on:
5454
Reporting Template & Example
5555
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5656

57-
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.
57+
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.
5858

5959
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).
6060

@@ -65,6 +65,18 @@ The following box is an example of what a methods report might look like (where
6565
peak threshold : *XX*; and aperiodic mode : *XX*. Power spectra were parameterized across
6666
the frequency range *XX* to *XX* Hz.
6767

68+
Checking module version
69+
~~~~~~~~~~~~~~~~~~~~~~~
70+
71+
If you are not sure which version of the module you have installed, you can
72+
check the `__version__` from Python, using the following code:
73+
74+
.. code-block:: python
75+
76+
# Check the version of the tool
77+
from fooof import __version__ as fooof_version
78+
print('Current fooof version:', fooof_version)
79+
6880
Generating Methods Reports
6981
~~~~~~~~~~~~~~~~~~~~~~~~~~
7082

doc/visualizers.rst

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
Visualizers
2+
===========
3+
4+
This page includes animated visualizers to explore topics related to spectral parameterization.
5+
6+
The source code to create these visualizations is in the
7+
`visualizers repository <https://github.com/fooof-tools/Visualizers/>`_.
8+
9+
Spectral Rotation
10+
-----------------
11+
12+
Animated visualizer showing spectral rotation, emphasizing why offset and exponent are often correlated:
13+
14+
.. image:: https://raw.githubusercontent.com/fooof-tools/Visualizers/main/gifs/specrot.gif
Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
"""
2+
Exporting Model Results
3+
=======================
4+
5+
This example covers utilities for extracting and exporting model fit results.
6+
7+
Note that the functionality to export to pandas DataFrames was added in version 1.1,
8+
and requires the optional dependency `pandas` to be installed.
9+
"""
10+
11+
###################################################################################################
12+
13+
# Import model objects, and Bands object to define bands of interest
14+
from fooof import FOOOF, FOOOFGroup, Bands
15+
16+
# Import simulation functions to create some example data
17+
from fooof.sim import gen_power_spectrum, gen_group_power_spectra
18+
19+
###################################################################################################
20+
# Exporting Results
21+
# -----------------
22+
#
23+
# In this example we will explore available functionality for extracting model fit results,
24+
# specifically the options available for exporting results to pandas objects.
25+
#
26+
# Note that the main use case of exporting models to pandas DataFrames is for
27+
# analysis across models. If you are just trying to access the model fit results from
28+
# a fit model, you may want the :meth:`~fooof.FOOOF.get_results` and/or
29+
# :meth:`~fooof.FOOOF.get_params` methods.
30+
#
31+
# Defining Oscillation Bands
32+
# ~~~~~~~~~~~~~~~~~~~~~~~~~~
33+
#
34+
# A difficulty with exporting and collecting model results across model fits is that the
35+
# models may be different sizes - most notably, they may contain different numbers of peaks.
36+
#
37+
# This means that we need to define some kind of strategy to organize the peak
38+
# parameters across different models. Across these examples, this will include using the
39+
# :class:`~fooof.Bands` object to define oscillations bands of interest.
40+
#
41+
42+
###################################################################################################
43+
44+
# Initialize bands object, defining alpha band
45+
bands1 = Bands({'alpha' : [7, 14]})
46+
47+
# Initialize model object
48+
fm = FOOOF()
49+
50+
###################################################################################################
51+
52+
# Simulate example power spectrum
53+
freqs, powers = gen_power_spectrum([1, 50], [0, 10, 1], [10, 0.25, 2], freq_res=0.25)
54+
55+
# Fit model to power spectrum
56+
fm.fit(freqs, powers)
57+
58+
###################################################################################################
59+
#
60+
# The :meth:`~fooof.FOOOF.to_df` method supports exporting model fit results to pandas objects.
61+
#
62+
63+
###################################################################################################
64+
65+
# Export results
66+
fm.to_df(None)
67+
68+
###################################################################################################
69+
#
70+
# In the above, we export the model fit results to a pandas Series.
71+
#
72+
# Note that we explicitly passed in `None` to the `peak_org` argument, meaning we did not define
73+
# a strategy for managing peaks. Because of this, the export did not include any peak parameters.
74+
#
75+
# Next, let's can try exporting again, this time passing in an integer to define the number
76+
# of peaks to extract.
77+
#
78+
79+
###################################################################################################
80+
81+
# Export results - extracting 1 peak
82+
fm.to_df(1)
83+
84+
###################################################################################################
85+
# Using Band Definitions
86+
# ~~~~~~~~~~~~~~~~~~~~~~
87+
#
88+
# In the above, we extract the results specifying to extract 1 peak. By default, this approach
89+
# will extract the dominant (highest power) peak.
90+
#
91+
# Notably, specifying a set number of peaks to extract does allow for combining across peaks
92+
# (in terms of enforcing the same model size), but may not be the ideal way to examine across
93+
# peaks (since the dominant extract peak may vary across model fits).
94+
#
95+
# Therefore, we may often want to instead define a set of band definitions to organize peaks,
96+
# as can be done by passing a `Bands` object in to the `to_df` method.
97+
#
98+
99+
###################################################################################################
100+
101+
# Export results - extracting peaks based on bands object
102+
fm.to_df(bands1)
103+
104+
###################################################################################################
105+
#
106+
# Note that there are limitations to using the bands definitions - notably that doing so
107+
# necessarily requires extracting at most 1 peak per band. In doing so, the extraction will
108+
# select the dominant peak per band. However, this may not fully reflect the full model fit
109+
# if there are, for example, multiple peaks fit within a band.
110+
#
111+
112+
###################################################################################################
113+
# Example on Group Object
114+
# ~~~~~~~~~~~~~~~~~~~~~~~
115+
#
116+
# In the above, we used the model object to show the basic exporting functionalities.
117+
#
118+
# This functionality is more useful when considering multiple model fits together, such
119+
# as can be done using the :meth:`~fooof.FOOOFGroup.to_df` method from the Group object,
120+
# which allows for exporting DataFrames of organized model fit parameters across power spectra.
121+
#
122+
# As with the above, keep in mind that for some cases you may want the
123+
# :meth:`~fooof.FOOOFGroup.get_results` and/or :meth:`~fooof.FOOOFGroup.get_params` methods
124+
# instead of doing a DataFrame export.
125+
#
126+
127+
###################################################################################################
128+
129+
# Simulate an example group of power spectra
130+
freqs, powers = gen_group_power_spectra(5, [1, 50], [0, 1], [10, 0.25, 2])
131+
132+
# Initialize a group model object and fit power spectra
133+
fg = FOOOFGroup(verbose=False)
134+
fg.fit(freqs, powers)
135+
136+
###################################################################################################
137+
138+
# Export results to dataframe, with no peak definition
139+
fg.to_df(None)
140+
141+
###################################################################################################
142+
143+
# Export results to dataframe, specifying to export a single peak
144+
fg.to_df(1)
145+
146+
###################################################################################################
147+
148+
# Export results to dataframe, using bands definition with defines the alpha band
149+
fg.to_df(bands1)
150+
151+
###################################################################################################
152+
#
153+
# In the above examples, we showed the same exports on the Group object as we previously
154+
# explored on the single spectrum in the model object.
155+
#
156+
# Note that we can also define new bands objects to change the peak output organization,
157+
# as demonstrated in the following example.
158+
#
159+
160+
###################################################################################################
161+
162+
# Define a new bands object, specifying both the alpha and beta band
163+
bands2 = Bands({'alpha' : [7, 14],
164+
'beta' : [15, 30]})
165+
166+
###################################################################################################
167+
168+
# Export results to dataframe, using bands object with alpha & beta
169+
fg.to_df(bands2)
170+
171+
###################################################################################################
172+
#
173+
# That covers the pandas export functionality available from the model objects.
174+
#

examples/models/README.txt

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
Models & Parameters
2+
-------------------
3+
4+
Examples of evaluating and exploring model fits and parameters.

0 commit comments

Comments
 (0)