pybispectra.waveshape.WaveShape#

class pybispectra.waveshape.WaveShape(data: ndarray, freqs: ndarray, sampling_freq: int | float, times: ndarray | None = None, verbose: bool = True)[source]#

Class for computing waveshape properties using the bispectrum.

Parameters:

datandarray, shape of [epochs, channels, frequencies (, times)]: Fourier coefficients.
freqsndarray, shape of [frequencies]: Frequencies (in Hz) in data. Frequencies are expected to be evenly spaced.
sampling_freqint | float: Sampling frequency (in Hz) of the data from which data was derived.
timesndarray, shape of [times] | None: Timepoints (in seconds) in data. If data has a times dimension and times = None, the time of the first sample in data is assumed to be 0 seconds.

Added in version 1.3.
verbosebool (default True): Whether or not to report the progress of the processing.

Attributes:

resultsResultsWaveShape | tuple of ResultsWaveShape: Waveshape results for each of the computed metrics.
datandarray, shape of [epochs, channels, frequencies (, times)]: Fourier coefficients.
freqsndarray, shape of [frequencies]: Frequencies (in Hz) in data.
sampling_freqint | float: Sampling frequency (in Hz) of the data from which data was derived.
timesndarray, shape of [times] | None: Timepoints (in seconds) in data.
verbosebool: Whether or not to report the progress of the processing.

Methods

`compute`([indices, f1s, f2s, times, norm, n_jobs])	Compute waveshape within channels, averaged over epochs.
`copy`()	Return a copy of the object.

Notes

It is recommended that spatio-spectral filtering for a given frequency band of interest has been performed before analysing waveshape properties [1]. This can enhance the signal-to-noise ratio of your data as well as mitigate the risks of source-mixing in the sensor space compromising the bicoherence patterns of the data [1]. Filtering can be performed with pybispectra.utils.SpatioSpectralFilter.

References

Compute waveshape within channels, averaged over epochs.

Parameters:

indicestuple of int | None (default None): Indices of the channels to compute waveshape within. If None, waveshape within all channels is computed.
f1stuple of int or float, length of 2 | None (default None): Start and end lower frequencies to compute waveshape for, respectively. If None, all frequencies are used.
f2stuple of int or float, length of 2 | None (default None): Start and end higher frequencies to compute waveshape for, respectively. If None, all frequencies are used.
timestuple of int or float, length of 2 | None (default None): Start and end times (in seconds) to compute waveshape for, respectively. If None, all timepoints are used.

Added in version 1.3.
normbool | tuple of bool (default True): Whether to normalise the waveshape results using the threenorm. If a tuple of bool, both forms of waveshape are computed in turn.

Added in version 1.3.
n_jobsint (default 1): The number of jobs to run in parallel. If -1, all available CPUs are used.

Notes

Non-sinudoisal waveshape features can be extracted using bispectrum-based methods. The bispectrum has the general form

\(\textbf{B}_{kmn}(f_1,f_2)=<\textbf{k}(f_1)\textbf{m}(f_2) \textbf{n}^*(f_2+f_1)>\) ,

where \(kmn\) is a combination of signals with Fourier coefficients \(\textbf{k}\), \(\textbf{m}\), and \(\textbf{n}\), respectively; \(f_1\) and \(f_2\) correspond to a lower and higher frequency, respectively; and \(<>\) represents the average value over epochs. When analysing waveshape, we are interested in only a single signal, and as such \(k=m=n\).

Furthermore, we can normalise the bispectrum to the bicoherence, \(\boldsymbol{\mathcal{B}}\), using the threenorm, \(\textbf{N}\), [2]

\(\textbf{N}_{xxx}(f_1,f_2)=(<|\textbf{x}(f_1)|^3><|\textbf{x} (f_2)|^3> <|\textbf{x}(f_2+f_1)|^3>)^{\frac{1}{3}}\) ,

\(\boldsymbol{\mathcal{B}}_{xxx}(f_1,f_2)=\Large\frac{\textbf{B}_{xxx} (f_1,f_2)}{\textbf{N}_{xxx}(f_1,f_2)}\) ,

where the resulting values lie in the range \([-1, 1]\).

Waveshape is computed for all values of f1s and f2s.

Warning

For values of f1s higher than f2s or where f2s + f1s exceeds the Nyquist frequency, a numpy.nan value is returned.

References

copy()[source]#: Return a copy of the object.