API Documentation¶

API reference for the module.

Table of Contents¶

Model Objects ¶

Objects that manage data and fit the model to parameterize neural power spectra.

Base Object ¶

The SpectralModel object is the base object for the model, and can be used to fit individual power spectra.

SpectralModel([peak_width_limits, ...])

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

Group Object ¶

The SpectralGroupModel object allows for parameterizing groups of power spectra.

SpectralGroupModel(*args, **kwargs)

Model a group of power spectra as a combination of aperiodic and periodic components.

Time & Event Objects ¶

The time & event objects allows for parameterizing power spectra organized across time and/or events.

`SpectralTimeModel`(args, *kwargs)	Model a spectrogram as a combination of aperiodic and periodic components.
`SpectralTimeEventModel`(args, *kwargs)	Model a set of event as a combination of aperiodic and periodic components.

Object Utilities ¶

Functions to manipulate, examine, and analyze model objects.

`compare_model_objs`(model_objs, aspect)	Compare multiple model, checking for consistent attributes.
`combine_model_objs`(model_objs)	Combine a group of model objects into a single group model object.
`average_group`(group, bands[, avg_method, ...])	Average across model fits in a group model object.
`average_reconstructions`(group[, avg_method])	Average across model reconstructions for a group of power spectra.

fit_models_3d(group, freqs, power_spectra[, ...])

Fit power spectrum models across a 3d array of power spectra.

Data Objects ¶

Objects to manage frequency bands, model information, and simulation parameters.

Bands Object ¶

An object to handle frequency band definitions.

Bands([input_bands])

Frequency band definitions.

Model Information ¶

Objects to store settings, metadata and results for power spectrum models.

`SpectrumMetaData`(freq_range, freq_res)	Metadata information about a power spectrum.
`ModelSettings`(peak_width_limits, ...)	User defined settings for the fitting algorithm.
`ModelRunModes`(debug, check_freqs, check_data)	Checks performed and errors raised by the model.
`FitResults`(aperiodic_params, peak_params, ...)	Model results from parameterizing a power spectrum.

Simulation Parameters ¶

Object to store information about simulated data.

SimParams(aperiodic_params, periodic_params, nlv)

Parameters that define a simulated power spectrum.

Analyze Model Results ¶

Functions to analyze power spectrum models and the results parameters / components.

Analyze Model Errors ¶

Functions for analyzing the error of model fits.

Object Inputs

The following functions take in model objects directly.

`compute_pointwise_error`(model[, ...])	Calculate the frequency by frequency error of a model fit.
`compute_pointwise_error_group`(group[, ...])	Calculate the frequency by frequency error of model fits for a group of fits.

Array Inputs

The following functions operate on arrays of models and data, which may be useful for more custom work-flows.

compute_pointwise_error_arr(data_model, data)

Calculate point-wise error between original data and a model fit of that data.

Analyze Periodic Components ¶

Functions for analyzing the periodic components of model fits.

Object Inputs

The following functions take in model objects directly, which is the typical use case.

`get_band_peak`(model, band[, select_highest, ...])	Extract peaks from a band of interest from a model object.
`get_band_peak_group`(group, band[, ...])	Extract peaks from a band of interest from a group model object.
`get_band_peak_event`(event, band[, ...])	Extract peaks from a band of interest from an event model object.

Array Inputs

The following functions operate on arrays of peak parameters, which may be useful for more custom work-flows.

`get_band_peak_arr`(peak_params, band[, ...])	Extract peaks within a given band of interest.
`get_band_peak_group_arr`(peak_params, band, ...)	Extract peaks within a given band of interest, from peaks from a group fit.
`get_highest_peak`(peak_params)	Extract the highest power peak.
`threshold_peaks`(peak_params, threshold[, param])	Extract peaks that are above a given threshold value.

Simulation Code ¶

Code & utilities for simulating power spectra.

Generate Power Spectra ¶

Functions for simulating neural power spectra and spectrograms.

`sim_power_spectrum`(freq_range, ...[, nlv, ...])	Simulate a power spectrum.
`sim_group_power_spectra`(n_spectra, ...[, ...])	Simulate multiple power spectra.
`sim_spectrogram`(n_windows, freq_range, ...)	Simulate spectrogram.

Manage Parameters ¶

Functions and objects for managing parameters for simulated power spectra.

`Stepper`(start, stop, step)	Object for stepping across parameter values.
`param_iter`(params)	Create a generator to iterate across parameter ranges.
`param_sampler`(params[, probs])	Create a generator to sample randomly from possible parameters.
`param_jitter`(params, jitters)	Create a generator that adds jitter to parameter definitions.
`update_sim_ap_params`(sim_params, delta[, field])	Update the aperiodic parameter definition in a SimParams object.

Transform Power Spectra ¶

Functions for transforming power spectra.

`translate_spectrum`(power_spectrum, delta_offset)	Translate a spectrum, changing the offset value.
`translate_sim_spectrum`(power_spectrum, ...)	Translate a simulated spectrum, updating a SimParams object.
`rotate_spectrum`(freqs, power_spectrum, ...)	Rotate a power spectrum about a frequency point, changing the aperiodic exponent.
`rotate_sim_spectrum`(freqs, power_spectrum, ...)	Rotate a simulated power spectrum, updating a SimParams object.
`compute_rotation_offset`(delta_exponent, ...)	Calculate the change in offset from a given rotation.
`compute_rotation_frequency`(delta_exponent_b, ...)	Calculate the rotation frequency between two rotated power spectra.

Simulation Utilities ¶

Utilities for simulating power spectra.

`create_freqs`(freq_range, freq_res)	Generate a frequency vector.
`set_random_seed`([seed_value])	Set the random seed value.

Plotting Functions ¶

Visualizations.

Plot Power Spectra ¶

Plots for visualizing power spectra and spectrograms.

`plot_spectra`(freqs, power_spectra[, ...])	Plot one or multiple power spectra.
`plot_spectrogram`(freqs, powers[, times])	Plot a spectrogram.

Plots for plotting power spectra with shaded regions.

`plot_spectra_shading`(freqs, power_spectra, ...)	Plot one or multiple power spectra with a shaded frequency region (or regions).
`plot_spectra_yshade`(freqs, power_spectra[, ...])	Plot standard deviation or error as a shaded region around the mean spectrum.

Plot Model Properties & Parameters ¶

Plots for visualizing periodic parameters and model components.

`plot_peak_fits`(peaks[, freq_range, average, ...])	Plot reconstructions of model peak fits.
`plot_peak_params`(peaks[, freq_range, ...])	Plot peak parameters as dots representing center frequency, power and bandwidth.

Plots for visualizing aperiodic parameters and model components.

`plot_aperiodic_fits`(aps, freq_range[, ...])	Plot reconstructions of model aperiodic fits.
`plot_aperiodic_params`(aps[, colors, labels, ax])	Plot aperiodic parameters as dots representing offset and exponent value.

Plots for visualizing model error.

plot_spectral_error(freqs, error[, shade, ...])

Plot frequency by frequency error values.

Plot Model Objects ¶

Plots for visualizing from model objects. Note that these are the same plotting functions that can be called from the model objects directly.

plot_model(model[, plot_peaks, ...])

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

plot_group_model(group, **plot_kwargs)

Plot a figure with subplots visualizing the parameters from a group model object.

plot_time_model(time_model, **plot_kwargs)

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

plot_event_model(event_model, **plot_kwargs)

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

Annotated Plots ¶

Annotated plots that describe the model and fitting process.

`plot_annotated_model`(model[, plt_log, ...])	Plot a an annotated power spectrum and model, from a model object.
`plot_annotated_peak_search`(model)	Plot a series of plots illustrating the peak search from a flattened spectrum.

Plot Utilities & Styling ¶

Plot related utilies for styling and managing plots.

check_style_options()

Check the list of valid style arguments that can be passed into plot functions.

`check_ax`(ax[, figsize])	Check whether a figure axes object is defined, and define if not.
`recursive_plot`(data, plot_function, ax, **kwargs)	A utility to recursively plot sets of data.
`save_figure`(file_name[, file_path, close])	Save out a figure.

Utilities ¶

Utility functions and objects.

Data Utilities ¶

Utilities for working with data.

`trim_spectrum`(freqs, power_spectra, f_range)	Extract a frequency range from power spectra.
`interpolate_spectrum`(freqs, powers, interp_range)	Interpolate a frequency region in a power spectrum.
`interpolate_spectra`(freqs, powers, interp_range)	Interpolate a frequency region across a group of power spectra.
`subsample_spectra`(spectra, selection[, ...])	Subsample a group of power spectra.

Parameter Utilities ¶

Utilities for working with parameters

compute_knee_frequency(knee, exponent)

Compute the frequency value of the knee given the aperiodic parameter values.

Input / Output (IO)¶

`load_model`(file_name[, file_path, regenerate])	Load a model file into a model object.
`load_group_model`(file_name[, file_path])	Load a group file into a group model object.
`load_time_model`(file_name[, file_path, peak_org])	Load a time file into a time model object.
`load_event_model`(file_name[, file_path, ...])	Load an event file into an event model object.

Methods Reports ¶

Utilities to creating methods reports.

`methods_report_info`([model_obj, concise])	Prints out a report of information required for methods reporting.
`methods_report_text`([model_obj])	Prints out a text template of methods reporting information.