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)