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:
- data
ndarray
, shape of [epochs, channels, frequencies] Fourier coefficients.
- freqs
ndarray
, shape of [frequencies] Frequencies (in Hz) in
data
. Frequencies are expected to be evenly spaced.- sampling_freq
int
|float
Sampling frequency (in Hz) of the data from which
data
was derived.- verbose
bool
(defaultTrue
) Whether or not to report the progress of the processing.
- data
- Attributes:
- results
ResultsWaveShape
Waveshape results.
- data
ndarray
, shape of [epochs, channels, frequencies] Fourier coefficients.
- freqs
ndarray
, shape of [frequencies] Frequencies (in Hz) in
data
.- sampling_freq
int
|float
Sampling frequency (in Hz) of the data from which
data
was derived.- verbose
bool
Whether or not to report the progress of the processing.
- results
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:
- indices
tuple
ofint
|None
(defaultNone
) Indices of the channels to compute bicoherence within. If
None
, bicoherence within all channels is computed.- f1s
tuple
ofint
orfloat
, length of 2 |None
(defaultNone
) Start and end lower frequencies to compute bicoherence for, respectively. If
None
, all frequencies are used.- f2s
tuple
ofint
orfloat
, length of 2 |None
(defaultNone
) Start and end higher frequencies to compute bicoherence for, respectively. If
None
, all frequencies are used.- n_jobs
int
(default1
) The number of jobs to run in parallel. If
-1
, all available CPUs are used.
- indices
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
andf2s
. If any value off1s
is higher thanf2s
, anumpy.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.