/fooof

Parameterizing neural power spectra.

Primary LanguagePythonApache License 2.0Apache-2.0

FOOOF - fitting oscillations & one over f

Project Status: Active – The project has reached a stable, usable state and is being actively developed. Latest Version Build Status codecov License Supported Python Versions

FOOOF is a fast, efficient, and physiologically-informed tool to parameterize neural power spectra.

Overview

FOOOF conceives of a model of the power spectrum as a combination of two distinct functional processes:

  • An aperiodic component, reflecting 1/f like characteristics, modeled with an exponential fit, with
  • A variable number of periodic components, that exhibit as band-limited peaks rising above the aperiodic component, reflecting putative oscillations, modeled as Gaussians

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 using FOOOF for measuring 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. FOOOF also gives you 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.

Documentation

Documentation for FOOOF is available here.

The tutorials describe the FOOOF algorithm and it's usage, as well as additional examples on the Examples page.

The documentation also includes an FAQ.

Dependencies

FOOOF is written in Python, and requires Python >= 3.5 to run.

It has the following dependencies:

  • numpy
  • scipy >= 0.19
  • matplotlib (optional)
  • tqdm (optional)
  • pytest (optional)

That is, if you are using Anaconda, then you are good to go.

If you aren't already using Anaconda, it is a useful tool to get and manage these dependencies.

Matplotlib is not required for running the model fitting, but is used if you want to visualize model fits.

tqdm is also not required for running the model fitting, but can be used to print progress bars when fitting many models.

Pytest is only required to run the test suite.

Installation

Stable Version

To install the latest stable release of fooof, you can use pip:

$ pip install fooof

Note that this will install only the core (non-optional) fooof requirements.

Development Version

To get the lastest, development version, you can get the code using git:

$ git clone https://github.com/fooof-tools/fooof

To then install the development version (without making changes to it), move into the directory you cloned and run:

$ pip install .

Otherwise, if you want to install an editable, development version, move into the directory you cloned and install with:

$ pip install -e .

Matlab Support

FOOOF is implemented in Python, but there is also Matlab wrapper with which you can use FOOOF from Matlab, which is available in the fooof_mat repository.

If you would like to use FOOOF, from Python, within a pipeline that is mostly in Matlab, the mat_py_mat repository also has some examples and utilities for doing so.

Reference

If you use this code in your project, please cite:

Haller M, Donoghue T, Peterson E, Varma P, Sebastian P, Gao R, Noto T, Knight RT, Shestyuk A,
Voytek B (2018) Parameterizing Neural Power Spectra. bioRxiv, 299859.
doi: https://doi.org/10.1101/299859

Direct Link: https://doi.org/10.1101/299859

Quickstart

FOOOF is object oriented, and generally follows a similar approach as used in scikit-learn.

The algorithm works on frequency representations, that is power spectra in linear space.

With a power spectrum loaded (with 'freqs' storing frequency values, and 'spectrum' storing the power spectrum, both as 1D arrays in linear space) FOOOF can be used as follows:

from fooof import FOOOF

# Initialize FOOOF object
fm = FOOOF()

# Define frequency range across which to model the spectrum
freq_range = [3, 40]

# Model the power spectrum with FOOOF, and print out a report
fm.report(freqs, spectrum, freq_range)

FOOOF.report() fits the model, plots the original power spectrum with the associated FOOOF 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.

FOOOF also accepts parameters for fine-tuning the fit. For example:

fm = FOOOF(peak_width_limits=[1.0, 8.0], max_n_peaks=6, min_peak_height=0.1, peak_threshold=2.0)
  • 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, also sets a threshold above which a peak height must cross to be included in the model. This parameter is in terms of standard deviation above the noise of the flattened spectrum.

FOOOF also has convenience methods for running the FOOOF model across matrices of multiple power spectra, as well as functionality for saving and loading results, creating reports from FOOOF outputs, and utilities to further analize FOOOF results.

An example workflow for fitting a group of neural power spectra with 'freqs' as 1D array of frequency values, and 'spectra' as a 2D array of power spectra:

# Initialize a FOOOFGroup object, specifying some parameters
fg = FOOOFGroup(peak_width_limits=[1.0, 8.0], max_n_peaks=8)

# Fit FOOOF model 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 FOOOF results for further analysis later
fg.save(file_name='fooof_group_results', save_results=True)

Example output for a FOOOF fit on an individual power spectrum:

"fooof_report"

Example output from using FOOOFGroup across a group of power spectra:

"fooof_group_report"