From c3e3e164d97ea1b4b777eefb2ed3163a8546829a Mon Sep 17 00:00:00 2001 From: Tom Donoghue Date: Fri, 17 Apr 2026 21:50:41 +0100 Subject: [PATCH] update doc ref page --- doc/reference.rst | 63 +++++++++++++++++++++++++---------------------- 1 file changed, 34 insertions(+), 29 deletions(-) diff --git a/doc/reference.rst b/doc/reference.rst index 657cec1d6..87b12902a 100644 --- a/doc/reference.rst +++ b/doc/reference.rst @@ -1,7 +1,7 @@ Reference and Reporting Information =================================== -This page describes how to reference and report on using this method for parameterizing neural power spectra, and related information. +This page describes how to reference and report the use of `specparam`, and related information. Table of Contents ----------------- @@ -9,10 +9,11 @@ Table of Contents :local: :backlinks: none -Reference -~~~~~~~~~ +Main Reference +~~~~~~~~~~~~~~ -If you use this method, and/or want to refer to our approach, examples, and discussion points, please cite the following paper: +If you use this method, and/or want to refer to our approach, examples, and discussion points, +please cite the following paper: .. topic:: Reference @@ -22,28 +23,25 @@ If you use this method, and/or want to refer to our approach, examples, and disc Direct link: https://doi.org/10.1038/s41593-020-00744-x -Example Applications -~~~~~~~~~~~~~~~~~~~~ +Note beyond describing the method, this paper also includes simulations to evaluate performance +and example analyses and applications, the code for which is also available in the +`paper repository `_. -As well as reporting on the method, the full version of the paper includes simulation work as well as example analyses and applications. -The code for the simulations and applications is indexed and available in the -`Paper repository `_. - -You can also find the full list of articles that cite the `Parameterizing Neural Power Spectra` paper at this +To explore the list of articles that cite this paper, you can use this `Google scholar link `_. Methods Reporting ~~~~~~~~~~~~~~~~~ -If you use this module and the power spectrum model in your work, there is some information you should include in the methods section. - -Specifically, we recommend including the following information in the methods section: +If you use spectral parameterization to model power spectrum, there is some information +you should include in the methods section to describe this process, including: -- The version number of the module that was used (for example 1.0.0) -- The algorithm settings that were used - - - You should report all public settings, even if default values are used +- The version of the module that was used (for example 1.0.0) - The frequency range of the data that was fit +- The fit modes and algorithm settings that were used (inclusive of all public settings, + even if default values are used) +- Any additional processes used to update parameter estimates and/or to estimate other values from + the power spectra and/or model components (e.g. if a computing power for particular band ranges) In addition, we recommend that reports should include information on: @@ -54,16 +52,19 @@ In addition, we recommend that reports should include information on: Reporting Template & Example ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To assist in reporting on using spectral parameterization, 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 module includes templates for reporting on the use of spectral parameterization methods, +with code utilities 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). +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). .. topic:: Methods Report Template - Spectral parameterization, using the specparam Python tool (version *X.X.X*) was used to - parameterize neural power spectra. Settings for the algorithm were: peak width limits : *XX*; - max number of peaks : *XX*; minimum peak height : *XX*; peak threshold : *XX*; and aperiodic - mode : *XX*. Power spectra were parameterized across the frequency range *XX* to *XX* Hz. + Power spectra were parameterized with the specparam Python tool (version *X.X.X*; Donoghue et al, 2020). + Power spectra were modeled across the frequency range of *XX* to *XX* Hz, using a powerlaw aperiodic + component and Gaussian periodic components, with the standard fitting approach, using algorithm settings + of peak width limits : *XX*; max number of peaks : *XX*; minimum peak height : *XX*; peak threshold : *XX*; + and aperiodic mode : *XX*. Goodness-of-fit measures were evaluated by XX. Checking module version ~~~~~~~~~~~~~~~~~~~~~~~ @@ -80,11 +81,13 @@ check the `__version__` from Python, using the following code: Generating Methods Reports ~~~~~~~~~~~~~~~~~~~~~~~~~~ -As of version 1.0.0 there are code utilities to extract all required information for reporting, and for generating methods reports. - -These utilities require a defined model object, such as `SpectralModel` or `SpectralGroupModel`, assumed to be called 'model_obj' in the following examples. This object will be used to extract all the relevant settings and any available meta-data for reporting. +As of version 1.0.0 there are code utilities to extract all required information for reporting, +and for generating methods reports. These utilities require an initialized model object +(e.g. `SpectralModel`), labeled as 'model_obj' in these examples. This object will be used to +extract all the relevant settings and any available meta-data for reporting. -The :func:`~specparam.utils.reports.methods_report_info` function can be used to print out the information you need for reporting: +The :func:`~specparam.utils.reports.methods_report_info` function can be used to print out +the information you need for reporting: .. code-block:: python @@ -94,7 +97,9 @@ The :func:`~specparam.utils.reports.methods_report_info` function can be used to # Print out all the methods information for reporting methods_report_info(model_obj) -The :func:`~specparam.utils.reports.methods_report_text` function can be used to print out an auto-generated methods report, like the one demonstrated above, with all available information filled: +The :func:`~specparam.utils.reports.methods_report_text` function can be used to +print out an auto-generated methods report, like the one demonstrated above, +with all available information filled: .. code-block:: python