pybispectra.waveshape.WaveShape

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

Class for computing waveshape properties using bicoherence.

Parameters:

datanumpy.ndarray, shape of [epochs, channels, frequencies]

Fourier coefficients.

freqsnumpy.ndarray, 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.

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 SpatioSpectralFilter.

References

[1] (1,2)

Sarah Bartz, Forooz Shahbazi Avarvand, Gregor Leicht, and Guido Nolte. Analyzing the waveshape of brain oscillations with bicoherence. NeuroImage, 188:145–160, 2019. doi:10.1016/j.neuroimage.2018.11.045.

Attributes:

resultstuple of ResultsWaveShape

Return the 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.

compute(indices: tuple[int] | None = None, f1s: tuple[int | float] | None = None, f2s: tuple[int | float] | None = None, n_jobs: int = 1) → None

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

[2]

Forooz Shahbazi, Arne Ewald, and Guido Nolte. Univariate normalization of bispectrum using Hölder’s inequality. Journal of Neuroscience Methods, 233:177–186, 2014. doi:10.1016/j.jneumeth.2014.05.030.

copy()

Return a copy of the object.

property results: ResultsWaveShape

Return the results.

Returns:

resultsResultsWaveShape

The results of the waveshape computation.