Wavelet spectral analysis (spynal.spectra.wavelet)

Continuous-wavelet-based spectral analysis

wavelet_spectrum(data, smp_rate, axis=0, data_type='lfp', spec_type='complex', freqs=None, removeDC=True, wavelet='morlet', wavenumber=6, pad=False, buffer=0, **kwargs)

Compute continuous wavelet transform of data, then averages across timepoints to reduce it down to a frequency spectrum.

Not really the best way to compute 1D frequency spectra, but included for completeness

Only parameters differing from spectrum() are described here.

Parameters:

  • freqs (array-like, shape=(n_freqs,), default: 2**np.arange(1,7.5,0.25)) – Set of desired wavelet frequencies. Default value logarithmically samples from 2-152 in 1/4 octaves, but log sampling is not required.

  • wavelet ({'morlet'}, default: 'morlet') – Name of wavelet type. Currently only ‘morlet’ is supported.

  • wavenumber (int, default: 6) – Wavelet wave number parameter ~ number of oscillations in each wavelet. Must be >= 6 to meet “admissibility constraint”.

  • buffer (float, default: 0 (no buffer)) – Time (s) to trim off each end of time dimension of data. Removes symmetric buffer previously added (outside of here) to prevent edge effects.

Returns:

  • spec (ndarray, shape=(…,n_freqs,…), dtype=complex or float.) – Wavelet-derived spectrum of data. Same shape as data, with frequency axis replacing time axis dtype is complex if spec_type is ‘complex’, float otherwise.

  • freqs, ndarray, shape=(n_freqs,) – List of frequencies in spec (in Hz)

wavelet_spectrogram(data, smp_rate, axis=0, data_type='lfp', spec_type='complex', freqs=None, removeDC=True, wavelet='morlet', wavenumber=6, pad=False, buffer=0, downsmp=1, **kwargs)

Compute continuous time-frequency wavelet transform of data at given frequencies.

Only parameters differing from spectrogram() are described here.

Parameters:

  • freqs (array-like, shape=(n_freqs,), default: 2**np.arange(1,7.5,0.25)) – Set of desired wavelet frequencies. Default value logarithmically samples from 2-152 in 1/4 octaves, but log sampling is not required.

  • wavelet ({'morlet'}, default: 'morlet') – Name of wavelet type. Currently only ‘morlet’ is supported.

  • wavenumber (int, default: 6) – Wavelet wave number parameter ~ number of oscillations in each wavelet. Must be >= 6 to meet “admissibility constraint”.

  • buffer (float, default: 0 (no buffer)) – Time (s) to trim off each end of time dimension of data. Removes symmetric buffer previously added (outside of here) to prevent edge effects.

  • downsmp (int, default: 1 (no downsampling)) – Factor to downsample time sampling by (after spectral analysis). eg, smp_rate=1000 (dt=0.001), downsmp=10 -> smpRateOut=100 (dt=0.01)

Returns:

  • spec (ndarray, shape=(…,n_freqs,n_timepts_out,…), dtype=complex or float.) – Wavelet time-frequency spectrogram of data, transformed to requested spectral type. Same shape as data, with frequency axis prepended before time, and time axis possibly reduces via downsampling. dtype is complex if spec_type is ‘complex’, float otherwise.

  • freqs (ndarray, shape=(n_freqs,) ndarray) – List of frequencies in spec (in Hz)

  • timepts (ndarray, shape=(n_timepts_out,)) – List of timepoints in spec (in s, referenced to start of data).

References

Torrence & Compo 1998 https://doi.org/10.1175/1520-0477(1998)079%3C0061:APGTWA%3E2.0.CO;2

compute_wavelets(n, smp_rate, freqs=None, wavelet='morlet', wavenumber=6, do_fft=False)

Compute set of (Fourier transformed) wavelets for use in wavelet spectral analysis

Parameters:

  • n (int) – Total number of samples (time points) in analysis, including any padding.

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

  • freqs (array-like, shape=(n_freqs,), default: 2**np.arange(1,7.5,0.25)) – Set of desired wavelet frequencies. Default value logarithmically samples from 2-152 in 1/4 octaves, but log sampling is not required.

  • wavelet ({'morlet'}, default: 'morlet') – Name of wavelet type. Currently only ‘morlet’ is supported.

  • wavenumber (int, default: 6) – Wavelet wave number parameter ~ number of oscillations in each wavelet. Must be >= 6 to meet “admissibility constraint”.

  • do_fft (bool, default: False) – If True, returns Fourier transform of wavelet functions. If False, returns original time-domain functions.

Returns:

wavelets – Computed set of wavelet functions at multiple frequencies/scales. (either the time domain wavelets or theirFourier transform, depending on do_fft)

Return type:

ndarray, shape=(n_freqs,n_timepts)

References

Torrence & Compo 1998 https://doi.org/10.1175/1520-0477(1998)079%3C0061:APGTWA%3E2.0.CO;2

wavelet_bandwidth(freqs, wavelet='morlet', wavenumber=6, full=True)

Return frequency and time bandwidths for set of wavelets at given frequencies

Parameters:

  • freqs (array-like, shape=(n_freqs,)) – Set of wavelet center frequencies.

  • wavelet ({'morlet'}, default: 'morlet') – Name of wavelet type. Currently only ‘morlet’ is supported.

  • wavenumber (int, default: 6) – Wavelet wave number parameter ~ number of oscillations in each wavelet.

  • full (bool, default: True) – If True, return full-bandwidths. If False, return half-bandwidths.

Returns:

  • freq_widths (ndarray, shape=(n_freqs,)) – Frequency bandwidth (Hz) for each given frequency

  • time_widths (ndarray, shape=(n_freqs,)) – Time bandwidth (s) for each given frequency

wavelet_edge_extent(freqs, wavelet='morlet', wavenumber=6)

Return temporal extent of edge effects for set of wavelets at given frequencies

Compute time period over which edge effects might effect output of wavelet transform, and over which the effects of a single spike-like artifact in data will extend.

Computed as time for wavelet power to drop by a factor of exp(−2), ensuring that edge effects are “negligible” beyond this point.

Parameters:

  • freqs (array-like, shape=(n_freqs,)) – Set of wavelet center frequencies

  • wavelet ({'morlet'}, default: 'morlet') – Name of wavelet type. Currently only ‘morlet’ is supported.

  • wavenumber (int, default: 6) – Wavelet wave number parameter ~ number of oscillations in each wavelet.

Returns:

edge_extent – Time period (s) over which edge effects extend for each given frequency

Return type:

ndarray, shape=(n_freqs,)

References

Torrence & Compo https://doi.org/10.1175/1520-0477(1998)079%3C0061:APGTWA%3E2.0.CO;2 Sxn.3g