pyPTE estimates directed connectivity between oscillatory signals: given
two channels of EEG, MEG or any rhythmic time series, it answers which one is
leading the other.
It is worth being precise about the claim, because it is narrower than it first appears:
pyPTE recovers the direction of information flow between a pair of signals. It does not recover the wiring diagram of a network.
Direction is reliable once the data are band-passed to the rhythm and checked
with time reversal, and the coupling lag is more than a small fraction of a
cycle; #85 maps where it breaks.
Which connections are direct is not recoverable from a bivariate measure, and what can fool it
shows exactly how that fails, with numbers. Every claim below is produced by a
script in examples/ that asserts its own result, so if something
here stops being true, the test suite says so.
Based on:
- 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
pip install pyPTE # or: uv add pyPTEThe core needs only NumPy and SciPy. Adapters are optional:
pip install "pyPTE[mne]" # MNE-Python adapter (also installs pandas)
pip install "pyPTE[pandas]" # pandas adapterRequires Python 3.11 or newer. Dependencies are deliberately unpinned at the top
end so pyPTE resolves alongside whatever NumPy and SciPy the rest of your
environment needs.
PTE takes an (n_channels, n_samples) array and returns two matrices, where
entry [i, j] describes flow from channel i to channel j.
import numpy as np
from scipy.signal import butter, sosfiltfilt
from pyPTE import PTE
rng = np.random.default_rng(0)
fs, n, lag = 250, 30_000, 12 # two minutes; the target trails by 12 samples
# one 10 Hz rhythm with a drifting phase, seen by both channels with equal noise
drift = np.cumsum(rng.normal(0, 0.025, n + lag))
rhythm = np.sin(2 * np.pi * 10 * np.arange(n + lag) / fs + drift)
driver = rhythm[lag:] + rng.standard_normal(n)
target = rhythm[:n] + rng.standard_normal(n)
# band-pass to the rhythm, and cancel what noise alone would make look directed
alpha = butter(4, [8, 12], btype="band", fs=fs, output="sos")
signal = sosfiltfilt(alpha, np.vstack([driver, target]))
dPTE, raw_PTE = PTE(signal, time_reversal=True)
print(dPTE[0, 1]) # ~0.63 -> driver leads target
print(dPTE[1, 0]) # ~0.37 -> the reverseraw_PTE is transfer entropy in bits. dPTE is the direction-normalised form,
where dPTE[i, j] + dPTE[j, i] == 1: above 0.5 means net flow from i to
j, and exactly 0.5 means no preferred direction. Two independent rhythms
with the same noise give about 0.5. Without the band-pass, or with unequal
noise and no time_reversal, dPTE can point from the cleaner channel to the
noisier one whatever the coupling.
A raw dPTE value on its own is not a finding. See
running a real analysis.
- Tutorial: the measure built up from phase histograms, figure by figure
- Running a real analysis: surrogate tests, epoched group tests, multiple comparisons
- What can fool it: unequal noise, indirect paths, detuned oscillators
- Examples and API reference
Contributions are welcome — issues, suggestions and pull requests alike.
git clone https://github.com/patrk/pyPTE && cd pyPTE
uv sync --all-extras
uv run pytestBefore opening a PR: uv run ruff check ., uv run ruff format .,
uv run mypy pyPTE tests.
If pyPTE helps your research, please cite it. GitHub's "Cite this repository" button gives the details from CITATION.cff. Please also cite the papers that introduced the method:
- Lobier, Siebenhühner, Palva & Palva (2014). Phase transfer entropy: a novel phase-based measure for directed connectivity in networks coupled by oscillatory interactions. NeuroImage 85, 853–872. doi:10.1016/j.neuroimage.2013.08.056
- Hillebrand et al. (2016). Direction of information flow in large-scale resting-state networks is frequency-dependent. PNAS 113(14), 3867–3872. doi:10.1073/pnas.1515657113
pyPTE is released under GPL-3.0-or-later. See LICENSE.