pybispectra.cfc.PAC#

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

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

verbosebool (default True)

Whether or not to report the progress of the processing.

Attributes:
resultstuple of ResultsCFC

Return the results.

datandarray of float, shape of [epochs, channels, frequencies]

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.

verbosebool

Whether or not to report the progress of the processing.

Methods

compute([indices, f1s, f2s, antisym, norm, ...])

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

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.

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}_{xyx}\), [3]

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

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. If any value of f1s is higher than f2s, a numpy.nan value is returned.

References

copy()[source]#

Return a copy of the object.

property results: ResultsCFC | tuple[ResultsCFC]#

Return the results.

Returns:
resultsResultsCFC | tuple of ResultsCFC

The results of the PAC computation returned as a single results object (if only one PAC variant was computed) or a tuple of results objects.