pybispectra.general.Bispectrum

class pybispectra.general.Bispectrum(data: ndarray, freqs: ndarray, sampling_freq: int | float, times: ndarray | None = None, verbose: bool = True)

Class for computing the bispectrum.

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.

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:

resultsResultsGeneral

Bispectrum results.

datandarray of float, shape of [epochs, channels, frequencies (, times)]

Fourier coefficients.

freqsndarray of float, 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, n_jobs])	Compute the bispectrum, averaged over epochs.
copy()	Return a copy of the object.

Notes

Added in version 1.2.

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

Compute the bispectrum, averaged over epochs.

Parameters:

indicestuple of tuple of int, length of 3 | None (default None)

Indices of the channels \(k\), \(m\), and \(n\), respectively, to compute the bispectrum for. If None, the bispectrum for all channel combinations is computed.

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

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

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

The bispectrum, \(\textbf{B}\), 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.

The bispectrum is computed between 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.

copy()

Return a copy of the object.