Fitting Oscillations and One-Over-F (FOOOF)

Author: Luc Wilson

This tutorial introduces the features developed in Brainstorm to compute and view FOOOF models from a Welch’s Power Spectral Density (PSD) file.

Introduction

The Fitting Oscillations and One-Over-F (FOOOF) algorithm is designed to identify and model features of the neural power spectrum. It performs a sequential decomposition of the power spectrum into aperiodic and periodic components, modelling the spectrum using a least-squared-error approach. The present tutorial will demonstrate the algorithm’s functionality within the Brainstorm interface; for a detailed breakdown of the algorithm, please refer to the FOOOF GitHub.

This demonstration uses sample data from the introduction dataset, and can be followed by completing all steps of the Brainstorm tutorial up to and including tutorial 10.

Initializing and running FOOOF

FOOOF is principally performed on Welch’s PSD files. Analysis of Fourier transforms are also possible, but not recommended. We will run FOOOF over the PSD files we previously produced.

• Clear the list of files in the Process1 tab.
• Select the PSDs from the three datasets we have linked to our protocol and load them into Process1.

  You can select the two "PSD: 179/4000ms Power (MEG)" files and the single "PSD: 59/4000ms Power (MEG)". If you do not have these PSDs, refer to tutorial 10.

• Click on [Run] to open the pipeline editor window.

• Select the process "Frequency > FOOOF: Fitting oscillations and 1/f".
  
  

• Select the following process options:

  • FOOOF version: Matlab
    This option allows you to choose which version of FOOOF you would like to run; either the MATLAB standalone version, or the original Python version. Results and computation times may vary slightly between versions but are roughly the same.

  • Frequency range for analysis: 1.0 - 40.0 Hz [default: 1.0 - 40.0 Hz].
    FOOOF is best performed on a subset of the frequencies from the original PSD. In this range, it is important to avoid frequencies which have previously been filtered, as their adjusted powers can alter model results adversely.

  • Peak model: Gaussian [default: Gaussian].
    The original FOOOF algorithm fits spectral peaks using a gaussian distribution; the MATLAB version also allows the algorithm to fit peaks using a Cauchy distribution instead. The final option ("Best of Both") allows for individual channels to be fit using the distribution which minimizes model mean squared error (MSE).

  • Peak width limits: 1.5 - 12.0 Hz [default: 0.5 - 12.0 Hz].
    The bounds for a putative peak to be included in the final FOOOF model. Putative peaks outside these bounds are discarded.

  • Maximum number of peaks: 3 [default: 3].
    The maximum number of attempts the model will make to identify peaks; it is best to allow for at least the number of observable peaks in the PSD plus one, in the event that the model does not remove a larger peak entirely in the peak-identification process.

  • Minimum peak height : 3.0 dB [default: 3 dB].
    The minimum peak height (in log[Power]) necessary for a putative peak to be included in the final FOOOF model. Putative peaks smaller than this threshold will be discarded.

  • Proximity threshold: 2 standard deviations of the (comparatively) largest peak [default: 2].
    Occasionally, the algorithm can mistake components of a single peak as two smaller peaks. This option forces the smaller of two peaks which are too close to one-another (i.e. If the center frequency of the smaller peak is within this value of standard deviations of the larger peak’s center frequency), the smaller of the two peaks is discarded. This option also removes peaks within this value of their standard deviation from the edge of the frequency window.

  • Aperiodic mode: Fixed [default: Fixed].
    The aperiodic component of the neural power spectrum occasionally presents with a knee, as seen below in log-log space. When selecting this option, you should first consult your data to determine whether it has a knee or not (Note: a knee component is present when the aperiodic features of the spectrum plotted in log-log space are not linear).
    
    

  • Guess weight: Weak [default: None].
    By design, peak parameter estimates are close to the actual fit. However, fitting a distribution that does not match the spectrum precisely (i.e. fitting a gaussian distribution to an imperfect gaussian-shaped peak) can occasionally lead to semantically worse-fit models; square error is reduced, but the model does not look as much like the data. Selecting this option allows for additional model error to be placed on parameter values which lie further from initial estimates. “Weak” represents a small penalty, while “Strong” represents a larger penalty (essentially keeping the pre-optimization estimates). When this option is set to “None”, the algorithm reduces square error most similarly to the Python version.

• Some process options are only available in the MATLAB version, including “peak model”, “proximity threshold”, and “guess weight”. They have been added to allow for greater flexibility in the algorithm’s settings; a few are actually within the Python version, but are inaccessible via MATLAB. Still, if you would prefer to use the algorithm in its original state, you can instead select “Python” when prompted with “FOOOF version” (Note: to use this version, you will need to have loaded the appropriate version of Python into MATLAB by directing MATLAB to the correct Python executable file).

  • To direct MATLAB to the correct Python executable, use the “pyenv” function after starting up MATLAB (documentation here; here is an alternative function). Read this blog post for more information.

  • To use the Python version of FOOOF, you must have also downloaded and installed SciPy, NumPy, and FOOOF Python libraries on your computer (installation instructions).

  • Note that your Python environment shoud be available in your system path. It should always be the case by default on Linux and MacOS, but not necesarily on Windows. You might have to add some folders to your system path (instructions). The folders to add depend on your Python distribution, but could be something like:
    

    C:\Users\username\Anaconda3\envs\mne;C:\Users\username\Anaconda3\envs\mne\Library\mingw-w64\bin;C:\Users\username\Anaconda3\envs\mne\Library\bin;C:\Users\usernamec\Anaconda3\condabin;C:\Users\username\Anaconda3\Scripts

• Select the following output options:

  • Sort peaks using: Peak parameters

    • This sorts peaks according to a particular property, defined below.

  • Sort by peak: Frequency.

    • This sorts peaks by center frequency, in ascending order.
    (If you would not line to rearrange peaks, sort peaks using frequency bands).
• Click on [Run].

Viewing FOOOF models

Three new files should now be visible, with one below each PSD we just processed.

• Double-click on the first new file to open the spectrum figure.

• When viewing the options in “Display”, you should see a new set of options specific to FOOOF, including Spectrum (the original PSD), FOOOF Model (the new FOOOF model), Aperiodic only (which plots only the model’s aperiodic component), and Peaks only (which plots only the model’s peak components).
  
  

• Try all the display options:
  
  

This is an ideal environment to view FOOOF models to ensure that they are fitting the spectrum correctly. Here, you can also double-click and view the original PSD file at the same time, selecting individual channels to determine goodness-of-fit qualitatively.

Accessing FOOOF model parameters

While viewing the FOOOF models within Brainstorm is helpful for qualitative interpretations, some may wish to extract the parameter values directly from the model for statistical tests.

• Right-click on the first FOOOF file and select "File > Export to Matlab". Name the variable anything you would like (eg. "FOOOF_file").
  
  

• In MATLAB, you can explore the contents of the file using the tab "Workspace" (navigate to "FOOOF_file > Options > FOOOF") or the command line (FOOOF_file.Options.FOOOF).
  

• The first three elements are always present after computing FOOOF on the PSD file:

  • options: all of the settings for the algorithm.

  • freqs: all of the specific frequencies used in the model.

  • data: channel-specific FOOOF models, in the same order as present in Brainstorm.

• The following three elements are the product of extracting model properties:

  • peaks: a struct containing every peak’s channel of origin, center frequency (in Hz), amplitude (in B, Bells, or log[Power]), and standard deviation/gamma (in Hz); if peaks were sorted by frequency band, another column would show the name of the frequency band the peak is located in.
    
    

  • aperiodics: a struct containing every channel’s aperiodic slope (exponent) and broadband offset (in B, Bells, or log[Power]); if aperiodic mode was set as “Knee”, another column would show the knee frequency of the aperiodic.
    
    

  • stats: a struct containing every model’s channel of origin, MSE, R-squared, and absolute frequency-wise error.
    
    

Summary

FOOOF is an algorithm designed to complement many analytical techniques already in use today. Its purpose is to help researchers characterize the neural power spectrum more quantitatively; it is not necessarily meant to be used for exploratory means. The algorithm can return noticeably different models depending on whether the settings provided are suitable for the spectra being parametrized. Understanding the characteristics of a particular power spectrum is crucial to modelling them appropriately. The best way to determine whether a model is appropriate for a given spectrum is to compare the original and modelled spectra side-by-side.

Acknowledgements

All credit for the conception of the original FOOOF algorithm goes to Matar Haller, Thomas Donoghue, Erik Peterson, Paroma Varma, Priyadarshini Sebastian, Richard Gao, Torben Noto, Robert T. Knight, Avgusta Shestyuk, and Bradley Voytek. The appropriate citation for FOOOF is as follows:

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