pybispectra.tde.TDE#
- class pybispectra.tde.TDE(data: ndarray, freqs: ndarray, sampling_freq: int | float, verbose: bool = True)[source]#
Class for computing time delay estimation (TDE) using the bispectrum.
- Parameters:
- data
ndarray
, shape of [epochs, channels, frequencies] Fourier coefficients. Must contain a coefficient for the zero frequency. Coefficients should be computed with the number of points equal to twice the number of timepoints in each epoch of the original data plus one (i.e.
n_points=2 * n_times + 1
inpybispectra.utils.compute_fft()
).- 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
ResultsTDE
|tuple
ofResultsTDE
TDE results for each of the computed metrics.
- data
ndarray
, shape of [epochs, channels, frequencies] Fourier coefficients, with negative frequencies appended.
- freqs
ndarray
, shape of [frequencies] Frequencies (in Hz) in
data
, with negative frequencies appended.- 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, fmin, fmax, antisym, ...])Compute TDE, averaged over epochs.
copy
()Return a copy of the object.
Notes
TDE with the bispectrum requires the Fourier coefficients of the negative frequencies of the original signals, however since these are expected to be real-valued, they can be inferred from the positive frequencies. Accordingly, only the coefficients corresponding to the zero and positive frequencies should be passed to
data
.It is recommended to compute the Fourier coefficients with
n_points=2 * n_times + 1
. Using a smaller number of points than this will reduce the time range in which a delay estimate can be generated below that of the length of the epochs. Furthermore, a larger number of points than this will only artificially increase the time range in which a delay estimate can be generated beyond the length of the epochs.- compute(indices: tuple[tuple[int]] | None = None, fmin: int | float | tuple[int | float] = 0.0, fmax: int | float | tuple[int | float] = inf, antisym: bool | tuple[bool] = False, method: int | tuple[int] = 1, n_jobs: int = 1) None [source]#
Compute TDE, averaged over epochs.
- Parameters:
- indices
tuple
oftuple
ofint
, length of 2 |None
(defaultNone
) Indices of the seed and target channels, respectively, to compute TDE between. If
None
, coupling between all channels is computed.- fmin
int
|float
|tuple
ofint
orfloat
(default0.0
) The low frequency of interest (in Hz) to compute time delays for. If a tuple of float, specifies the low frequencies for each frequency band of interest (must have the same length as fmax).
- fmax
int
|float
|tuple
ofint
orfloat
(defaultnumpy.inf
) The high frequency of interest (in Hz) to compute time delays for. If a tuple of float, specifies the high frequencies for each frequency band of interest (must have the same length as fmin).
- antisym
bool
|tuple
ofbool
(defaultFalse
) Whether to antisymmetrise the PAC results. If a tuple of bool, both forms of PAC are computed in turn.
- method
int
|tuple
ofint
(default1
) The method to use to compute TDE [1]. Can include
[1, 2, 3, 4]
.- n_jobs
int
(default1
) The number of jobs to run in parallel. If
-1
, all available CPUs are used.
- indices
Notes
TDE can be computed from 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. When computing TDE, information from \(\textbf{n}\) is taken not only from the positive frequencies, but also the negative frequencies.
Four methods exist for computing TDE based on the bispectrum [1]. The fundamental equation is as follows
\(\textrm{TDE}_{xy}(\tau)=\int_{-\pi}^{+\pi}\int_{-\pi}^{+\pi}\textbf{I} (\textbf{x}_{f_1},\textbf{y}_{f_2})e^{-if_1\tau}df_1df_2\) ,
where \(\textbf{I}\) varies depending on the method; and \(\tau\) is a given time delay. Phase information of the signals is extracted from the bispectrum in two variants used by the different methods:
\(\boldsymbol{\phi}(\textbf{x}_{f_1},\textbf{y}_{f_2})=\boldsymbol{\varphi} _{\textbf{B}_{xyx}} (f_1,f_2)-\boldsymbol{\varphi}_{\textbf{B}_{xxx}} (f_1,f_2)\) ;
\(\boldsymbol{\phi}'(\textbf{x}_{f_1},\textbf{y}_{f_2})= \boldsymbol{\varphi}_{\textbf{B}_{xyx}}(f_1,f_2)-\frac{1}{2}( \boldsymbol{\varphi}_{\textbf{B}_{xxx}}(f_1,f_2) + \boldsymbol{\varphi}_{ \textbf{B}_{yyy}}(f_1,f_2))\) .
Method I: \(\textbf{I}(\textbf{x}_{f_1},\textbf{y}_{f_2})=e^{i\boldsymbol{\phi} (\textbf{x}_{f_1},\textbf{y}_{f_2})}\)
Method II: \(\textbf{I}(\textbf{x}_{f_1},\textbf{y}_{f_2})=e^{i\boldsymbol{\phi}' (\textbf{x}_{f_1},\textbf{y}_{f_2})}\)
Method III: \(\textbf{I}(\textbf{x}_{f_1},\textbf{y}_{f_2})=\Large \frac{\textbf{B}_ {xyx}(f_1,f_2)}{\textbf{B}_{xxx}(f_1,f_2)}\)
Method IV: \(\textbf{I}(\textbf{x}_{f_1},\textbf{y}_{f_2})=\Large \frac{|\textbf{B}_ {xyx}(f_1,f_2)|e^{i\boldsymbol{\phi}'(\textbf{x}_{f_1},\textbf{y}_{f_2})}}{ \sqrt{|\textbf{B}_{xxx}(f_1,f_2)||\textbf{B}_{yyy}(f_1,f_2)|}}\)
where \(\boldsymbol{\varphi}_{\textbf{B}}\) is the phase of the bispectrum. All four methods aim to capture the phase difference between \(\textbf{x}\) and \(\textbf{y}\). Method I involves the extraction of phase spectrum periodicity and monotony, with method III involving an additional amplitude weighting from the bispectrum of \(\textbf{x}\). Method II instead relies on a combination of phase spectra of the different frequency components, with method IV containing an additional amplitude weighting from the bispectrum of \(\textbf{x}\) and \(\textbf{y}\). No single method is superior to another.
Antisymmetrisation of the bispectrum is implemented as the replacement of \(\textbf{B}_{xyx}\) with \((\textbf{B}_{xyx} - \textbf{B}_{yxx})\) in the above equations [2].
If the seed and target for a given connection is the same channel, an error is raised.
References
- property results: ResultsTDE | tuple[ResultsTDE]#
TDE results for each of the computed metrics.
Returns a single results object if only one TDE variant was computed.