patrk / pypte

Pythonic implementation of the Phase Transfer Entropy method using NumPy and SciPy

pyPTE: Phase Transfer Entropy in Python

pyPTE is an open-source Python implementation of the Phase Transfer Entropy method, designed to analyze directed connectivity in networks influenced by oscillatory interactions. This tool is inspired by the following foundational works:

• Lobier et al., 2014: Phase transfer entropy: A novel phase-based measure for directed connectivity in networks coupled by oscillatory interactions.
• Hillebrand et al., 2016: Direction of information flow in large-scale resting-state networks is frequency-dependent.

Introduction

Phase Transfer Entropy (PTE) is a measure for directed connectivity in networks coupled by oscillatory interactions. The pyPTE library provides a Python implementation of this method, allowing researchers and developers to apply PTE analysis to their data.

Mathematical Background

The mathematical formulation of PTE can be described as follows:

Given two time series $X$ and $Y$, the PTE is defined as:

$$PTE_{X \to Y} = H(Y_{t+1} | Y_t) - H(Y_{t+1} | Y_t, X_t)$$

The PTE value quantifies the amount of uncertainty reduced in predicting the future phase of $Y$ when considering the current phase of $X$.

Contributing

Contributions to pyPTE are welcome! If you have suggestions, bug reports, or want to contribute code via Pull Requests

License

pyPTE is released under the GPL-3.0 license. For more details, see the LICENSE file.

pypte's Issues

Delay Estimation Methods to Support Per-Channel Analysis and Explore More Robust Metrics

Current situation

Delay estimation is a heuristic method suggested by Hillebrand, which computes an overall delay estimate across all channels in a measurement. This method calculates a single scalar value representing the delay based on the phase of the signals.

Goals

• Enhance the granularity and accuracy of delay estimation
• Ensure the PTE calculation is more reflective of the complex dynamics
• Investigate and potentially implement more robust and versatile delay estimation metrics
• Method is more or less deterministic and has profound mathematical foundations that ensure reliability and accuracy in its estimations (nice to have)

To improve delay estimation should explore additional metrics beyond the current heuristic.

Suggested metrics or concepts include:

• Cross-Correlation: Utilize cross-correlation to identify the time lag at which two signals are most similar
• Phase-Locking Value (PLV): Investigate the use of PLV for estimating delays by measuring the phase synchronization between signals.
• Mutual Information: Evaluate mutual information as a metric for delay estimation
• Dynamic Time Warping
• Wavelet Coherence
• Or even dive deeper into Hilbert Phase Analysis on which Hillebrand estimation is vaguely based

AC:

• method must be capable of calculating delay estimations on a per-channel-pair basis, resulting in a delay matrix that represents the time delays between each pair of channels in the dataset
• PTE calculation mechanism must be adapted to accept and effectively process a delay matrix as its input and use the correct delay estimate between channel pairs for the window sizing and shifting
• tests that underline the sanity and robustness of the overall algorithm with the integration of the new delay estimation method(s)

Divide by zero in entropy calculations

Hi, thanks for implementing this.

I often get:
yPTE.py:153: RuntimeWarning: divide by zero encountered in log2

Would it be sensible here to add an infinitesimal for numerical stability?

IndexError

It seems that the program might throw out "IndexError" when calling np.add.at in pyPTE.PTE.
Just like:

line 143, in compute_PTE
np.add.at(P_y_x, [y, x], 1)
IndexError: index 4 is out of bounds for axis 0 with size 4

I printed the matrix, and found out this would happen when y and x didn't share the same maximum value that P_y_x was not square.

My numpy version is 1.26.0.

Is get_delay correct?

I assume the basis for get_delay is Hillebrand, 2016, if not I apologise.

pyPTE/pyPTE/pyPTE.py

Line 22 in 2e165d9

r_phase = np.roll(phase, 2, axis=0)

Shouldn't the 2nd parameter be 1, rather than 2? With 2, it overcounts zero-crossings by nearly double.

Also, what is the motivation for m-2 in

pyPTE/pyPTE/pyPTE.py

Line 21 in 2e165d9

c1 = n*(m-2)

In the paper, it is simply n*m, right?

Bug: Axes are switched

Currently, the docstrings and the logic of compute_PTE expect the data to be of shape (n_channels, n_samples). However, the rest of the code assumes that the data is (n_samples, n_channels). This usually results in an error.

Make use of numpy iterators in PTE calculation

self-explanatory

Correctness of TE calculation

Im trying to use your PTE calculation. At the entrance I have 19 channel array with 1000 elements each. Im expecting to return 2 arrays 19x19 each with normalized/non normalized TE between each channel. But instead of this I have 2 arrays 1000x1000 elements each. Could you help me, what I`m doing wrong?
Attaching link to git https://github.com/Ku4eruk/tests_with_eeg/blob/main/test.py
Thanks

the definition of bin width

def get_binsize(phase, c = 3.49):
"""
Computes the bin size for the phase binning

Parameters
----------
c : float
phase : numpy.ndarray
    m x n ndarray : m: number of channels, n: number of samples

Returns
-------
bincount : float

"""

m, n = phase.shape
binsize = c * np.mean(np.std(phase, axis=0, ddof=1)) * m ** (-1.0 / 3)
return binsize

Hi，I want to confirm with you the definition of the bin width in your code. In paper “Phase transfer entropy: A novel phase-based measure for directed connectivity in networks coupled by oscillatory interactions”, the bin width is defined as h_j=3.5ϑ_j/N^(1/3) (Chapter: Method, Section: phase transfer entropy), and the N is defined as the number of samples. but in your code N is the number of channel. Could you please check this definition again and tell the reason?

Dimensions switched in documentation of code

Thanks for the great code!

I just wanted to point out that the documentation incorrectly specifies the shape of input data to be (channels,samples), whereas all functions seem to expect the opposite; i.e. an array of shape (samples,channels).

Raise awareness on issues and drawbacks by examples

Refactor examples

Create notebook for all examples including explanations and visualize results

Semantic Release does not work in GH Actions

A new version can be generated locally, but the release job in gh action does nothing

semantic release is run with poetry and is configured in pyproject.toml

Raise awareness on delay calculation

Refactor code - object oriented

Introduce Abstract Base Class which enforces overriding delay calculation

Include default delay calculation in constructor

Publish code on PyPi

Invite collaborators to review changes
Publish on PyPi

Explore / implement more approaches to phase based TE

"Kernel-Based Phase Transfer Entropy with Enhanced Feature Relevance Analysis for Brain Computer Interfaces" - This paper introduces a method that combines kernel-based TE estimator and Renyi’s entropy. It’s designed for better feature relevance analysis in EEG signals. Could be a solid addition for more nuanced connectivity analysis.

"Measurement of information transfer based on phase increment transfer entropy (PITE)" - PITE offers a novel twist on assessing the information transfer by focusing on the phase increments, which could provide a more robust analysis in non-linear signal scenarios. This approach might shine new light on ADHD EEG signal analysis, offering a fresh perspective on information transfer.

"A modified phase transfer entropy for cross-frequency directed coupling estimation in brain network" - This paper suggests an improved PTE method that considers cross-frequency interactions, addressing multivariable effects and the curse of dimensionality. It’s something that could greatly benefit the analysis of complex cognitive processes.

Update Readme, Documentation, gh-pages

Enhancements: NMM Examples, PTE Significance Testing, and More Sanity Checks

• NMM Examples: include examples using Neural Mass Models to show how PTE can reproduce connectivity.

• Significance Testing for PTE: make PTE results more reliable, implement significance testing. this will help users know if the connectivity patterns they see are statistically meaningful.

• Expanded Sanity Testing: add more sanity tests to make sure new updates don't break anything. Use simple synthetic data with know expected results, kuramoto models, NMMs and / or open source brain connectivity data

Permutation testing?

Hello,

Do you have any methods for implementing permutation testing to determine significance?

I saw the matrix_wilcoxon() function, but this appears run a single significance test between two connectivity matrices after the PTE has already been calculated.

Perhaps I misunderstand how the PTE is calculated, and shuffling is not necessary?

Thanks!