|
Size: 13791
Comment:
|
Size: 12520
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 6: | Line 6: |
| ''Note: ''The FOOOF algorithm has recently been renamed by its authors to'' specparam''. |
|
| Line 9: | Line 11: |
| 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||width="600",height="400"}} | 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||height="400",width="600"}} |
| Line 20: | Line 22: |
| * Select the process "'''Frequency > FOOOF > Generate FOOOF models'''". <<BR>><<BR>> {{attachment:psd_select.gif||width="170",height="324"}} {{attachment:FOOOF_pipeline.png||width="250",height="170"}} * 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||width="300",height="260""}} * 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: 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||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. * 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]. |
* 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 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 broad range of frequencies, and should be set with respect to 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||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. 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). |
| Line 45: | Line 48: |
| * 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"}} |
* 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"}} |
| Line 50: | Line 53: |
| == Extracting parameter values for further analysis == | == Accessing FOOOF model parameters == |
| Line 53: | Line 56: |
| * 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||width="260",height="170"}} * 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||width="250",height="220"}} <<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||width="325",height="161"}} * 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||width="414",height="148"}} * 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||width="500",height="220"}} * '''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||width="500",height="220"}} * '''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||width="500",height="220"}} |
* 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 > Options > FOOOF'''") or the command line ('''FOOOF_file.Options.FOOOF''').<<BR>> {{attachment:FOOOF_workspace.png||height="148",width="344"}} {{attachment:FOOOF_struct.png||height="148",width="274"}} * 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||height="220",width="370"}} * '''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||height="220",width="370"}} * '''stats''': a struct containing every model’s channel of origin, MSE, R-squared, and absolute frequency-wise error. <<BR>><<BR>> {{attachment:FOOOF_stats.png||height="220",width="370"}} == 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 }}} |
| Line 87: | Line 82: |
| 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: | 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: |
| Line 89: | Line 84: |
| 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 | 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 |
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.
Note: The FOOOF algorithm has recently been renamed by its authors to specparam.
Contents
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 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.Ignore power line frequencies: None [default: 60 Hz].
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 broad range of frequencies, and should be set with respect to one's region.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.
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).
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 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.
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.
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 pyenv (>= 2019b) or pyversion (=< 2019a) after starting up MATLAB. Read this blog post for more information.
You must have also downloaded and installed SciPy, NumPy, and FOOOF Python libraries on your computer (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 (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