fooof.FOOOFGroup

class fooof.FOOOFGroup(*args, **kwargs)[source]

Model a group of power spectra 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. This threshold is defined in absolute units of the power spectrum (log power).

peak_thresholdfloat, optional, default: 2.0

Relative threshold for detecting peaks. This threshold is defined in relative units of the power spectrum (standard deviation).

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

  • The FOOOFGroup object inherits from the FOOOF object. As such it also has data attributes (power_spectrum & fooofed_spectrum_), and parameter attributes (aperiodic_params_, peak_params_, gaussian_params_, r_squared_, error_) which are defined in the context of individual model fits. These attributes are used during the fitting process, but in the group context do not store results post-fitting. Rather, all model fit results are collected and stored into the group_results attribute. To access individual parameters of the fit, use the get_params method.

Attributes
freqs1d array

Frequency values for the power spectra.

power_spectra2d array

Power values for the group of power spectra, as [n_power_spectra, n_freqs]. Power values are stored internally in log10 scale.

freq_rangelist of [float, float]

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

freq_resfloat

Frequency resolution of the power spectra.

group_resultslist of FOOOFResults

Results of FOOOF model fit for each power spectrum.

has_databool

Indicator for if the object contains data.

has_modelbool

Indicator for if the object contains model fits.

n_peaks_int

How many peaks were fit for each model.

n_null_int

How many model fits are null.

null_inds_list of int

The indices for model fits that are null.

__init__(*args, **kwargs)[source]

Initialize object with desired settings.

Methods

__init__(*args, **kwargs)

Initialize object with desired settings.

add_data(freqs, power_spectra[, 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.

drop(inds)

Drop one or more model fit results from the object.

fit([freqs, power_spectra, freq_range, ...])

Fit a group of power spectra.

get_data([component, space])

Get a data component.

get_fooof(ind[, regenerate])

Get a FOOOF object for a specified model fit.

get_group(inds)

Get a FOOOFGroup object with the specified sub-selection of model fits.

get_meta_data()

Return data information from the current object.

get_model([component, space])

Get a model component.

get_params(name[, col])

Return model fit parameters for specified feature(s).

get_results()

Return the results run across a group of power spectra.

get_run_modes()

Return run modes of the current object.

get_settings()

Return user defined settings of the current object.

load(file_name[, file_path])

Load FOOOFGroup data from file.

plot([save_fig, file_name, file_path])

Plot a figure with subplots visualizing the parameters from a FOOOFGroup object.

print_report_issue([concise])

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

print_results([concise])

Print out FOOOFGroup results.

print_settings([description, concise])

Print out the current settings.

report([freqs, power_spectra, freq_range, ...])

Fit a group of power spectra and display a report, with a plot and printed results.

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

Save out results and/or settings from FOOOFGroup object.

save_model_report(index, file_name[, ...])

"Save out an individual model report for a specified model fit.

save_report(file_name[, file_path, add_settings])

Generate and save out a PDF report for a group of power spectrum models.

set_check_data_mode(check_data)

Set check data mode, which controls if an error is raised if NaN or Inf data are added.

set_check_modes([check_freqs, check_data])

Set check modes, which controls if an error is raised based on check on the inputs.

set_debug_mode(debug)

Set debug mode, which controls if an error is raised if model fitting is unsuccessful.

set_run_modes(debug, check_freqs, check_data)

Simultaneously set all run modes.

to_df(peak_org)

Convert and extract the model results as a pandas object.

Attributes

has_data

Indicator for if the object contains data.

has_model

Indicator for if the object contains model fits.

n_null_

How many model fits are null.

n_peaks_

How many peaks were fit for each model.

null_inds_

The indices for model fits that are null.

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

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

Parameters
freqs1d array

Frequency values for the power spectra, in linear space.

power_spectra2d array, shape=[n_power_spectra, n_freqs]

Matrix of power values, in linear space.

freq_rangelist of [float, float], optional

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

Notes

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

add_meta_data(fooof_meta_data)

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)

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)

Add settings into object from a FOOOFSettings object.

Parameters
fooof_settingsFOOOFSettings

A data object containing the settings for a FOOOF model.

copy()

Return a copy of the current object.

drop(inds)[source]

Drop one or more model fit results from the object.

Parameters
indsint or array_like of int or array_like of bool

Indices to drop model fit results for. If a boolean mask, True indicates indices to drop.

Notes

This method sets the model fits as null, and preserves the shape of the model fits.

fit(freqs=None, power_spectra=None, freq_range=None, n_jobs=1, progress=None)[source]

Fit a group of power spectra.

Parameters
freqs1d array, optional

Frequency values for the power_spectra, in linear space.

power_spectra2d array, shape: [n_power_spectra, n_freqs], optional

Matrix of power spectrum values, in linear space.

freq_rangelist of [float, float], optional

Desired frequency range to run FOOOF on. If not provided, fits the entire given range.

n_jobsint, optional, default: 1

Number of jobs to run in parallel. 1 is no parallelization. -1 uses all available cores.

progress{None, ‘tqdm’, ‘tqdm.notebook’}, optional

Which kind of progress bar to use. If None, no progress bar is used.

Notes

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

get_data(component='full', space='log')

Get a data component.

Parameters
component{‘full’, ‘aperiodic’, ‘peak’}
Which data component to return.

‘full’ - full power spectrum ‘aperiodic’ - isolated aperiodic data component ‘peak’ - isolated peak data component

space{‘log’, ‘linear’}
Which space to return the data component in.

‘log’ - returns in log10 space. ‘linear’ - returns in linear space.

Returns
output1d array

Specified data component, in specified spacing.

Notes

The ‘space’ parameter doesn’t just define the spacing of the data component values, but rather defines the space of the additive data definition such that power_spectrum = aperiodic_component + peak_component. With space set as ‘log’, this combination holds in log space. With space set as ‘linear’, this combination holds in linear space.

get_fooof(ind, regenerate=True)[source]

Get a FOOOF object for a specified model fit.

Parameters
indint

The index of the FOOOFResults in FOOOFGroup.group_results to load.

regeneratebool, optional, default: False

Whether to regenerate the model fits from the given fit parameters.

Returns
fmFOOOF

The FOOOFResults data loaded into a FOOOF object.

get_group(inds)[source]

Get a FOOOFGroup object with the specified sub-selection of model fits.

Parameters
indsarray_like of int or array_like of bool

Indices to extract from the object. If a boolean mask, True indicates indices to select.

Returns
fgFOOOFGroup

The requested selection of results data loaded into a new FOOOFGroup object.

get_meta_data()

Return data information from the current object.

Returns
FOOOFMetaData

Object containing meta data from the current object.

get_model(component='full', space='log')

Get a model component.

Parameters
component{‘full’, ‘aperiodic’, ‘peak’}
Which model component to return.

‘full’ - full model ‘aperiodic’ - isolated aperiodic model component ‘peak’ - isolated peak model component

space{‘log’, ‘linear’}
Which space to return the model component in.

‘log’ - returns in log10 space. ‘linear’ - returns in linear space.

Returns
output1d array

Specified model component, in specified spacing.

Notes

The ‘space’ parameter doesn’t just define the spacing of the model component values, but rather defines the space of the additive model such that model = aperiodic_component + peak_component. With space set as ‘log’, this combination holds in log space. With space set as ‘linear’, this combination holds in linear space.

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 across the group.

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
outndarray

Requested data.

Raises
NoModelError

If there are no model fit results available.

ValueError

If the input for the col input is not understood.

Notes

When extracting peak information (‘peak_params’ or ‘gaussian_params’), an additional column is appended to the returned array, indicating the index of the model that the peak came from.

get_results()[source]

Return the results run across a group of power spectra.

get_run_modes()

Return run modes of the current object.

Returns
FOOOFRunModes

Object containing the run modes from the current object.

get_settings()

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 model fits.

load(file_name, file_path=None)[source]

Load FOOOFGroup data from file.

Parameters
file_namestr

File to load data from.

file_pathPath or str, optional

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

property n_null_

How many model fits are null.

property n_peaks_

How many peaks were fit for each model.

property null_inds_

The indices for model fits that are null.

plot(save_fig=False, file_name=None, file_path=None, **plot_kwargs)[source]

Plot a figure with subplots visualizing the parameters from a FOOOFGroup object.

Parameters
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_pathPath or str, optional

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

**plot_kwargs

Additional plot related keyword arguments, with styling options managed by style_plot.

Raises
NoModelError

If the FOOOF object does not have model fit data available to plot.

static print_report_issue(concise=False)

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 FOOOFGroup results.

Parameters
concisebool, optional, default: False

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

print_settings(description=False, concise=False)

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_spectra=None, freq_range=None, n_jobs=1, progress=None)[source]

Fit a group of power spectra and display a report, with a plot and printed results.

Parameters
freqs1d array, optional

Frequency values for the power_spectra, in linear space.

power_spectra2d array, shape: [n_power_spectra, n_freqs], optional

Matrix of power spectrum values, in linear space.

freq_rangelist of [float, float], optional

Desired frequency range to run FOOOF on. If not provided, fits the entire given range.

n_jobsint, optional, default: 1

Number of jobs to run in parallel. 1 is no parallelization. -1 uses all available cores.

progress{None, ‘tqdm’, ‘tqdm.notebook’}, optional

Which kind of progress bar to use. If None, no progress bar is used.

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 results and/or settings from FOOOFGroup object. Saves out to a JSON file.

Parameters
file_namestr or FileObject

File to save data to.

file_pathPath or str, optional

Path to directory to load from. If None, loads from 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 power spectra data.

Raises
ValueError

If the data or save file specified are not understood.

save_model_report(index, file_name, file_path=None, plt_log=False, add_settings=True, **plot_kwargs)[source]

“Save out an individual model report for a specified model fit.

Parameters
indexint

Index of the model fit to save out.

file_namestr

Name to give the saved out file.

file_pathPath or str, 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.

add_settingsbool, optional, default: True

Whether to add a print out of the model settings to the end of the report.

plot_kwargskeyword arguments

Keyword arguments to pass into the plot method.

save_report(file_name, file_path=None, add_settings=True)[source]

Generate and save out a PDF report for a group of power spectrum models.

Parameters
file_namestr

Name to give the saved out file.

file_pathPath or str, optional

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

add_settingsbool, optional, default: True

Whether to add a print out of the model settings to the end of the report.

set_check_data_mode(check_data)

Set check data mode, which controls if an error is raised if NaN or Inf data are added.

Parameters
check_databool

Whether to run in check data mode.

set_check_modes(check_freqs=None, check_data=None)

Set check modes, which controls if an error is raised based on check on the inputs.

Parameters
check_freqsbool, optional

Whether to run in check freqs mode, which checks the frequency data.

check_databool, optional

Whether to run in check data mode, which checks the power spectrum values data.

set_debug_mode(debug)

Set debug mode, which controls if an error is raised if model fitting is unsuccessful.

Parameters
debugbool

Whether to run in debug mode.

set_run_modes(debug, check_freqs, check_data)

Simultaneously set all run modes.

Parameters
debugbool

Whether to run in debug mode.

check_freqsbool

Whether to run in check freqs mode.

check_databool

Whether to run in check data mode.

to_df(peak_org)[source]

Convert and extract the model results as a pandas object.

Parameters
peak_orgint or Bands

How to organize peaks. If int, extracts the first n peaks. If Bands, extracts peaks based on band definitions.

Returns
pd.DataFrame

Model results organized into a pandas object.

Examples using fooof.FOOOFGroup

Exporting Model Results

Exporting Model Results

Failed Model Fits

Failed Model Fits

Fitting Power Spectrum Models Across 3D Arrays

Fitting Power Spectrum Models Across 3D Arrays

Manipulating FOOOF Objects

Manipulating FOOOF Objects

Aperiodic Parameters

Aperiodic Parameters

Frequency-by-Frequency Errors

Frequency-by-Frequency Errors

Plot Model Components

Plot Model Components

Developmental Data Demo

Developmental Data Demo

Topographical Analyses with MNE

Topographical Analyses with MNE

06: FOOOFGroup

06: FOOOFGroup

07: Tuning & Troubleshooting

07: Tuning & Troubleshooting

08: Further Analysis

08: Further Analysis

09: Reporting & Referencing

09: Reporting & Referencing