pybispectra.cfc.PAC

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

Class for computing phase-amplitude coupling (PAC) 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:

resultsResultsCFC | tuple of ResultsCFC

PAC results for each of the computed metrics.

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, antisym, ...])	Compute PAC, averaged over epochs.
copy()	Return a copy of the object.

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, antisym: bool | tuple[bool] = False, norm: bool | tuple[bool] = False, n_jobs: int = 1) → None

Compute PAC, averaged over epochs.

Parameters:

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

Indices of the seed and target channels, respectively, to compute PAC between. If None, coupling between all channels is computed.

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

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

Added in version 1.3.

antisymbool | tuple of bool (default False)

Whether to antisymmetrise the PAC results. If a tuple of bool, both forms of PAC are computed in turn.

normbool | tuple of bool (default False)

Whether to normalise the PAC results using the threenorm. If a tuple of bool, both forms of PAC are computed in turn.

n_jobsint (default 1)

The number of jobs to run in parallel. If -1, all available CPUs are used.

Notes

PAC can be computed as the bispectrum, \(\textbf{B}\), of signals \(\textbf{x}\) and \(\textbf{y}\) of the seeds and targets, respectively, which 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 computation of PAC follows from this [1]

\(\textbf{B}_{xyy}(f_1,f_2)=<\textbf{x}(f_1)\textbf{y}(f_2) \textbf{y}^*(f_2+f_1)>\) ,

\(\textrm{PAC}(\textbf{x}_{f_1},\textbf{y}_{f_2})=|\textbf{B}_{xyy} (f_1,f_2)|\) .

The bispectrum can be normalised to the bicoherence, \(\boldsymbol{\mathcal{B}}\), using the threenorm, \(\textbf{N}\), [2]

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

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

\(\textrm{PAC}_{\textrm{norm}}(\textbf{x}_{f_1},\textbf{y}_{f_2})= |\boldsymbol{\mathcal{B}}_{xyy}(f_1,f_2)|\) .

where the resulting values lie in the range \([0, 1]\). Furthermore, PAC can be antisymmetrised by subtracting the results from those found using the transposed bispectrum, \(\textbf{B}_{yxy}\), [3]

\(\textrm{PAC}_{\textrm{antisym}}(\textbf{x}_{f_1},\textbf{y}_{f_2})= |\textbf{B}_{xyy}(f_1,f_2)-\textbf{B}_{yxy}(f_1,f_2)|\) .

A modified approach is used for the normalisation of antisymmetrised PAC [4]

\(\textrm{PAC}_{\textrm{norm,antisym}}(\textbf{x}_{f_1},\textbf{y}_{f_2})= \Large|\frac{\textbf{B}_{xyy}(f_1,f_2)-\textbf{B}_{yxy}(f_1,f_2)} {\textbf{N}_{xyy}(f_1,f_2)+\textbf{N}_{yxy}(f_1,f_2)}|\) .

If the seed and target for a given connection is the same channel and antisymmetrisation is being performed, numpy.nan values are returned.

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

References

[1]

Christopher K. Kovach, Hiroyuki Oya, and Hiroto Kawasaki. The bispectrum and its relationship to phase-amplitude coupling. NeuroImage, 173:518–539, 2018. doi:10.1016/j.neuroimage.2018.02.033.

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

[3]

Federico Chella, Laura Marzetti, Vittorio Pizzella, Filippo Zappasodi, and Guido Nolte. Third order spectral analysis robust to mixing artifacts for mapping cross-frequency interactions in EEG/MEG. NeuroImage, 91:146–161, 2014. doi:10.1016/j.neuroimage.2013.12.064.

[4]

Federico Chella, Vittorio Pizzella, Filippo Zappasodi, Guido Nolte, and Laura Marzetti. Bispectral pairwise interacting source analysis for identifying systems of cross-frequency interacting brain sources from electroencephalographic or magnetoencephalographic signals. Physical Review E, 93(5):052420, 2016. doi:10.1103/PhysRevE.93.052420.

copy()

Return a copy of the object.