= 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.

<<TableOfContents(2,2)>>

== 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 [[https://fooof-tools.github.io/fooof/|FOOOF GitHub]].<<BR>><<BR>> {{attachment:FOOOF_schematic.png||height="400",width="600"}}

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||height="324",width="170"}}
 {{attachment:FOOOF_options.png||height="324",width="220"}}
 * Select the following 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.
  * '''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.
  * '''Peak threshold''': 2 standard deviations of the noise floor [default: 2 standard deviations]. <<BR>> Similar to minimum peak height, peaks with an amplitude within this value of standard deviations of the flattened (aperiodic removed) spectrum’s power levels 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.
  * '''Threshold after fitting''': Yes [default: No]. <<BR>> Slight differences in methodology between the MATLAB and Python builds of FOOOF occasionally allows for certain modelled peaks to be maintained in the final model, despite not adhering to previous requirements (peak width limits, minimum peak height, proximity threshold). This can only occur in the MATLAB build of FOOOF; however, selecting this option ensures this does not happen.
  * '''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||height="300",width="350"}}
  * '''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.
 * Some of these options are only available in the MATLAB version, including “'''peak model'''”, “'''proximity threshold'''”, “'''threshold after fitting'''”, 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 [[https://www.mathworks.com/help/matlab/ref/pyenv.html|here]]; [[https://www.mathworks.com/help/matlab/ref/pyversion.html|here]] is an alternative function). Read this [[https://irenevigueguix.wordpress.com/2020/03/25/loading-python-into-matlab/|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 ([[https://fooof-tools.github.io/fooof/|installation instructions]]).
 * Save your settings by clicking [OK].
 * 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).<<BR>><<BR>> {{attachment:FOOOF_display.png||height="370",width="650"}}
 * Try all the display options: <<BR>><<BR>> {{attachment:FOOOF_model.gif||height="229",width="470"}}

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.

== Extracting parameter values for further analysis ==
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.

 * Clear the list of files in the Process1 tab.
 * Select the three new FOOOF files from the three datasets we have linked to our protocol and load them into Process1.
 * Click on [Run] to open the pipeline editor window.
 * Select the process "'''Frequency > FOOOF > Extract FOOOF features'''". <<BR>><<BR>> {{attachment:FOOOF_extract.png||height="170",width="260"}}
 * In the interests of completeness, this demonstration will use every option available. Select the following options:
  * '''Extract peaks''': Yes
  * '''Extract aperiodic''': Yes
  * '''Extract stats''': Yes
 * Now, click "'''Edit...'''" on '''Manage Options'''. <<BR>><<BR>> {{attachment:FOOOF_extractionOptions.png||height="220",width="250"}} <<BR>> Some of the options we just selected have specific settings associated with them; choosing one setting over another will not manipulate the values of their outputs, only their order or presence. Choose the following settings:
  * '''Peak extraction settings''':
   * '''Peak parameters''': Extract and sort peaks by their properties.
   * '''Frequency''': Grouping peaks into frequency bands.
  * '''Stat extraction settings''': Select only the statistical values you need
   * '''MSE''': Mean-squared-error
   * '''R-squared''': Model goodness-of-fit
   * '''Absolute error by frequency''': Frequency-wise error of the model (helpful for determining whether any frequency of the model show systematic increases in error).
 ('''Note''': there are no options for extracting the aperiodic parameters; rest assured, if you have selected this option, they will be extracted.)
 * Click [OK] to save your settings, and then click [Run].
 * After the process has completed, all of the FOOOF files involved in the process will have their comments altered to include “Analyzed”.
 * 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||height="161",width="325"}}
 * In MATLAB, you can explore the contents of the file using the tab "Workspace" (navigate to "FOOOF_file > FOOOF") or the command line (FOOOF_file.FOOOF).<<BR>><<BR>> {{attachment:FOOOF_var.gif||height="148",width="414"}}
 * The first three elements are always present after computing FOOOF on the PSD file:
  * '''FOOOF_options''': all of the settings for the algorithm.
  * '''FOOOF_freqs''': all of the specific frequencies used in the model.
  * '''FOOOF_data''': channel-specific FOOOF models, in the same order as present in Brainstorm.
 * The following three elements are the product of extracting model properties:
  * '''extractedPeaks''': a table 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||height="220",width="500"}}
  * '''extractedAperiodics''': a table 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||height="220",width="500"}}
  * '''extractedStats''': a table containing every model’s channel of origin, MSE (if selected), R-squared (if selected), and absolute frequency-wise error (if selected). <<BR>><<BR>> {{attachment:FOOOF_stats.png||height="220",width="500"}}

== 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