Skip to content

[WIP] - Update referencing #399

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
TomDonoghue wants to merge 1 commit into
base: main
Choose a base branch
from
Open

[WIP] - Update referencing #399

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 34 additions & 29 deletions doc/reference.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,18 +1,19 @@
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
-----------------
.. 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

Expand All @@ -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 <https://github.com/fooof-tools/Paper>`_.

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 <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
To explore the list of articles that cite this paper, you can use this
`Google scholar link <https://scholar.google.com/scholar?cites=1871208307712966933&as_sdt=5,33&sciodt=0,33&hl=en>`_.

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:

Expand All @@ -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
~~~~~~~~~~~~~~~~~~~~~~~
Expand All @@ -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

Expand All @@ -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

Expand Down
Loading