fooof-tools · TomDonoghue · Jun 11, 2026 · Jun 11, 2026 · Jun 11, 2026 · Jun 11, 2026
diff --git a/doc/conf.py b/doc/conf.py
@@ -143,7 +143,8 @@ def setup(app):
                                         '../examples/sims',
                                         '../examples/analyses',
                                         '../motivations/concepts',
-                                        '../motivations/measurements']),
+                                        '../motivations/measurements',
+                                        '../motivations/models']),
     'within_subsection_order': FileNameSortKey,
     'default_thumb_file': 'img/spectrum.png',
     'backreferences_dir': 'generated',   # Where to drop linking files between examples & API

diff --git a/doc/visualizers.rst b/doc/visualizers.rst
@@ -6,6 +6,13 @@ This page includes animated visualizers to explore topics related to spectral pa
 The source code to create these visualizations is in the
 `visualizers repository <https://github.com/fooof-tools/Visualizers/>`_.
 
+Fitting Algorithm
+-----------------
+
+Animated visualizer showing the fitting algorithm:
+
+.. image:: https://raw.githubusercontent.com/fooof-tools/Visualizers/main/gifs/specparam-algorithm.gif
+
 Spectral Rotation
 -----------------
 

diff --git a/examples/analyses/plot_clinical_analyses.py b/examples/analyses/plot_clinical_analyses.py
@@ -0,0 +1,62 @@
+"""
+Clinical Analyses
+=================
+
+An overview of clinically-related analyses using spectral parameterization.
+
+This overview draws from recommendations from a review on analysis of aperiodic activity
+in clinical applications, which also discusses a series of recommendations.
+
+.. seealso::
+
+    Reference for the full project on reviewing clinical examinations of aperiodic activity:
+
+    Donoghue T (2025). A systematic review of aperiodic neural activity in
+    clinical investigations. European Journal of Neuroscience, 62(7), e70255.
+    https://doi.org/10.1111/ejn.70255
+
+For more information, find the full project in the
+`journal article <https://doi.org/10.1111/ejn.70255>`_ and/or the
+`Github repository <https://github.com/TomDonoghue/AperiodicClinical>`_.
+
+If you wish to reference this example or use guidelines from it,
+please cite the associated paper.
+"""
+
+###################################################################################################
+# Introduction
+# ------------
+#
+# Words, words, words.
+#
+
+###################################################################################################
+# Group-Level Analyses
+# --------------------
+#
+#
+
+###################################################################################################
+# Evaluating Model Fit Quality
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#
+#
+
+###################################################################################################
+# Visualizing Results
+# ~~~~~~~~~~~~~~~~~~~
+#
+#
+
+###################################################################################################
+# Checklist of Recommendations
+# ----------------------------
+#
+#
+
+###################################################################################################
+# Conclusion
+# ----------
+#
+# Words, words, words.
+#
diff --git a/examples/analyses/plot_dev_demo.py b/examples/analyses/plot_dev_demo.py
@@ -3,21 +3,33 @@
 =======================
 
 An example analysis applied to developmental data, demonstrating best practices.
+
+This guide is part of a broader project on
+'Spectral parameterization for studying neurodevelopment: how and why'.
+
+.. seealso::
+
+    Reference for the full project on best-practices for parameterizing developmental data:
+
+    Ostlund B, Donoghue T, Anaya B, Gunther KE, Karalunas SL, Voytek B, Pérez-Edgar KE (2022).
+    Spectral parameterization for studying neurodevelopment: How and why.
+    Developmental Cognitive Neuroscience, 54, 101073.
+    https://doi.org/10.1016/j.dcn.2022.101073
+
+For more information, find the full project in the
+`journal article <https://doi.org/10.1016/j.dcn.2022.101073>`_ and/or the
+`Github repository <https://github.com/fooof-tools/DevelopmentalDemo/>`_.
+
+If you wish to reference this example or use guidelines from it,
+please cite the associated paper.
 """
 
 ###################################################################################################
 # Spectral Parameterization for studying neurodevelopment
 # -------------------------------------------------------
 #
-# This example is adapted from the
-# `Developmental Data Demo <https://github.com/fooof-tools/DevelopmentalDemo/>`_.
-#
-# If you wish to reference this example or use guidelines from it, please cite the associated
-# paper `Spectral parameterization for studying neurodevelopment: how and why` by
-# Brendan Ostlund, Thomas Donoghue, Berenice Anaya, Kelley E Gunther, Sarah L Karalunas,
-# Bradley Voytek, and Koraly E Pérez-Edgar.
-#
-# Paper link: https://doi.org/10.1016/j.dcn.2022.101073
+# This guide provides an overview of best-practice guidelines and considerations for applying
+# spectral parameterization to developmental data.
 #
 
 ###################################################################################################
@@ -678,6 +690,5 @@
 # For more on this topic, see the
 # `DevelopmentalDemo repository <https://github.com/fooof-tools/DevelopmentalDemo/>`_
 # and/or the
-# `associated paper  <https://doi.org/10.1016/j.dcn.2022.101073>`_
-# for further information.
+# `associated paper  <https://doi.org/10.1016/j.dcn.2022.101073>`_.
 #
diff --git a/motivations/README.txt b/motivations/README.txt
@@ -3,14 +3,15 @@
 Motivations
 ===========
 
-This section explores conceptual and methodological ideas that motivate parameterizing neural power spectra.
+This section explores motivations for parameterizing neural power spectra.
 
-Using code examples, topics are organized into:
+Using code-driven examples, topics are organized into:
 
-- conceptual points about approaches for analyzing neural data and related topics in digital signal processing
-- methodological points investigating if and how current approaches may conflate different aspects of the data
+- 'concepts' : conceptual points about digital signal processing and analyzing aperiodic and periodic components
+- 'measurements' : methodological topics examining if and how measurements may conflate different components of the data
+- 'models' : theoretical models and findings relating to way to interpret aperiodic and periodic components
 
-These examples can be explored in any order.
+These topics and pages can be explored in any order.
 
 .. contents:: Contents
    :local:

diff --git a/motivations/concepts/README.txt b/motivations/concepts/README.txt
@@ -1,6 +1,9 @@
 Concepts
 --------
 
-This section seeks to motivate the idea of conceptualizing neural data as being comprised of both periodic and aperiodic activity.
+This section seeks to motivate the conceptualization of neural data as having
+periodic and aperiodic components.
 
-In particular, these examples investigate how the notion of different components in neural data relates to practices in digital signal processing, and why this motivates approaches such as parameterizing neural power spectra.
+In particular, these examples investigate how the notion of different components in neural data
+relates to practices in digital signal processing, and why this motivates approaches such as
+parameterizing neural power spectra.
diff --git a/motivations/concepts/plot_ColourfulNoises.py b/motivations/concepts/plot_ColourfulNoises.py
@@ -0,0 +1,144 @@
+"""
+Aperiodic Activity
+==================
+
+Exploring properties of aperiodic signals, with power across all frequencies.
+
+This example uses the
+`neurodsp <https://neurodsp-tools.github.io/>`_
+module for time series simulations & analyses.
+"""
+
+###################################################################################################
+# Non-Frequency Specific Power
+# ----------------------------
+#
+# colours of noise
+# synaptic noise
+# knees / multi-fractals?
+#
+
+###################################################################################################
+
+# Import numpy
+import numpy as np
+
+# ...
+from neurodsp.plts import plot_time_series
+from neurodsp.spectral import compute_spectrum_welch
+from neurodsp.sim import sim_powerlaw, set_random_seed
+
+###################################################################################################
+# Colored Noise Signals
+# ~~~~~~~~~~~~~~~~~~~~~
+#
+# Let's now look at 'noise' signals.
+#
+# In the signals below, we will simulate colored noise signals, in which samples are
+# drawn randomly from noise distributions, with no rhythmic properties.
+#
+# As we will see, in the power spectrum, these signals exhibit power at all frequencies,
+# with specific patterns of powers across frequencies, which is dependent on the 'color'
+# of the noise.
+#
+
+###################################################################################################
+# White Noise
+# ^^^^^^^^^^^
+#
+# A 'white noise' signal is one that is created with uncorrelated samples drawn from
+# a random distribution. Since each element of the signal is sampled randomly,
+# there is no consistent rhythmic structure in the signal.
+#
+
+###################################################################################################
+
+# Simulate a white noise time series signal
+white_sig = np.random.normal(0, 1, n_points)
+
+###################################################################################################
+
+# Plot the white noise time series
+plot_time_series(times, white_sig)
+
+###################################################################################################
+#
+# As before, we can compute and visualize the power spectrum of this signal.
+#
+
+###################################################################################################
+
+# Compute the power spectrum of the white noise signal
+freqs, powers = compute_spectrum_welch(white_sig, s_rate)
+
+###################################################################################################
+
+# Visualize the power spectrum of the white noise signal
+plot_power_spectra(freqs, powers)
+
+###################################################################################################
+#
+# In the frequency representation, we can see that white noise has a flat power spectrum,
+# with equal power across all frequencies. This is the definition of white noise.
+#
+# This is similar to the delta function, though note that in this case the power across
+# frequencies is representing continuous aperiodic activity, rather than a single transient.
+#
+
+###################################################################################################
+# Pink Noise
+# ^^^^^^^^^^
+#
+# Other 'colors' of noise refer to different patterns of power distributions
+# in the power spectrum.
+#
+# For example, pink noise is a signal where power systematically decreases across
+# frequencies in the power spectrum.
+#
+
+###################################################################################################
+
+# Simulate a pink noise signal
+pink_sig = sim_powerlaw(n_seconds, s_rate, exponent=-1)
+
+###################################################################################################
+
+# Plot the pink noise time series
+plot_time_series(times, pink_sig)
+
+###################################################################################################
+
+# Compute the power spectrum of the pink noise signal
+freqs, powers = compute_spectrum_welch(pink_sig, s_rate)
+
+###################################################################################################
+
+# Visualize the power spectrum of the pink noise signal
+plot_power_spectra(freqs, powers)
+
+###################################################################################################
+# Section Conclusion
+# ^^^^^^^^^^^^^^^^^^
+#
+# The 'colored noise' signals above are simulated signals with no rhythmic properties,
+# in the sense that there are no characteristic frequencies or visible rhythms in the data.
+#
+# Nevertheless, and by definition, in the power spectra of such signals, there is power across
+# all frequencies, with some pattern of power across frequencies.
+#
+# However, there are no frequencies at which power is different from expected from an
+# aperiodic noise signal. These signals are statistically, by definition, aperiodic.
+#
+
+
+
+###################################################################################################
+
+
+###################################################################################################
+
+
+###################################################################################################
+
+
+###################################################################################################