=========================
Spectral Parameterization
=========================
|ProjectStatus|_ |Version|_ |BuildStatus|_ |Coverage|_ |License|_ |PythonVersions|_ |Paper|_
.. |ProjectStatus| image:: http://www.repostatus.org/badges/latest/active.svg
.. _ProjectStatus: https://www.repostatus.org/#active
.. |Version| image:: https://img.shields.io/pypi/v/fooof.svg
.. _Version: https://pypi.python.org/pypi/fooof/
.. |BuildStatus| image:: https://github.com/fooof-tools/fooof/actions/workflows/build.yml/badge.svg
.. _BuildStatus: https://github.com/fooof-tools/fooof/actions/workflows/build.yml
.. |Coverage| image:: https://codecov.io/gh/fooof-tools/fooof/branch/main/graph/badge.svg
.. _Coverage: https://codecov.io/gh/fooof-tools/fooof
.. |License| image:: https://img.shields.io/pypi/l/fooof.svg
.. _License: https://opensource.org/licenses/Apache-2.0
.. |PythonVersions| image:: https://img.shields.io/pypi/pyversions/fooof.svg
.. _PythonVersions: https://pypi.python.org/pypi/fooof/
.. |Paper| image:: https://img.shields.io/badge/paper-nn10.1038-informational.svg
.. _Paper: https://doi.org/10.1038/s41593-020-00744-x
Spectral parameterization (`specparam`, formerly `fooof`) is a fast, efficient, and physiologically-informed tool to parameterize neural power spectra.
WARNING: this Github repository has been updated to a major update / breaking change from previous releases, which were under the `fooof` name, and now contains major breaking update for the new `specparam` version of the code. The new version is not fully released, though a test version is available (see installation instructions below).
Overview
--------
The power spectrum model conceives of a model of the power spectrum as a combination of two distinct functional processes:
- An aperiodic component, reflecting 1/f like characteristics, with
- A variable number of periodic components (putative oscillations), as peaks rising above the aperiodic component
This model driven approach can be used to measure periodic and aperiodic properties of electrophysiological data,
including EEG, MEG, ECoG and LFP data.
The benefit of fitting a model in order to measure putative oscillations, is that peaks in the power spectrum are
characterized in terms of their specific center frequency, power and bandwidth without requiring predefining
specific bands of interest and controlling for the aperiodic component.
The model also returns a measure of this aperiodic components of the signal, allowing for measuring and
comparison of 1/f-like components of the signal within and between subjects.
specparam (upcoming version)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
We are currently in the process of a major update to this tool, that includes a name changes (fooof -> specparam), and full rewrite of the code. This means that the new version will be incompatible with prior versions (in terms of the code having different names, and previous code no longer running as written), though note that the exact same procedures will be available (spectra can be fit in a way expected to give the same results), as well many new features.
The new version is called `specparam` (spectral parameterization). There is a release candidate available for testing (see installation instructions).
fooof (stable version)
~~~~~~~~~~~~~~~~~~~~~~
The fooof naming scheme, with most recent stable version 1.1 is the current main release, and is fully functional and stable, including everything that was introduced under the fooof name.
Which version should I use?
~~~~~~~~~~~~~~~~~~~~~~~~~~~
The previous release version, fooof, is fully functional, and projects that are already using it might as well stick with that, unless any of the new functionality in specparam is particularly important. For projects that are just starting, the new specparam version may be of interest if some of the new features are of interest (e.g. time-resolved estimations), though note that as release candidates, the release are not guaranteed to be stable (future updates may make breaking changes). Note that for the same model and settings, fooof and specparam should be exactly equivalent, so in terms of outputs there should be no difference in choosing one or the other.
Documentation
-------------
The `specparam` package includes a full set of code documentation.
specparam (upcoming version)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To see the documentation for the candidate 2.0 release, see
`here <https://specparam-tools.github.io/>`_.
fooof (stable version)
~~~~~~~~~~~~~~~~~~~~~~
Documentation is available on the
`documentation site <https://fooof-tools.github.io/>`_.
This documentation includes:
- `Motivations <https://fooof-tools.github.io/fooof/auto_motivations/index.html>`_:
with motivating examples of why we recommend parameterizing neural power spectra
- `Tutorials <https://fooof-tools.github.io/fooof/auto_tutorials/index.html>`_:
with a step-by-step guide through the model and how to apply it
- `Examples <https://fooof-tools.github.io/fooof/auto_examples/index.html>`_:
demonstrating example analyses and use cases, and other functionality
- `API list <https://fooof-tools.github.io/fooof/api.html>`_:
which lists and describes all the code and functionality available in the module
- `FAQ <https://fooof-tools.github.io/fooof/faq.html>`_:
answering frequency asked questions
- `Glossary <https://fooof-tools.github.io/fooof/glossary.html>`_:
which defines all the key terms used in the module
- `Reference <https://fooof-tools.github.io/fooof/reference.html>`_:
with information for how to reference and report on using the module
Dependencies
------------
`specparam` is written in Python, and requires Python >= 3.7 to run.
It has the following required dependencies:
- `numpy <https://github.com/numpy/numpy>`_
- `scipy <https://github.com/scipy/scipy>`_ >= 0.19
There are also optional dependencies, which are not required for model fitting itself, but offer extra functionality:
- `matplotlib <https://github.com/matplotlib/matplotlib>`_ is needed to visualize data and model fits
- `tqdm <https://github.com/tqdm/tqdm>`_ is needed to print progress bars when fitting many models
- `pandas <https://github.com/pandas-dev/pandas>`_ is needed for exporting model fit results to dataframes
- `pytest <https://github.com/pytest-dev/pytest>`_ is needed to run the test suite locally
We recommend using the `Anaconda <https://www.anaconda.com/distribution/>`_ distribution to manage these requirements.
Installation
------------
specparam / fooof can be installed using pip.
specparam (test version)
~~~~~~~~~~~~~~~~~~~~~~~~
To install the current release candidate version for the new 2.0 version, you can do:
.. code-block:: shell
$ pip install specparam
The above will install the most recent release candidate.
NOTE: specparam is currently available as a 'release candidate', meaning it is not finalized and fully released yet.
This means it may not yet have all features that the ultimate 2.0 version will include, and things are not strictly
guaranteed to stay the same (there may be further breaking changes in the ultimate 2.0 release).
fooof (stable version)
~~~~~~~~~~~~~~~~~~~~~~
The current major release is the 1.X.X series, which is a breaking change from the prior 0.X.X series.
Check the `changelog <https://fooof-tools.github.io/fooof/changelog.html>`_ for notes on updating to the new version.
**Stable Version**
To install the latest stable release, use pip:
.. code-block:: shell
$ pip install fooof
The module can also be installed with conda, from the conda-forge channel:
.. code-block:: shell
$ conda install -c conda-forge fooof
**Development Version**
To get the current development version, first clone this repository:
.. code-block:: shell
$ git clone https://github.com/fooof-tools/fooof
To install this cloned copy, move into the directory you just cloned, and run:
.. code-block:: shell
$ pip install .
**Editable Version**
To install an editable version, download the development version as above, and run:
.. code-block:: shell
$ pip install -e .
Other Language Support
----------------------
The original implementation of `specparam`, available in this repository, is implemented in Python.
If you wish to run specparam from another language, there are a couple potential options:
- a `wrapper`, which allows for running the Python code from another language
- a `reimplementation`, which reflects a new implementation of the specparam algorithm in another language
Below are listed some examples of wrappers and/or re-implementations in other languages (non-exhaustive).
Matlab
~~~~~~
In Matlab, there is a reimplementation available in common toolboxes:
- The `Brainstorm <https://neuroimage.usc.edu/brainstorm/Introduction>`_ toolbox has a reimplementation of specparam (see the `Brainstorm fooof tutorial <https://neuroimage.usc.edu/brainstorm/Tutorials/Fooof>`_)
- The `Fieldtrip <https://www.fieldtriptoolbox.org/>`_ toolbox also uses the same reimplementation (see the `Fieldtrip fooof tutorial <https://www.fieldtriptoolbox.org/example/fooof/>`_)
There is also a Matlab wrapper in the `fooof_mat <http://github.com/fooof-tools/fooof_mat>`_ repository.
Note that another option is to use Python FOOOF within a Matlab pipeline, as explored in the
`mat_py_mat <https://github.com/fooof-tools/mat_py_mat>`_ repository.
Other Languages
~~~~~~~~~~~~~~~
Other languages with wrappers include:
- Julia, for which there is a `fooof wrapper <https://juliahub.com/ui/Packages/PyFOOOF/Ng8hN/0.1.0>`_
- R, in which fooof can be run using `reticulate <https://rstudio.github.io/reticulate/>`_, as `shown here <https://github.com/fooof-tools/DevelopmentalDemo/tree/main/R>`_
Reference
---------
If you use this code in your project, please cite::
Donoghue T, Haller M, Peterson EJ, Varma P, Sebastian P, Gao R, Noto T, Lara AH, Wallis JD,
Knight RT, Shestyuk A, & Voytek B (2020). Parameterizing neural power spectra into periodic
and aperiodic components. Nature Neuroscience, 23, 1655-1665.
DOI: 10.1038/s41593-020-00744-x
Direct link: https://doi.org/10.1038/s41593-020-00744-x
More information for how to cite this method can be found on the
`reference page <https://fooof-tools.github.io/fooof/reference.html>`_.
Code and analyses from the paper are also available in the
`paper repository <https://github.com/fooof-tools/Paper>`_.
Contribute
----------
This project welcomes and encourages contributions from the community!
To file bug reports and/or ask questions about this project, please use the
`Github issue tracker <https://github.com/fooof-tools/fooof/issues>`_.
To see and get involved in discussions about the module, check out:
- the `issues board <https://github.com/fooof-tools/fooof/issues>`_ for topics relating to code updates, bugs, and fixes
- the `development page <https://github.com/fooof-tools/Development>`_ for discussion of potential major updates to the module
When interacting with this project, please use the
`contribution guidelines <https://github.com/fooof-tools/fooof/blob/main/CONTRIBUTING.md>`_
and follow the
`code of conduct <https://github.com/fooof-tools/fooof/blob/main/CODE_OF_CONDUCT.md>`_.
Quickstart
----------
This module is object oriented, and uses a similar approach as used in scikit-learn.
The algorithm works on frequency representations, that is power spectra in linear space.
**Fitting a Single Power Spectrum**
With a power spectrum loaded (with 'freqs' storing frequency values, and 'spectrum' storing
the power spectrum, both as 1D arrays in linear space) parameterization can be done as follows:
.. code-block:: python
# Import the model object
from specparam import SpectralModel
# Initialize model object
fm = SpectralModel()
# Define frequency range across which to model the spectrum
freq_range = [3, 40]
# Parameterize the power spectrum, and print out a report
fm.report(freqs, spectrum, freq_range)
SpectralModel.report() fits the model, plots the original power spectrum with the associated model fit,
and prints out the parameters of the model fit for both the aperiodic component, and parameters for
any identified peaks, reflecting periodic components.
Example output for the report of a parameterized fit on an individual power spectrum:
.. image:: https://raw.githubusercontent.com/fooof-tools/fooof/main/doc/img/FOOOF_report.png
**Defining the model Settings**
The settings for the algorithm are:
* ``peak_width_limits`` sets the possible lower- and upper-bounds for the fitted peak widths.
* ``max_n_peaks`` sets the maximum number of peaks to fit.
* ``min_peak_height`` sets an absolute limit on the minimum height (above aperiodic) for any extracted peak.
* ``peak_threshold`` sets a relative threshold above which a peak height must cross to be included in the model.
* ``aperiodic_mode`` defines the approach to use to parameterize the aperiodic component.
These settings can be defined when initializing the model, for example:
.. code-block:: python
# Initialize a model object with defined settings
fm = SpectralModel(peak_width_limits=[1.0, 8.0], max_n_peaks=6, min_peak_height=0.1,
peak_threshold=2.0, aperiodic_mode='fixed')
**Fitting a Group of Power Spectra**
Next is an example workflow for fitting a group of neural power spectra.
In this case, 'freqs' is again a 1D array of frequency values, and 'spectra' is a 2D array of power spectra.
We can fit the group of power spectra by doing:
.. code-block:: python
# Initialize a SpectralGroupModel object, specifying some parameters
fg = SpectralGroupModel(peak_width_limits=[1.0, 8.0], max_n_peaks=8)
# Fit models across the matrix of power spectra
fg.fit(freqs, spectra)
# Create and save out a report summarizing the results across the group of power spectra
fg.save_report()
# Save out results for further analysis later
fg.save(file_name='group_results', save_results=True)
Example output from using SpectralGroupModel across a group of power spectra:
.. image:: https://raw.githubusercontent.com/fooof-tools/fooof/main/doc/img/FOOOFGroup_report.png
**Other Functionality**
The module also includes functionality for fitting the model to matrices of multiple power spectra,
saving and loading results, creating reports describing model fits, analyzing model outputs,
plotting models and parameters, and simulating power spectra, all of which is described in the
`documentation <https://fooof-tools.github.io/fooof/>`_.
Funding
-------
Supported by NIH award R01 GM134363 from the
`NIGMS <https://www.nigms.nih.gov/>`_.
.. image:: https://www.nih.gov/sites/all/themes/nih/images/nih-logo-color.png
:width: 400
|
Raw data
{
"_id": null,
"home_page": "https://github.com/fooof-tools/fooof",
"name": "specparam",
"maintainer": "Thomas Donoghue",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "tdonoghue.research@gmail.com",
"keywords": "neuroscience, neural oscillations, power spectra, 1/f, electrophysiology",
"author": "The Voytek Lab",
"author_email": "voyteklab@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/5a/f1/0406e3984e0923076310161fa2a3ff8df0e93a755f18a470ae9565c3e81c/specparam-2.0.0rc2.tar.gz",
"platform": "any",
"description": "=========================\nSpectral Parameterization\n=========================\n\n|ProjectStatus|_ |Version|_ |BuildStatus|_ |Coverage|_ |License|_ |PythonVersions|_ |Paper|_\n\n.. |ProjectStatus| image:: http://www.repostatus.org/badges/latest/active.svg\n.. _ProjectStatus: https://www.repostatus.org/#active\n\n.. |Version| image:: https://img.shields.io/pypi/v/fooof.svg\n.. _Version: https://pypi.python.org/pypi/fooof/\n\n.. |BuildStatus| image:: https://github.com/fooof-tools/fooof/actions/workflows/build.yml/badge.svg\n.. _BuildStatus: https://github.com/fooof-tools/fooof/actions/workflows/build.yml\n\n.. |Coverage| image:: https://codecov.io/gh/fooof-tools/fooof/branch/main/graph/badge.svg\n.. _Coverage: https://codecov.io/gh/fooof-tools/fooof\n\n.. |License| image:: https://img.shields.io/pypi/l/fooof.svg\n.. _License: https://opensource.org/licenses/Apache-2.0\n\n.. |PythonVersions| image:: https://img.shields.io/pypi/pyversions/fooof.svg\n.. _PythonVersions: https://pypi.python.org/pypi/fooof/\n\n.. |Paper| image:: https://img.shields.io/badge/paper-nn10.1038-informational.svg\n.. _Paper: https://doi.org/10.1038/s41593-020-00744-x\n\n\nSpectral parameterization (`specparam`, formerly `fooof`) is a fast, efficient, and physiologically-informed tool to parameterize neural power spectra.\n\nWARNING: this Github repository has been updated to a major update / breaking change from previous releases, which were under the `fooof` name, and now contains major breaking update for the new `specparam` version of the code. The new version is not fully released, though a test version is available (see installation instructions below).\n\nOverview\n--------\n\nThe power spectrum model conceives of a model of the power spectrum as a combination of two distinct functional processes:\n\n- An aperiodic component, reflecting 1/f like characteristics, with\n- A variable number of periodic components (putative oscillations), as peaks rising above the aperiodic component\n\nThis model driven approach can be used to measure periodic and aperiodic properties of electrophysiological data,\nincluding EEG, MEG, ECoG and LFP data.\n\nThe benefit of fitting a model in order to measure putative oscillations, is that peaks in the power spectrum are\ncharacterized in terms of their specific center frequency, power and bandwidth without requiring predefining\nspecific bands of interest and controlling for the aperiodic component.\nThe model also returns a measure of this aperiodic components of the signal, allowing for measuring and\ncomparison of 1/f-like components of the signal within and between subjects.\n\nspecparam (upcoming version)\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nWe are currently in the process of a major update to this tool, that includes a name changes (fooof -> specparam), and full rewrite of the code. This means that the new version will be incompatible with prior versions (in terms of the code having different names, and previous code no longer running as written), though note that the exact same procedures will be available (spectra can be fit in a way expected to give the same results), as well many new features.\n\nThe new version is called `specparam` (spectral parameterization). There is a release candidate available for testing (see installation instructions).\n\nfooof (stable version)\n~~~~~~~~~~~~~~~~~~~~~~\n\nThe fooof naming scheme, with most recent stable version 1.1 is the current main release, and is fully functional and stable, including everything that was introduced under the fooof name.\n\nWhich version should I use?\n~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe previous release version, fooof, is fully functional, and projects that are already using it might as well stick with that, unless any of the new functionality in specparam is particularly important. For projects that are just starting, the new specparam version may be of interest if some of the new features are of interest (e.g. time-resolved estimations), though note that as release candidates, the release are not guaranteed to be stable (future updates may make breaking changes). Note that for the same model and settings, fooof and specparam should be exactly equivalent, so in terms of outputs there should be no difference in choosing one or the other.\n\nDocumentation\n-------------\n\nThe `specparam` package includes a full set of code documentation.\n\nspecparam (upcoming version)\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nTo see the documentation for the candidate 2.0 release, see\n`here <https://specparam-tools.github.io/>`_.\n\nfooof (stable version)\n~~~~~~~~~~~~~~~~~~~~~~\n\nDocumentation is available on the\n`documentation site <https://fooof-tools.github.io/>`_.\n\nThis documentation includes:\n\n- `Motivations <https://fooof-tools.github.io/fooof/auto_motivations/index.html>`_:\n with motivating examples of why we recommend parameterizing neural power spectra\n- `Tutorials <https://fooof-tools.github.io/fooof/auto_tutorials/index.html>`_:\n with a step-by-step guide through the model and how to apply it\n- `Examples <https://fooof-tools.github.io/fooof/auto_examples/index.html>`_:\n demonstrating example analyses and use cases, and other functionality\n- `API list <https://fooof-tools.github.io/fooof/api.html>`_:\n which lists and describes all the code and functionality available in the module\n- `FAQ <https://fooof-tools.github.io/fooof/faq.html>`_:\n answering frequency asked questions\n- `Glossary <https://fooof-tools.github.io/fooof/glossary.html>`_:\n which defines all the key terms used in the module\n- `Reference <https://fooof-tools.github.io/fooof/reference.html>`_:\n with information for how to reference and report on using the module\n\nDependencies\n------------\n\n`specparam` is written in Python, and requires Python >= 3.7 to run.\n\nIt has the following required dependencies:\n\n- `numpy <https://github.com/numpy/numpy>`_\n- `scipy <https://github.com/scipy/scipy>`_ >= 0.19\n\nThere are also optional dependencies, which are not required for model fitting itself, but offer extra functionality:\n\n- `matplotlib <https://github.com/matplotlib/matplotlib>`_ is needed to visualize data and model fits\n- `tqdm <https://github.com/tqdm/tqdm>`_ is needed to print progress bars when fitting many models\n- `pandas <https://github.com/pandas-dev/pandas>`_ is needed for exporting model fit results to dataframes\n- `pytest <https://github.com/pytest-dev/pytest>`_ is needed to run the test suite locally\n\nWe recommend using the `Anaconda <https://www.anaconda.com/distribution/>`_ distribution to manage these requirements.\n\nInstallation\n------------\n\nspecparam / fooof can be installed using pip.\n\nspecparam (test version)\n~~~~~~~~~~~~~~~~~~~~~~~~\n\nTo install the current release candidate version for the new 2.0 version, you can do:\n\n.. code-block:: shell\n\n $ pip install specparam\n\nThe above will install the most recent release candidate.\n\nNOTE: specparam is currently available as a 'release candidate', meaning it is not finalized and fully released yet.\nThis means it may not yet have all features that the ultimate 2.0 version will include, and things are not strictly\nguaranteed to stay the same (there may be further breaking changes in the ultimate 2.0 release).\n\nfooof (stable version)\n~~~~~~~~~~~~~~~~~~~~~~\n\nThe current major release is the 1.X.X series, which is a breaking change from the prior 0.X.X series.\n\nCheck the `changelog <https://fooof-tools.github.io/fooof/changelog.html>`_ for notes on updating to the new version.\n\n**Stable Version**\n\nTo install the latest stable release, use pip:\n\n.. code-block:: shell\n\n $ pip install fooof\n\nThe module can also be installed with conda, from the conda-forge channel:\n\n.. code-block:: shell\n\n $ conda install -c conda-forge fooof\n\n**Development Version**\n\nTo get the current development version, first clone this repository:\n\n.. code-block:: shell\n\n $ git clone https://github.com/fooof-tools/fooof\n\nTo install this cloned copy, move into the directory you just cloned, and run:\n\n.. code-block:: shell\n\n $ pip install .\n\n**Editable Version**\n\nTo install an editable version, download the development version as above, and run:\n\n.. code-block:: shell\n\n $ pip install -e .\n\nOther Language Support\n----------------------\n\nThe original implementation of `specparam`, available in this repository, is implemented in Python.\n\nIf you wish to run specparam from another language, there are a couple potential options:\n\n- a `wrapper`, which allows for running the Python code from another language\n- a `reimplementation`, which reflects a new implementation of the specparam algorithm in another language\n\nBelow are listed some examples of wrappers and/or re-implementations in other languages (non-exhaustive).\n\nMatlab\n~~~~~~\n\nIn Matlab, there is a reimplementation available in common toolboxes:\n- The `Brainstorm <https://neuroimage.usc.edu/brainstorm/Introduction>`_ toolbox has a reimplementation of specparam (see the `Brainstorm fooof tutorial <https://neuroimage.usc.edu/brainstorm/Tutorials/Fooof>`_)\n- The `Fieldtrip <https://www.fieldtriptoolbox.org/>`_ toolbox also uses the same reimplementation (see the `Fieldtrip fooof tutorial <https://www.fieldtriptoolbox.org/example/fooof/>`_)\n\nThere is also a Matlab wrapper in the `fooof_mat <http://github.com/fooof-tools/fooof_mat>`_ repository.\n\nNote that another option is to use Python FOOOF within a Matlab pipeline, as explored in the\n`mat_py_mat <https://github.com/fooof-tools/mat_py_mat>`_ repository.\n\nOther Languages\n~~~~~~~~~~~~~~~\n\nOther languages with wrappers include:\n\n- Julia, for which there is a `fooof wrapper <https://juliahub.com/ui/Packages/PyFOOOF/Ng8hN/0.1.0>`_\n- R, in which fooof can be run using `reticulate <https://rstudio.github.io/reticulate/>`_, as `shown here <https://github.com/fooof-tools/DevelopmentalDemo/tree/main/R>`_\n\nReference\n---------\n\nIf you use this code in your project, please cite::\n\n Donoghue T, Haller M, Peterson EJ, Varma P, Sebastian P, Gao R, Noto T, Lara AH, Wallis JD,\n Knight RT, Shestyuk A, & Voytek B (2020). Parameterizing neural power spectra into periodic\n and aperiodic components. Nature Neuroscience, 23, 1655-1665.\n DOI: 10.1038/s41593-020-00744-x\n\nDirect link: https://doi.org/10.1038/s41593-020-00744-x\n\nMore information for how to cite this method can be found on the\n`reference page <https://fooof-tools.github.io/fooof/reference.html>`_.\n\nCode and analyses from the paper are also available in the\n`paper repository <https://github.com/fooof-tools/Paper>`_.\n\nContribute\n----------\n\nThis project welcomes and encourages contributions from the community!\n\nTo file bug reports and/or ask questions about this project, please use the\n`Github issue tracker <https://github.com/fooof-tools/fooof/issues>`_.\n\nTo see and get involved in discussions about the module, check out:\n\n- the `issues board <https://github.com/fooof-tools/fooof/issues>`_ for topics relating to code updates, bugs, and fixes\n- the `development page <https://github.com/fooof-tools/Development>`_ for discussion of potential major updates to the module\n\nWhen interacting with this project, please use the\n`contribution guidelines <https://github.com/fooof-tools/fooof/blob/main/CONTRIBUTING.md>`_\nand follow the\n`code of conduct <https://github.com/fooof-tools/fooof/blob/main/CODE_OF_CONDUCT.md>`_.\n\nQuickstart\n----------\n\nThis module is object oriented, and uses a similar approach as used in scikit-learn.\n\nThe algorithm works on frequency representations, that is power spectra in linear space.\n\n**Fitting a Single Power Spectrum**\n\nWith a power spectrum loaded (with 'freqs' storing frequency values, and 'spectrum' storing\nthe power spectrum, both as 1D arrays in linear space) parameterization can be done as follows:\n\n.. code-block:: python\n\n # Import the model object\n from specparam import SpectralModel\n\n # Initialize model object\n fm = SpectralModel()\n\n # Define frequency range across which to model the spectrum\n freq_range = [3, 40]\n\n # Parameterize the power spectrum, and print out a report\n fm.report(freqs, spectrum, freq_range)\n\nSpectralModel.report() fits the model, plots the original power spectrum with the associated model fit,\nand prints out the parameters of the model fit for both the aperiodic component, and parameters for\nany identified peaks, reflecting periodic components.\n\nExample output for the report of a parameterized fit on an individual power spectrum:\n\n.. image:: https://raw.githubusercontent.com/fooof-tools/fooof/main/doc/img/FOOOF_report.png\n\n**Defining the model Settings**\n\nThe settings for the algorithm are:\n\n* ``peak_width_limits`` sets the possible lower- and upper-bounds for the fitted peak widths.\n* ``max_n_peaks`` sets the maximum number of peaks to fit.\n* ``min_peak_height`` sets an absolute limit on the minimum height (above aperiodic) for any extracted peak.\n* ``peak_threshold`` sets a relative threshold above which a peak height must cross to be included in the model.\n* ``aperiodic_mode`` defines the approach to use to parameterize the aperiodic component.\n\nThese settings can be defined when initializing the model, for example:\n\n.. code-block:: python\n\n # Initialize a model object with defined settings\n fm = SpectralModel(peak_width_limits=[1.0, 8.0], max_n_peaks=6, min_peak_height=0.1,\n peak_threshold=2.0, aperiodic_mode='fixed')\n\n**Fitting a Group of Power Spectra**\n\nNext is an example workflow for fitting a group of neural power spectra.\nIn this case, 'freqs' is again a 1D array of frequency values, and 'spectra' is a 2D array of power spectra.\nWe can fit the group of power spectra by doing:\n\n.. code-block:: python\n\n # Initialize a SpectralGroupModel object, specifying some parameters\n fg = SpectralGroupModel(peak_width_limits=[1.0, 8.0], max_n_peaks=8)\n\n # Fit models across the matrix of power spectra\n fg.fit(freqs, spectra)\n\n # Create and save out a report summarizing the results across the group of power spectra\n fg.save_report()\n\n # Save out results for further analysis later\n fg.save(file_name='group_results', save_results=True)\n\nExample output from using SpectralGroupModel across a group of power spectra:\n\n.. image:: https://raw.githubusercontent.com/fooof-tools/fooof/main/doc/img/FOOOFGroup_report.png\n\n**Other Functionality**\n\nThe module also includes functionality for fitting the model to matrices of multiple power spectra,\nsaving and loading results, creating reports describing model fits, analyzing model outputs,\nplotting models and parameters, and simulating power spectra, all of which is described in the\n`documentation <https://fooof-tools.github.io/fooof/>`_.\n\nFunding\n-------\n\nSupported by NIH award R01 GM134363 from the\n`NIGMS <https://www.nigms.nih.gov/>`_.\n\n.. image:: https://www.nih.gov/sites/all/themes/nih/images/nih-logo-color.png\n :width: 400\n\n|\n",
"bugtrack_url": null,
"license": "Apache License, 2.0",
"summary": "Spectral parameterization.",
"version": "2.0.0rc2",
"project_urls": {
"Bug Reports": "https://github.com/fooof-tools/fooof/issues",
"Documentation": "https://fooof-tools.github.io/fooof/",
"Download": "https://github.com/fooof-tools/fooof/releases",
"Homepage": "https://github.com/fooof-tools/fooof",
"Source": "https://github.com/fooof-tools/fooof"
},
"split_keywords": [
"neuroscience",
" neural oscillations",
" power spectra",
" 1/f",
" electrophysiology"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fb8dd71d6108f14c13999be642ffa18582481f36264cfcd2121471b5571fc97f",
"md5": "95bb5c28e439209480e13c1c57971737",
"sha256": "8e3961813c14f893728aa8380e5c77b7c55b26ac95ab3ee11a912b91b0004bbd"
},
"downloads": -1,
"filename": "specparam-2.0.0rc2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "95bb5c28e439209480e13c1c57971737",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 167753,
"upload_time": "2024-04-10T15:21:13",
"upload_time_iso_8601": "2024-04-10T15:21:13.402298Z",
"url": "https://files.pythonhosted.org/packages/fb/8d/d71d6108f14c13999be642ffa18582481f36264cfcd2121471b5571fc97f/specparam-2.0.0rc2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5af10406e3984e0923076310161fa2a3ff8df0e93a755f18a470ae9565c3e81c",
"md5": "d4828eb0f0738c5ca29422cfa4a8c761",
"sha256": "ea9a38ad8b698ebf076433b0955996b4295aa7354df83925507c00431654d619"
},
"downloads": -1,
"filename": "specparam-2.0.0rc2.tar.gz",
"has_sig": false,
"md5_digest": "d4828eb0f0738c5ca29422cfa4a8c761",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 128239,
"upload_time": "2024-04-10T15:21:15",
"upload_time_iso_8601": "2024-04-10T15:21:15.276721Z",
"url": "https://files.pythonhosted.org/packages/5a/f1/0406e3984e0923076310161fa2a3ff8df0e93a755f18a470ae9565c3e81c/specparam-2.0.0rc2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-10 15:21:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fooof-tools",
"github_project": "fooof",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "specparam"
}
JSON
