fooof.sim.gen_group_power_spectra

fooof.sim.gen_group_power_spectra(n_spectra, freq_range, aperiodic_params, periodic_params, nlvs=0.005, freq_res=0.5, f_rotation=None, return_params=False)[source]

Generate a group of simulated power spectra.

Parameters
n_spectraint

The number of power spectra to generate.

freq_rangelist of [float, float]

Frequency range to simulate power spectra across, as [f_low, f_high], inclusive.

aperiodic_paramslist of float or generator

Parameters for the aperiodic component of the power spectra.

periodic_paramslist of float or generator

Parameters for the periodic component of the power spectra. Length of n_peaks * 3.

nlvsfloat or list of float or generator, optional, default: 0.005

Noise level to add to generated power spectrum.

freq_resfloat, optional, default: 0.5

Frequency resolution for the simulated power spectra.

f_rotationfloat, optional

Frequency value, in Hz, to rotate around. Should only be set if spectra are to be rotated.

return_paramsbool, optional, default: False

Whether to return the parameters for the simulated spectra.

Returns
freqs1d array

Frequency values, in linear spacing.

powers2d array

Matrix of power values, in linear spacing, as [n_power_spectra, n_freqs].

sim_paramslist of SimParams

Definitions of parameters used for each spectrum. Has length of n_spectra. Only returned if return_params is True.

Notes

Parameters options can be:

  • A single set of parameters. If so, these same parameters are used for all spectra.

  • A list of parameters whose length is n_spectra. If so, each successive parameter set is such for each successive spectrum.

  • A generator object that returns parameters for a power spectrum. If so, each spectrum has parameters sampled from the generator.

Aperiodic Parameters:

  • The function for the aperiodic process to use is inferred from the provided parameters.

  • If length of 2, the ‘fixed’ aperiodic mode is used, if length of 3, ‘knee’ is used.

Periodic Parameters:

  • The periodic component is comprised of a set of ‘peaks’, each of which is described as:

    • Mean (Center Frequency), height (Power), and standard deviation (Bandwidth).

    • Make sure any center frequencies you request are within the simulated frequency range.

Rotating Power Spectra:

  • You can optionally specify a rotation frequency, such that power spectra will be simulated and rotated around that point to the specified aperiodic exponent.

    • This can be used so that any power spectra simulated with the same ‘f_rotation’ will relate to each other by having the specified rotation point.

  • Note that rotating power spectra changes the offset.

    • If you specify an offset value to simulate as well as ‘f_rotation’, the returned spectrum will NOT have the requested offset. It instead will have the offset value required to create the requested aperiodic exponent with the requested rotation point.

    • If you return SimParams, the recorded offset will be the calculated offset of the data post rotation, and not the entered value.

  • You cannot rotate power spectra simulated with a knee.

    • The procedure we use to rotate does not support spectra with a knee, and so setting ‘f_rotation’ with a knee will lead to an error.

Examples

Generate 2 power spectra using the same parameters:

>>> freqs, powers = gen_group_power_spectra(2, [1, 50], [0, 2], [10, 0.5, 1])

Generate 10 power spectra, randomly sampling possible parameters:

>>> from fooof.sim.params import param_sampler
>>> ap_opts = param_sampler([[0, 1.0], [0, 1.5], [0, 2]])
>>> pe_opts = param_sampler([[], [10, 0.5, 1], [10, 0.5, 1, 20, 0.25, 1]])
>>> freqs, powers = gen_group_power_spectra(10, [1, 50], ap_opts, pe_opts)

Generate 5 power spectra, rotated around 20 Hz:

>>> ap_params = [[None, 1], [None, 1.25], [None, 1.5], [None, 1.75], [None, 2]]
>>> pe_params = [10, 0.5, 1]
>>> freqs, powers = gen_group_power_spectra(5, [1, 50], ap_params, pe_params, f_rotation=20)

Generate power spectra stepping across exponent values, and return parameter values:

>>> from fooof.sim.params import Stepper, param_iter
>>> ap_params = param_iter([0, Stepper(1, 2, 0.25)])
>>> pe_params = [10, 0.5, 1]
>>> freqs, powers, sps = gen_group_power_spectra(5, [1, 50], ap_params, pe_params,
...                                              return_params=True)