= Fitting Oscillations and One-Over-F (FOOOF) =
''Authors: Luc Wilson, Raymundo Cassani''

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

''Note: ''The FOOOF algorithm has recently been renamed by its authors to'' specparam''.

<<TableOfContents(2,2)>>

== Introduction ==
The Fitting Oscillations and One-Over-F (FOOOF/specparam) 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, optimizing the modelled 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 [[https://fooof-tools.github.io/fooof/|FOOOF GitHub]].<<BR>><<BR>> {{attachment:FOOOF_schematic.png||width="600",height="400"}}

This demonstration uses sample data from the [[https://neuroimage.usc.edu/brainstorm/DatasetIntroduction|introduction dataset]], and can be followed by completing all steps of the Brainstorm tutorial up to and including [[https://neuroimage.usc.edu/brainstorm/Tutorials/ArtifactsFilter|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  [[https://neuroimage.usc.edu/brainstorm/Tutorials/ArtifactsFilter|tutorial 10]].
 * Click on [Run] to open the pipeline editor window.
 * Select the process "'''Frequency > FOOOF: Fitting oscillations and 1/f'''". <<BR>><<BR>> {{attachment:psd_select.gif||width="170",height="324"}} {{attachment:FOOOF_options.png||width="220",height="324"}}

Select the following process options:

 * '''FOOOF version''': Matlab <<BR>>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]. <<BR>>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.
 * '''Ignore power line frequencies''': None [default: 60 Hz]. <<BR>>Depending on whether a notch filter was previously used for one's regional power line frequency (and harmonics), FOOOF may either be attempting to fit increases in power attributable to power lines as peaks, or the aperiodic fit may be disrupted by 'negative peaks' of power. To avoid both of these pitfalls, users can choose to ignore frequencies whose power measures have been disrupted by power lines or their filtering (for instance, 60±2Hz, 120±2Hz, 180±2Hz) in the modelling process. This option becomes important when fitting a broader range of frequencies (>40Hz) and should be set in accordance with one's region.
 * '''Peak model''': Gaussian [default: Gaussian]. <<BR>> 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]. <<BR>> 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]. <<BR>> 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]. <<BR>> 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]. <<BR>> 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]. <<BR>> 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). <<BR>><<BR>> {{attachment:FOOOF_knee.png||width="350",height="300"}}
 * '''Guess weight''': Weak [default: None]. <<BR>> 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.
  * Note: '''Guess weight''' selections are ignored when Brainstorm detects that the user has the optimization toolbox, as it will use constrained optimization to best-match the Python version. It is recommended that users have the optimization toolbox.

Select the following output options:

 * '''Sort peaks using''': Peak parameters
  . This sorts peaks according to a particular property of the peaks, defined below.
 * '''Sort by peak''': Frequency.
  . This sorts peaks by center frequency, in ascending order. (If you would not like to rearrange peaks, sort peaks using frequency bands).

== 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).<<BR>><<BR>> {{attachment:FOOOF_display.png||width="650",height="370"}}
 * Try all the display options: <<BR>><<BR>> {{attachment:FOOOF_model.gif||width="470",height="229"}}

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"). <<BR>><<BR>> {{attachment:FOOOF_export.gif||width="325",height="161"}}
 * 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''').<<BR>> {{attachment:FOOOF_workspace.png||width="344",height="148"}} {{attachment:FOOOF_struct.png||width="274",height="148"}}
 * The FOOOF structure contains six additional elements:
  * '''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.
  * '''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.<<BR>><<BR>> {{attachment:FOOOF_peaks.png||width="370",height="220"}}
  * '''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. <<BR>><<BR>> {{attachment:FOOOF_aperiodic.png||width="370",height="220"}}
  * '''stats''': a struct containing every model’s channel of origin, MSE, R-squared, and absolute frequency-wise error. <<BR>><<BR>> {{attachment:FOOOF_stats.png||width="370",height="220"}}

== Convert FOOOF model parameters to regular PSD files ==
You can convert parameters of a FOOOF model to regular PSD files. This can be useful, as it allows using all the processes for PSD on FOOOF model parameters. For example, to export FOOOF model parameters as [[ExportSpm12|SPM surfaces]],[[ExportSpm8|SPM volumes]], [[Tutorials/TimeFrequency#Process_options|group in frequency bands]], etc.

 * In Process1: Select the FOOOF model file.
 * Run process: "'''Frequency > specparam: Extract measure'''":
  * specparam meaure: '''Peaks only'''
<<BR>>
  {{attachment:gui_extract_fooof_measure.gif||width="80%"}}

 * A new file with the same name but without the "'''| peaks'''" tag is created. This file is a regular PSD file that you can use with any process. When you open it, the FOOOF options do not show up.

== Python implementation ==
Some process options are only available in the MATLAB version. 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.

If you would prefer to use the algorithm in its original state, you can instead select '''FOOOF version: Python'''. To use the Python version, some configuration of your system is required.

 * To direct MATLAB to the correct Python executable, use the function  [[http://www.mathworks.com/help/matlab/ref/pyenv.html|pyenv]] (>= 2019b) or [[http://www.mathworks.com/help/matlab/ref/pyversion.html|pyversion]] (=< 2019a) after starting up MATLAB. Read this [[https://irenevigueguix.wordpress.com/2020/03/25/loading-python-into-matlab/|blog post]] for more information.
 * You must have also downloaded and installed '''SciPy''', '''NumPy''', and '''FOOOF''' Python libraries on your computer ([[https://fooof-tools.github.io/fooof/|installation instructions]]).
 * Your Python environment must 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 ([[https://www.mathworks.com/matlabcentral/answers/94933-how-do-i-edit-my-system-path-in-windows|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
}}}

== 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 is due to Thomas Donoghue, Matar Haller, Erik Peterson, Paroma Varma, Priyadarshini Sebastian, Richard Gao, Torben Noto, Antonio H. Lara, Joni D. Wallis, Robert T. Knight, Avgusta Shestyuk, and Bradley Voytek. The appropriate citation for FOOOF is as follows:

Donoghue, T., Haller, M., Peterson, E.J. et al. Parameterizing neural power spectra into periodic and aperiodic components. Nat Neurosci 23, 1655–1665 (2020). https://doi.org/10.1038/s41593-020-00744-x