= 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 [[https://fooof-tools.github.io/fooof/|FOOOF GitHub]].<<BR>><<BR>> {{attachment:FOOOF_schematic.png||height="433",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 > Generate FOOOF models'''". <<BR>><<BR>> {{attachment:FOOOF_pipeline.png||height="170",width="250"}}
 * Select the following option:
  * '''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.
 * Click "'''Edit...'''" on '''FOOOF options'''.<<BR>><<BR>> {{attachment:FOOOF_options.png||height="280",width="300""}}
 * Calibrate the settings as follows:
  * '''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: 2]. <<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.
 * Save your settings by clicking [OK].
 * Click on [Run].