FOOOF - fitting oscillations & one over f

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 'background' 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 this background, reflecting putative oscillations, modeled as Gaussians

With regards to examining peaks in the frequency domain, as putative oscillations, the benefit of the FOOOF approach is that these peaks are characterized in terms of their specific center frequency, amplitude and bandwidth without requiring predefining specific bands of interest. In particular, it separates these peaks from a dynamic, and independently interesting aperiodic background. This conception of the aperiodic background, as potentially functional (and therefore worth carefully modeling) is based on work from our lab suggesting that the slope of this approximately 1/f distributed aperiodic background may reflect physiological parameters, particularly excitation/inhibition balance (Gao, Peterson, Voytek, NeuroImage 2017; Voytek & Knight, Biol Psychiatry 2015). This aperiodic component changes with task (Podvalny et al., J Neurophysiol 2015), with aging (Voytek et al., J Neurosci 2015), and is thus interesting and important to measure, both in of itself, and to address potential confounds of the aperiodic components on the measurement of band-limited periodic components.

A full description of the method and approach is available in the paper below.

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

Link: https://www.biorxiv.org/content/early/2018/04/11/299859

Try it out with Binder

If you want to try it out, click here to jump straight into a live version of the tutorials.

This link uses Binder to launch a JupyterHub on the cloud for you.

Dependencies

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

It has the following dependencies:

numpy
scipy >= 0.19
matplotlib (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.

Pytest is only required to run the test suite.

Matlab Support

FOOOF is implemented in Python, but there is also Matlab wrapper, as well as other support utilities for using FOOOF in a Matlab pipeline, all of which is available in fooof_mat.

Install

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 Branch

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

$ git clone https://github.com/voytekresearch/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 .

Usage

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 aperiodic 'background' and Gaussian parameters for any identified peaks.

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_amplitude=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 (in decreasing order of amplitude).
min_peak_amp sets an absolute limit on the minimum amplitude (above background) for any extracted peak.
peak_threshold, also sets a threshold above which a peak amplitude 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, 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)

Output

Example output for a FOOOF fit of MEG data:

Example output for running FOOOF across a group of power spectra (with FOOOFGroup):

craddm / fooof