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:
- 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
ResultsCFC
|tuple
ofResultsCFC
PAC results for each of the computed metrics.
- data
ndarray
offloat
, shape of [epochs, channels, frequencies] Fourier coefficients.
- freqs
ndarray
offloat
, 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.
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:
- indices
tuple
oftuple
ofint
, length of 2 |None
(defaultNone
) Indices of the seed and target channels, respectively, to compute PAC between. If
None
, coupling between all channels is computed.- f1s
tuple
ofint
orfloat
, length of 2 |None
(defaultNone
) Start and end lower frequencies to compute PAC on, respectively. If
None
, all frequencies are used.- f2s
tuple
ofint
orfloat
, length of 2 |None
(defaultNone
) Start and end higher frequencies to compute PAC on, respectively. If
None
, all frequencies are used.- antisym
bool
|tuple
ofbool
(defaultFalse
) Whether to antisymmetrise the PAC results. If a tuple of bool, both forms of PAC are computed in turn.
- norm
bool
|tuple
ofbool
(defaultFalse
) Whether to normalise the PAC results using the threenorm. If a tuple of bool, both forms of PAC are computed in turn.
- n_jobs
int
(default1
) The number of jobs to run in parallel. If
-1
, all available CPUs are used.
- indices
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
andf2s
. If any value off1s
is higher thanf2s
, anumpy.nan
value is returned.References
- property results: ResultsCFC | tuple[ResultsCFC]#
PAC results for each of the computed metrics.
Returns a single results object if only one PAC variant was computed.