fooof.FOOOF

class fooof.FOOOF(peak_width_limits=0.5, 12.0, max_n_peaks=inf, min_peak_height=0.0, peak_threshold=2.0, aperiodic_mode='fixed', verbose=True)[source]

Model a physiological power spectrum as a combination of aperiodic and periodic components.

WARNING: FOOOF expects frequency and power values in linear space.

Passing in logged frequencies and/or power spectra is not detected, and will silently produce incorrect results.

Parameters
peak_width_limitstuple of (float, float), optional, default: (0.5, 12.0)

Limits on possible peak width, in Hz, as (lower_bound, upper_bound).

max_n_peaksint, optional, default: inf

Maximum number of peaks to fit.

min_peak_heightfloat, optional, default: 0

Absolute threshold for detecting peaks, in units of the input data.

peak_thresholdfloat, optional, default: 2.0

Relative threshold for detecting peaks, in units of standard deviation of the input data.

aperiodic_mode{‘fixed’, ‘knee’}

Which approach to take for fitting the aperiodic component.

verbosebool, optional, default: True

Verbosity mode. If True, prints out warnings and general status updates.

Notes

  • Commonly used abbreviations used in this module include: CF: center frequency, PW: power, BW: Bandwidth, AP: aperiodic

  • Input power spectra must be provided in linear scale. Internally they are stored in log10 scale, as this is what the model operates upon.

  • Input power spectra should be smooth, as overly noisy power spectra may lead to bad fits. For example, raw FFT inputs are not appropriate. Where possible and appropriate, use longer time segments for power spectrum calculation to get smoother power spectra, as this will give better model fits.

  • The gaussian params are those that define the gaussian of the fit, where as the peak params are a modified version, in which the CF of the peak is the mean of the gaussian, the PW of the peak is the height of the gaussian over and above the aperiodic component, and the BW of the peak, is 2*std of the gaussian (as ‘two sided’ bandwidth).

Attributes
freqs1d array

Frequency values for the power spectrum.

power_spectrum1d array

Power values, stored internally in log10 scale.

freq_rangelist of [float, float]

Frequency range of the power spectrum, as [lowest_freq, highest_freq].

freq_resfloat

Frequency resolution of the power spectrum.

fooofed_spectrum_1d array

The full model fit of the power spectrum, in log10 scale.

aperiodic_params_1d array

Parameters that define the aperiodic fit. As [Offset, (Knee), Exponent]. The knee parameter is only included if aperiodic component is fit with a knee.

peak_params_2d array

Fitted parameter values for the peaks. Each row is a peak, as [CF, PW, BW].

gaussian_params_2d array

Parameters that define the gaussian fit(s). Each row is a gaussian, as [mean, height, standard deviation].

r_squared_float

R-squared of the fit between the input power spectrum and the full model fit.

error_float

Error of the full model fit.

n_peaks_int

How many peaks were fit in the model.

has_databool

Indicator for if the object contains data.

has_modelbool

Indicator for if the object contains a model fit.

__init__(peak_width_limits=0.5, 12.0, max_n_peaks=inf, min_peak_height=0.0, peak_threshold=2.0, aperiodic_mode='fixed', verbose=True)[source]

Initialize object with desired settings.

Methods

__init__([peak_width_limits, max_n_peaks, …])

Initialize object with desired settings.

add_data(freqs, power_spectrum[, freq_range])

Add data (frequencies, and power spectrum values) to the current object.

add_meta_data(fooof_meta_data)

Add data information into object from a FOOOFMetaData object.

add_results(fooof_result)

Add results data into object from a FOOOFResults object.

add_settings(fooof_settings)

Add settings into object from a FOOOFSettings object.

copy()

Return a copy of the current object.

fit([freqs, power_spectrum, freq_range])

Fit the full power spectrum as a combination of periodic and aperiodic components.

get_meta_data()

Return data information from the current object.

get_params(name[, col])

Return model fit parameters for specified feature(s).

get_results()

Return model fit parameters and goodness of fit metrics.

get_settings()

Return user defined settings of the current object.

load(file_name[, file_path, regenerate])

Load in a FOOOF formatted JSON file to the current object.

plot([plot_peaks, plot_aperiodic, plt_log, …])

Plot the power spectrum and model fit results from a FOOOF object.

print_report_issue([concise])

Prints instructions on how to report bugs and/or problematic fits.

print_results([concise])

Print out model fitting results.

print_settings([description, concise])

Print out the current settings.

report([freqs, power_spectrum, freq_range, …])

Run model fit, and display a report, which includes a plot, and printed results.

save(file_name[, file_path, append, …])

Save out data, results and/or settings from a FOOOF object into a JSON file.

save_report(file_name[, file_path, plt_log])

Generate and save out a PDF report for a power spectrum model fit.

set_debug_mode(debug)

Set whether debug mode, wherein an error is raised if fitting is unsuccessful.

Attributes

has_data

Indicator for if the object contains data.

has_model

Indicator for if the object contains a model fit.

n_peaks_

How many peaks were fit in the model.

add_data(freqs, power_spectrum, freq_range=None)[source]

Add data (frequencies, and power spectrum values) to the current object.

Parameters
freqs1d array

Frequency values for the power spectrum, in linear space.

power_spectrum1d array

Power spectrum values, which must be input in linear space.

freq_rangelist of [float, float], optional

Frequency range to restrict power spectrum to. If not provided, keeps the entire range.

Notes

If called on an object with existing data and/or results they will be cleared by this method call.

add_meta_data(fooof_meta_data)[source]

Add data information into object from a FOOOFMetaData object.

Parameters
fooof_meta_dataFOOOFMetaData

A meta data object containing meta data information.

add_results(fooof_result)[source]

Add results data into object from a FOOOFResults object.

Parameters
fooof_resultFOOOFResults

A data object containing the results from fitting a FOOOF model.

add_settings(fooof_settings)[source]

Add settings into object from a FOOOFSettings object.

Parameters
fooof_settingsFOOOFSettings

A data object containing the settings for a FOOOF model.

copy()[source]

Return a copy of the current object.

fit(freqs=None, power_spectrum=None, freq_range=None)[source]

Fit the full power spectrum as a combination of periodic and aperiodic components.

Parameters
freqs1d array, optional

Frequency values for the power spectrum, in linear space.

power_spectrum1d array, optional

Power values, which must be input in linear space.

freq_rangelist of [float, float], optional

Frequency range to restrict power spectrum to. If not provided, keeps the entire range.

Raises
NoDataError

If no data is available to fit.

FitError

If model fitting fails to fit. Only raised in debug mode.

Notes

Data is optional, if data has already been added to the object.

get_meta_data()[source]

Return data information from the current object.

Returns
FOOOFMetaData

Object containing meta data from the current object.

get_params(name, col=None)[source]

Return model fit parameters for specified feature(s).

Parameters
name{‘aperiodic_params’, ‘peak_params’, ‘gaussian_params’, ‘error’, ‘r_squared’}

Name of the data field to extract.

col{‘CF’, ‘PW’, ‘BW’, ‘offset’, ‘knee’, ‘exponent’} or int, optional

Column name / index to extract from selected data, if requested. Only used for name of {‘aperiodic_params’, ‘peak_params’, ‘gaussian_params’}.

Returns
outfloat or 1d array

Requested data.

Raises
NoModelError

If there are no model fit parameters available to return.

Notes

For further description of the data you can extract, check the FOOOFResults documentation.

If there is no data on periodic features, this method will return NaN.

get_results()[source]

Return model fit parameters and goodness of fit metrics.

Returns
FOOOFResults

Object containing the model fit results from the current object.

get_settings()[source]

Return user defined settings of the current object.

Returns
FOOOFSettings

Object containing the settings from the current object.

property has_data

Indicator for if the object contains data.

property has_model

Indicator for if the object contains a model fit.

Notes

This check uses the aperiodic params, which are:

  • nan if no model has been fit

  • necessarily defined, as floats, if model has been fit

load(file_name, file_path=None, regenerate=True)[source]

Load in a FOOOF formatted JSON file to the current object.

Parameters
file_namestr or FileObject

File to load data from.

file_pathstr or None, optional

Path to directory to load from. If None, loads from current directory.

regeneratebool, optional, default: True

Whether to regenerate the model fit from the loaded data, if data is available.

property n_peaks_

How many peaks were fit in the model.

plot(plot_peaks=None, plot_aperiodic=True, plt_log=False, add_legend=True, save_fig=False, file_name=None, file_path=None, ax=None, plot_style=<function style_spectrum_plot>, data_kwargs=None, model_kwargs=None, aperiodic_kwargs=None, peak_kwargs=None)[source]

Plot the power spectrum and model fit results from a FOOOF object.

Parameters
plot_peaksNone or {‘shade’, ‘dot’, ‘outline’, ‘line’}, optional

What kind of approach to take to plot peaks. If None, peaks are not specifically plotted. Can also be a combination of approaches, separated by ‘-‘, for example: ‘shade-line’.

plot_aperiodicboolean, optional, default: True

Whether to plot the aperiodic component of the model fit.

plt_logboolean, optional, default: False

Whether to plot the frequency values in log10 spacing.

add_legendboolean, optional, default: False

Whether to add a legend describing the plot components.

save_figbool, optional, default: False

Whether to save out a copy of the plot.

file_namestr, optional

Name to give the saved out file.

file_pathstr, optional

Path to directory to save to. If None, saves to current directory.

axmatplotlib.Axes, optional

Figure axes upon which to plot.

plot_stylecallable, optional, default: style_spectrum_plot

A function to call to apply styling & aesthetics to the plot.

data_kwargs, model_kwargs, aperiodic_kwargs, peak_kwargsNone or dict, optional

Keyword arguments to pass into the plot call for each plot element.

Notes

Since FOOOF objects store power values in log spacing, the y-axis (power) is plotted in log spacing by default.

static print_report_issue(concise=False)[source]

Prints instructions on how to report bugs and/or problematic fits.

Parameters
concisebool, optional, default: False

Whether to print the report in a concise mode, or not.

print_results(concise=False)[source]

Print out model fitting results.

Parameters
concisebool, optional, default: False

Whether to print the report in a concise mode, or not.

print_settings(description=False, concise=False)[source]

Print out the current settings.

Parameters
descriptionbool, optional, default: False

Whether to print out a description with current settings.

concisebool, optional, default: False

Whether to print the report in a concise mode, or not.

report(freqs=None, power_spectrum=None, freq_range=None, plt_log=False)[source]

Run model fit, and display a report, which includes a plot, and printed results.

Parameters
freqs1d array, optional

Frequency values for the power spectrum.

power_spectrum1d array, optional

Power values, which must be input in linear space.

freq_rangelist of [float, float], optional

Desired frequency range to fit the model to. If not provided, fits across the entire given range.

plt_logbool, optional, default: False

Whether or not to plot the frequency axis in log space.

Notes

Data is optional, if data has already been added to the object.

save(file_name, file_path=None, append=False, save_results=False, save_settings=False, save_data=False)[source]

Save out data, results and/or settings from a FOOOF object into a JSON file.

Parameters
file_namestr or FileObject

File to save data to.

file_pathstr, optional

Path to directory to save to. If None, saves to current directory.

appendbool, optional, default: False

Whether to append to an existing file, if available. This option is only valid (and only used) if ‘file_name’ is a str.

save_resultsbool, optional

Whether to save out FOOOF model fit results.

save_settingsbool, optional

Whether to save out FOOOF settings.

save_databool, optional

Whether to save out input data.

Raises
ValueError

If the save file is not understood.

save_report(file_name, file_path=None, plt_log=False)[source]

Generate and save out a PDF report for a power spectrum model fit.

Parameters
file_namestr

Name to give the saved out file.

file_pathstr, optional

Path to directory to save to. If None, saves to current directory.

plt_logbool, optional, default: False

Whether or not to plot the frequency axis in log space.

set_debug_mode(debug)[source]

Set whether debug mode, wherein an error is raised if fitting is unsuccessful.

Parameters
debugbool

Whether to run in debug mode.