pybispectra.tde.TDE

class pybispectra.tde.TDE(data: ndarray, freqs: ndarray, sampling_freq: int | float, verbose: bool = True)

Class for computing time delay estimation (TDE) using the bispectrum.

Parameters:

datandarray, 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 in pybispectra.utils.compute_fft()).

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.

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.

Attributes:

resultstuple of ResultsTDE

Return the results.

datandarray, shape of [epochs, channels, frequencies]

Fourier coefficients, with negative frequencies appended.

freqsndarray, shape of [frequencies]

Frequencies (in Hz) in data, with negative frequencies appended.

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

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

Compute TDE, 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 TDE between. If None, coupling between all channels is computed.

fminint | float | tuple of int or float (default 0.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).

fmaxint | float | tuple of int or float (default numpy.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).

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.

methodint | tuple of int (default 1)

The method to use to compute TDE [1]. Can include [1, 2, 3, 4].

n_jobsint (default 1)

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

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

[1] (1,2)

Chrysostomos L. Nikias and Renlong Pan. Time delay estimation in unknown Gaussian spatially correlated noise. IEEE Transactions on Acoustics, Speech, and Signal Processing, 36(11):1706–1714, 1988. doi:10.1109/29.9008.

[2]

Tin Jurhar and others. Estimating signal time-delays under mixed noise influence with novel cross- and bispectrum methods. In Preparation, In Preparation.

copy()

Return a copy of the object.

property results: ResultsTDE | tuple[ResultsTDE]

Return the results.

Returns:

resultsResultsTDE | tuple of ResultsTDE

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