pybispectra.waveshape.WaveShape#

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

Class for computing waveshape properties using bicoherence.

Parameters:
datandarray, shape of [epochs, channels, frequencies]

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.

verbosebool (default True)

Whether or not to report the progress of the processing.

Attributes:
resultsResultsWaveShape

Waveshape results.

datandarray, shape of [epochs, channels, frequencies]

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.

verbosebool

Whether or not to report the progress of the processing.

Methods

compute([indices, f1s, f2s, n_jobs])

Compute bicoherence 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(indices: tuple[int] | None = None, f1s: tuple[int | float] | None = None, f2s: tuple[int | float] | None = None, n_jobs: int = 1) None[source]#

Compute bicoherence within channels, averaged over epochs.

Parameters:
indicestuple of int | None (default None)

Indices of the channels to compute bicoherence within. If None, bicoherence within all channels is computed.

f1stuple of int or float, length of 2 | None (default None)

Start and end lower frequencies to compute bicoherence 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 bicoherence for, respectively. If None, all frequencies are used.

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]\).

Bicoherence is computed for all values of f1s and f2s. If any value of f1s is higher than f2s, a numpy.nan value is returned.

References

copy()[source]#

Return a copy of the object.