General spectral analysis utilities (spynal.spectra.utils)

Utility functions for LFP/EEG/continuous data and spectral analysis

next_power_of_2(n)

Find next power of 2 (smallest power of 2 greater than n)

get_freq_sampling(smp_rate, n_fft, freq_range=None, two_sided=False)

Return frequency sampling vector (axis) for a given FFT-based computation

Parameters:

  • smp_rate (scalar) – Data sampling rate (Hz)

  • n_fft (scalar) – Number of samples (timepoints) in FFT output

  • freq_range (array-like, shape=(2,) or scalar, default: all frequencies from FFT) – Range of frequencies to retain in output, either given as an explicit [low,high] range or just a scalar giving the highest frequency to return.

two_sidedbool, default: False

If True, return freqs for two-sided spectrum, including both positive and negative frequencies (which have same amplitude for all real signals). If False, only return positive frequencies, in range (0,smp_rate/2).

Returns:

  • freqs (ndarray, shape=(n_freqs,)) – Frequency sampling vector (in Hz)

  • freq_bool (ndarray, shape=(n_fft,), dtype=bool) – Boolean vector flagging frequencies in full FFT output to retain, given desired freq_range

complex_to_spec_type(data, spec_type)

Converts complex spectral data to given spectral signal type

Parameters:

  • data (ndarray, shape=Any, dtype=complex) – Complex spectral (or time-frequency) data. Arbitrary shape.

  • spec_type ({'power','phase','magnitude','real','imag'}) –

    Type of spectral signal to return:

    • ’power’ Spectral power of data

    • ’phase’ Phase of complex spectral data (in radians)

    • ’magnitude’ Magnitude (square root of power) of complex data = signal envelope

    • ’real’ Real part of complex data

    • ’imag’ Imaginary part of complex data

Returns:

data – Computed spectral signal. Same shape as input.

Return type:

ndarray, shape=Any, dtype=complex

power(data)

Compute power from complex spectral data

magnitude(data)

Compute magnitude (square root of power) from complex spectral data

phase(data)

Compute phase of complex spectral data

real(data)

Return real part of complex spectral data

imag(data)

Return imaginary part of complex spectral data

one_sided_to_two_sided(data, freqs, smp_rate, axis=0)

Convert a one-sided Fourier/wavelet transform output to the two-sided equivalent.

Assumes conjugate symmetry across positive and negative frequencies (as is the case only when the original raw signals were real).

Also extrapolates values for f=0, as is necessary for wavelet transforms.

Parameters:

  • data (ndarray, shape=(...,n_freqs,...), dtype=complex) – Complex (1-sided) frequency-transformed data. Any arbitary shape.

  • freqs (array-like, shape=(n_freqs,)) – Frequency sampling in data

  • smp_rate (scalar) – Data sampling rate (Hz)

  • axis (int, default: 0 (1st axis)) – Data axis corresponding to frequency

Returns:

  • data (ndarray, shape=(…,2*n_freqs+1,…), dtype=complex) – 2-sided equivalent of input data

  • freqs (ndarray, shape=(2*n_freqs+1,)) – List of (positive and negative) freqs in 2-sided output data

simulate_oscillation(frequency, amplitude=5.0, phase=0, noise=1.0, n_trials=1000, freq_sd=0, amp_sd=0, phase_sd=0, smp_rate=1000, time_range=1.0, burst_rate=0, burst_width=4, seed=None)

Generate synthetic data with oscillation at given parameters.

Generate multiple trials with constant oscillatory signal + random additive Gaussian noise.

Parameters:

  • frequency (scalar) – Frequency to simulate oscillation at (Hz)

  • amplitude (scalar, default: 5.0) – Amplitude of simulated oscillation (a.u.)

  • phase (scalar, default: 0) – Phase of oscillation (rad)

  • noise (scalar, default: 1.0) – Amplitude of additive Gaussian noise (a.u)

  • n_trials (int, default: 1000) – Number of trials/observations to simulate

  • freq_sd (scalar, Default: 0 (no inter-trial variation)) – Inter-trial variation in frequency/amplitude/phase, given as Gaussian SD (same units as base parameters, which are used as Gaussian mean)

  • amp_sd (scalar, Default: 0 (no inter-trial variation)) – Inter-trial variation in frequency/amplitude/phase, given as Gaussian SD (same units as base parameters, which are used as Gaussian mean)

  • phase_sd (scalar, Default: 0 (no inter-trial variation)) – Inter-trial variation in frequency/amplitude/phase, given as Gaussian SD (same units as base parameters, which are used as Gaussian mean)

  • smp_rate (int, default: 1000) – Sampling rate for simulated data (Hz)

  • time_range (scalar, default: 1 s) – Full time range to simulate oscillation over (s)

  • burst_rate (scalar, default: 0 (not bursty)) – Oscillatory burst rate (bursts/trial). Set=0 to simulate constant, non-bursty oscillation.

  • burst_width (scalar, default: 4) – Half-width of oscillatory bursts (Gaussian SD, in cycles)

  • seed (int, default: None) – Random generator seed for repeatable results. Set=None for unseeded random numbers.

Returns:

data – Simulated oscillation-in-noise data

Return type:

ndarray, shape=(n_timepts,n_trials)