API reference

Estimation

pyPTE.PTE(time_series, *, binning='scott', delay='zero-crossing', bias_correction=False, trim_cycles=0.0, time_reversal=False)

Computes dPTE and raw PTE for every ordered channel pair

The procedure is:

1. Compute the phase with a Hilbert transform, on the interval [-pi, pi[

2. Estimate the analysis delay, and optionally trim the edges

3. Shift the phase so there are no negative values, then bin it

4. Count joint states and combine the entropies

Band-pass the input narrowly to the rhythm of interest first. On broadband data dPTE points from the cleaner channel to the noisier one, whatever the coupling, and even after filtering a large enough difference in signal-to-noise ratio can reverse it. time_reversal=True cancels that artefact; see the analysis guide.

Both free choices in that procedure are exposed, because neither is obviously correct and they change the answer. Wider bins give a better-populated histogram and a larger apparent effect; the delay sets which lag the measure is sensitive to.

Parameters:

time_seriesnumpy.ndarray

m x n ndarray : m: number of channels, n: number of samples

binning{“scott”, “auto”, “hillebrand”} or int

“scott”, the default, sizes bins by Scott’s rule. The fine bins keep the phase resolution dPTE depends on, and the estimator’s bias cancels in the dPTE ratio. Raw PTE under it is biased upwards, by about 0.75 bits on unrelated signals, so do not read raw values on their own. “auto” sizes bins for the three-dimensional joint histogram (see get_bincount_auto), which keeps raw PTE close to unbiased but blurs phase and usually weakens dPTE. Use it when raw PTE in bits matters. “hillebrand” uses the bin count published in Hillebrand et al. 2016, which is finer still and, in simulation, more easily turned around by a difference in signal-to-noise ratio. An integer sets the number of bins directly.

delay{“zero-crossing”, “phase-increment”} or int

passed to pyPTE.core.pyPTE.get_delay; an integer is used as-is

bias_correctionbool

apply the Miller-Madow correction, which brings raw PTE on unrelated signals to about zero. Use it when the size of raw PTE in bits matters. It makes dPTE noisier, so leave it off when only direction matters.

trim_cyclesfloat

dominant cycles to drop from each end after the Hilbert transform, where its phase is least reliable. One cycle is twice the estimated delay. 0, the default, keeps every sample; 1 to 3 is typical for long recordings, but short epochs may not have samples to spare.

time_reversalbool

return the time-reversal-differenced dPTE instead of dPTE (see reversal_differenced_dPTE). It cancels directions that come from a difference in signal-to-noise ratio or from instantaneous mixing, which plain dPTE reports as real, at twice the cost. raw_PTE is still the forward raw PTE.

Returns:

(dPTE, raw_PTE)tuple of numpy.ndarray objects

dPTE : normalized PTE matrix, raw_PTE : PTE in bits. Entry [i, j] describes information flow from channel i to channel j.

pyPTE.PTE_segments(time_series, n_segments, *, binning='scott', delay='zero-crossing', bias_correction=False, trim_cycles=0.0, time_reversal=False)

Computes one dPTE and raw PTE matrix per segment of a continuous recording

The way to put a group test on one long recording: the matrices go to pyPTE.group_test, which asks whether a direction is consistent across segments. With time_reversal=True that is the robust test of direction, since directions produced by a difference in signal-to-noise ratio or by instantaneous mixing cancel in every segment. The surrogate test cannot do this for the differenced statistic, because its null assumes independent channels.

The phase is computed once over the whole recording, so the segments add no Hilbert edges, and every segment shares one delay and one bin count. A data-dependent bin rule is sized for one segment, not for the whole recording, which on short segments gives too few bins for a reliable direction; binning=20 is the safer choice. Segments of one recording share its slow drift, so they are not fully independent and the group test over them is somewhat optimistic.

Parameters:

time_seriesnumpy.ndarray

m x n array : m channels, n samples

n_segmentsint

number of contiguous, near-equal segments. With Wilcoxon’s test the smallest two-sided p-value over n segments is 2 / 2**n, so the count bounds what can survive correction; group_test warns when it is too small. Each segment should still span many cycles of the rhythm.

binning, delay, bias_correction, trim_cycles, time_reversal

as for PTE

Returns:

(dPTE, raw_PTE)tuple of numpy.ndarray objects

n_segments x m x m arrays, ready for pyPTE.group_test. raw_PTE is the forward raw PTE even with time_reversal.

pyPTE.core.pyPTE.reversal_differenced_dPTE(dPTE, reversed_dPTE)

Combines dPTE of a recording and of its time reverse into one direction

A real interaction reverses with time, so it pushes dPTE and the dPTE of the reversed recording to opposite sides of 0.5. A difference in signal-to-noise ratio, or one source mixed instantaneously into two channels, looks the same either way round, and pushes both to the same side. Taking half the difference keeps the first and cancels the second: the time-reversal-differenced statistic of Haufe et al. (2012) and Winkler et al. (2016), applied to dPTE.

The cancellation is shown in simulation, not proven: Winkler et al. prove it for linear models, and nonlinear coupling can survive time reversal (Kořenek & Hlinka 2021). A common driver that reaches two channels at different lags still reads as a direction, since that order is real.

Parameters:

dPTE, reversed_dPTEnumpy.ndarray

m x m dPTE of the recording and of its time reverse, computed with the same delay and bins

Returns:

differencednumpy.ndarray

m x m matrix on the dPTE scale, 0.5 + (dPTE - reversed_dPTE) / 2. Like dPTE it is antisymmetric about 0.5, so it works with group_test and the other group statistics. The diagonal is zero.

pyPTE.core.pyPTE.reverse_phase(d_phase)

The binned phase with time running backwards.

Reversing the binned phase, rather than binning the reversed signal, makes the reverse of a time-shifted surrogate exactly the surrogate of the reverse, which the differenced test relies on.

pyPTE.core.pyPTE.compute_segments(segments, delay, n_bins, *, bias_correction=False, time_reversal=False)

dPTE and raw PTE for each of several binned phase arrays

Parameters:

segmentssequence of numpy.ndarray

m x n_k binned phase arrays, as from prepare_phase, sharing delay and bins; lengths may differ

delay, n_bins

the shared delay and bin count

bias_correction, time_reversal

as for PTE

Returns:

(dPTE, raw_PTE)tuple of numpy.ndarray objects

len(segments) x m x m arrays

pyPTE.core.pyPTE.prepare_phase(time_series, *, binning='scott', delay='zero-crossing', trim_cycles=0.0, n_segments=1)

Turns raw signals into the binned phase that PTE counts

Steps 1 to 3 of PTE, exposed so that a caller can fix the delay and bins once and reuse them, as surrogate_test does for every surrogate.

Parameters:

time_seriesnumpy.ndarray

m x n ndarray : m: number of channels, n: number of samples

binning, delay, trim_cycles

as for PTE

n_segmentsint

number of segments the binned phase will be split into, each analysed on its own. The data-dependent bin rules then size the bins for one segment rather than for the whole recording; bins sized for the whole recording leave a short segment’s joint histograms nearly empty, which pulls its dPTE towards 0.5.

Returns:

(d_phase, delay, n_bins)tuple

m x n’ array of phase bins in 0 .. n_bins - 1, where n’ is n less any trimmed samples; the analysis delay in samples; the number of bins

pyPTE.core.pyPTE.compute_dPTE_rawPTE(phase, delay, n_bins=None, bias_correction=False)

This function calls pyPTE.pyPTE.compute_PTE to obtain a PTE matrix and performs a normalization yielding dPTE to easily investigate directionality information. Technically it could be a function which computes the normalization for a given PTE matrix, but it appears to be more convenient to obtain both matrices in one call

Parameters:

phasenumpy.ndarray

m x n ndarray : m: number of channels, n: number of samples The discretized phase is computed by pyPTE.pyPTE.get_discretized_phase

delayint

This is the analysis delta, which is the number of samples in the past to be considered for x and y. Momentarily delay is estimated by pyPTE.pyPTE.get_delay(). A custom delay estimation can be used as well.

n_binsint, optional

Number of bins over [0, 2*pi). Passed to compute_PTE.

bias_correctionbool

passed to compute_PTE. Corrected values can dip below zero, so dPTE is formed from them clipped at zero.

Returns:

(dPTE, raw_PTE)tuple of numpy.ndarray objects

dPTE : normalized PTE matrix, raw_PTE: original PTE values. dPTE is NaN for pairs with no transfer in either direction, where it is 0/0.

pyPTE.core.pyPTE.get_bincount_auto(n_samples, samples_per_cell=20.0)

Bin count sized for the three-dimensional histogram PTE actually fills

The entropy estimates are biased by roughly the number of occupied cells over twice the sample count, and the joint term spreads the samples over up to n_bins ** 3 cells. Choosing n_bins = (n_samples / samples_per_cell) ** (1/3) keeps the cube populated however long the recording is, where Scott’s rule, meant for a one-dimensional histogram, leaves about one sample per cell and a bias of around 0.75 bits on unrelated signals.

Parameters:

n_samplesint

samples_per_cellfloat

average samples per cell of the full joint histogram

Returns:

bincountint

at least 3

Significance

pyPTE.surrogate_test(time_series, *, n_surrogates=200, alpha=0.05, seed=None, progress=False, keep_null=False, binning='scott', delay='zero-crossing', trim_cycles=0.0, n_jobs=1, time_reversal=False)

Test every directed channel pair against a time-shifted surrogate null.

Significance is two-tailed in spirit but computed one-sided on the distance from 0.5, because dPTE is antisymmetric: evidence that i drives j is the same evidence that j does not drive i, and testing |dPTE - 0.5| keeps the two directions from being counted as independent findings.

The null rules out independent channels, not a wrong direction: a difference in signal-to-noise ratio between coupled channels, or one source mixed into both, gives a significant direction that may point either way. Band-pass narrowly first, and check direction with time_reversal=True or, with more power, with PTE_segments and group_test.

Parameters:

time_seriesnumpy.ndarray

m x n array : m channels, n samples

n_surrogatesint

size of the null distribution. 200 supports p-values down to ~0.005; raise it if you need finer resolution after correction.

alphafloat

target false discovery rate for the Benjamini-Hochberg step

seedint | None

seed for surrogate generation, for reproducible results

progressbool

print progress, since a large montage takes a while

keep_nullbool

retain every surrogate matrix on the result. Needed to plot where an observation sits within its null; costs n_surrogates * m * m floats.

binning, delay, trim_cycles

as for PTE. The delay and bins are estimated once, from the observed data, and every surrogate reuses them, so the null is computed with exactly the settings of the value it is compared against.

n_jobsint

worker processes for the surrogates; -1 uses every CPU. Results do not depend on it: the shifts are drawn up front from seed. Starting workers costs about a second, so it pays off on large montages.

time_reversalbool

also test the time-reversed recording (Haufe et al. 2012, Winkler et al. 2016). A real direction reverses with time; one produced by a difference in signal-to-noise ratio or by instantaneous mixing does not. reversal_confirmed marks pairs that are significant both ways round, with opposite signs, which is the conservative rule; the reversed recording is tested against the reverse of each surrogate. differenced_dPTE comes back too, as an effect size. It doubles the run time, and it cannot catch a common driver that reaches the two channels at different lags, since that order is genuinely in the data.

Returns:

resultSignificanceResult

pyPTE.surrogates_needed(n_channels, alpha=0.05)

Smallest surrogate count that could yield a single significant edge.

A surrogate test can never report a p-value below 1 / (n_surrogates + 1). Its p-values are symmetric, p[i, j] == p[j, i], so an isolated pair enters the correction twice and Benjamini-Hochberg accepts it at rank 2 once p falls below alpha / n_pairs, counting unordered pairs. Below the count returned here, no edge can survive no matter how strong the coupling.

This is a worst case. A genuinely widespread effect is accepted at a higher rank, where the threshold is looser, so fewer surrogates can still work when many pairs are truly coupled.

Parameters:

n_channelsint

alphafloat

Returns:

n_surrogatesint

pyPTE.group_test(matrices, *, reference=0.5, method='wilcoxon', alpha=0.05)

Test whether dPTE departs from chance consistently across observations.

The counterpart to surrogate_test for repeated observations: epochs, trials, segments or subjects. It asks whether an effect is consistent across them.

Consistency is also what an artefact produces. A difference in signal-to-noise ratio, or one source mixed into two channels, shifts dPTE the same way in every observation, so plain dPTE matrices test for those as readily as for coupling. Pass time-reversal-differenced matrices (time_reversal=True in PTE_segments or PTE_from_epochs), and compute them with at least 16 bins, preferably 20: with fewer, a real coupling’s direction depends on the delay and can come out significantly backwards. Short observations carry little directional information, so the estimate in each one is pulled towards 0.5 rather than merely noisy.

Parameters:

matricesnumpy.ndarray

n_observations x m x m array of dPTE matrices, one per epoch, trial or subject

referencefloat

the no-effect value to test against. 0.5 for dPTE; use 0.0 when passing raw PTE.

method{“wilcoxon”, “ttest”}

Wilcoxon signed-rank by default, which makes no normality assumption and is the usual choice in the M/EEG literature

alphafloat

target false discovery rate

Returns:

resultGroupResult

Notes

dPTE is antisymmetric, so [i, j] and [j, i] express the same finding. When the input is antisymmetric each pair is tested once and the result mirrored. Benjamini-Hochberg over the mirrored p-values, each present twice, reaches exactly the decisions it would over one per pair. Raw PTE is not antisymmetric, so there both orientations are tested.

pyPTE.group_contrast(condition_a, condition_b, *, method='wilcoxon', alpha=0.05)

Test whether directed connectivity differs between two conditions.

The paired comparison most connectivity studies actually want: the same subjects measured twice, asking which pairs changed. Both inputs must be ordered identically, so that row k of each is the same subject.

Parameters:

condition_a, condition_bnumpy.ndarray

n_observations x m x m dPTE matrices, paired along the first axis

method{“wilcoxon”, “ttest”}

Wilcoxon signed-rank by default

alphafloat

target false discovery rate

Returns:

resultGroupResult

effect holds the mean difference, condition_a minus condition_b

pyPTE.cluster_permutation(condition_a, condition_b=None, *, reference=0.5, threshold_p=0.01, n_permutations=1000, alpha=0.05, seed=None)

Cluster-based permutation test over a connectivity matrix.

The multiple-comparison approach the M/EEG literature expects, adapted to connectivity as the network-based statistic: threshold the edgewise statistic, group the survivors into connected components, and compare each component’s mass against the null of the largest component under random sign flips. Because the null is built from the maximum, family-wise error is controlled across the whole matrix without testing each edge separately.

It is more powerful than Benjamini-Hochberg when an effect is distributed over several connected edges, and less powerful when effects are isolated, since a lone edge forms a cluster of one. Its claim is also weaker: a significant cluster means “this component contains an effect”, not “each of these edges is an effect”.

Parameters:

condition_anumpy.ndarray

n_observations x m x m array of dPTE matrices

condition_bnumpy.ndarray | None

paired second condition. When omitted, condition_a is tested against reference instead.

referencefloat

no-effect value for the one-sample case; 0.5 for dPTE

threshold_pfloat

cluster-forming threshold, as an uncorrected two-tailed p-value. This is a free parameter of the method, not an inference: raising it favours few large clusters, lowering it favours many small ones.

n_permutationsint

size of the permutation null. When 2 ** n_observations is no larger, every sign pattern is used once instead, which makes the test exact.

alphafloat

cluster-level significance

seedint | None

Returns:

resultClusterResult

pyPTE.benjamini_hochberg(p_values, alpha=0.05)

Control the false discovery rate across a family of p-values.

Bonferroni is the wrong instrument here: a 100-channel recording yields 9900 ordered pairs, and dividing alpha by that leaves no power to detect anything. Benjamini-Hochberg instead bounds the expected share of false positives among the pairs actually called significant.

Parameters:

p_valuesnumpy.ndarray

array of p-values, of any shape

alphafloat

target false discovery rate

Returns:

(significant, threshold)tuple of (numpy.ndarray, float)

boolean mask matching the input shape, and the largest p-value called significant, which is 0.0 when nothing survives

Results

class pyPTE.SignificanceResult(dPTE, raw_PTE, effective_PTE, p_values, significant, threshold, null_mean, n_surrogates, raw_null_mean, null_distribution=None, reversed_dPTE=None, reversed_p_values=None, reversal_confirmed=None, differenced_dPTE=None)

Outcome of a surrogate test over every ordered channel pair.

Attributes:

dPTEnumpy.ndarray

m x m observed dPTE matrix

raw_PTEnumpy.ndarray

m x m observed raw PTE matrix, in bits

effective_PTEnumpy.ndarray

m x m raw PTE minus the mean raw PTE of the surrogates, in bits: the effective transfer entropy of Marschinski & Kantz (2002) computed on phase, as in Yang et al. (2017) and Kudo et al. (2022), but against time-shifted rather than shuffled surrogates. The surrogates carry the estimator’s bias but no coupling, so the difference is the transfer beyond chance, comparable across recordings and bin counts where raw PTE is not. Values below zero are kept, since clipping them would bias any average taken across subjects. The diagonal is zero.

p_valuesnumpy.ndarray

m x m one-sided p-values against the surrogate null. The diagonal is set to 1.0, since self-transfer is identically zero.

significantnumpy.ndarray

m x m boolean mask of pairs surviving multiple-comparison correction

thresholdfloat

largest p-value called significant, or 0.0 if nothing survived

null_meannumpy.ndarray

m x m mean of the surrogate null, useful for seeing which pairs carry a bias that has nothing to do with coupling

n_surrogatesint

number of surrogates the null was built from

raw_null_meannumpy.ndarray

m x m mean raw PTE of the surrogates, in bits: the bias floor that effective_PTE subtracts

null_distributionnumpy.ndarray | None

n_surrogates x m x m array of surrogate dPTE values, present only when the test was run with keep_null=True. Useful for plotting where an observation falls within its own null, at the cost of holding every surrogate matrix in memory.

reversed_dPTEnumpy.ndarray | None

m x m dPTE of the time-reversed recording, present only when the test was run with time_reversal=True

reversed_p_valuesnumpy.ndarray | None

m x m p-values of the time-reversed recording against its own surrogates, built from the same shifts

reversal_confirmednumpy.ndarray | None

m x m boolean mask of significant pairs whose direction flips, significantly, when time is reversed. Like significant it is symmetric: the mask marks a pair, and dPTE says which way it points.

differenced_dPTEnumpy.ndarray | None

m x m time-reversal-differenced dPTE (see pyPTE.core.pyPTE.reversal_differenced_dPTE), in which directions that come from a difference in signal-to-noise ratio or from instantaneous mixing cancel. It is reported as an effect size only. The surrogate null assumes independent channels, which mixing violates, so to test it, compute it per segment or epoch (PTE_segments, or PTE_from_epochs(time_reversal=True)) and use group_test.

class pyPTE.GroupResult(statistic, p_values, significant, threshold, effect, n_observations, method)

Outcome of a test across repeated observations of the same channel pairs.

Attributes:

statisticnumpy.ndarray

m x m test statistic per ordered pair

p_valuesnumpy.ndarray

m x m p-values, with the diagonal set to 1.0

significantnumpy.ndarray

m x m boolean mask surviving Benjamini-Hochberg correction

thresholdfloat

largest p-value called significant, or 0.0 if nothing survived

effectnumpy.ndarray

m x m mean of the quantity tested: the mean dPTE for group_test, or the mean difference between conditions for group_contrast

n_observationsint

number of epochs, trials or subjects the test ran over

methodstr

which test was applied

class pyPTE.ClusterResult(statistic, clusters, cluster_p, significant, threshold, n_permutations, alpha=0.05)

Outcome of a cluster-based permutation test over a connectivity matrix.

Attributes:

statisticnumpy.ndarray

m x m t-statistic per ordered pair

clusterslist of numpy.ndarray

boolean m x m masks, one per connected component found above the cluster-forming threshold, ordered from strongest to weakest. For dPTE each pair appears once, at [i, j] where i drives j.

cluster_pnumpy.ndarray

p-value per cluster, against the null of the largest cluster mass

significantnumpy.ndarray

m x m boolean mask: the union of the clusters that survived, marking both orientations of each pair for dPTE

thresholdfloat

the cluster-forming t-threshold that was applied

n_permutationsint

size of the null that was used, 2 ** n_observations when exact

alphafloat

the cluster-level significance threshold that was applied

Adapters

PTE_from_mne and PTE_from_dataframe return labelled pandas.DataFrame results; PTE_from_epochs returns one matrix per epoch, ready for the group tests.

pyPTE.adapters.mne_adapter.PTE_from_mne(raw, picks=None, *, binning='scott', delay='zero-crossing', trim_cycles=0.0)

Computes dPTE and raw PTE matrices for the channels of an mne.io.Raw object

Parameters:

rawmne.io.Raw

EEG or MEG recording serving data in sensor space

picksstr | list | slice | None

Channels to analyse, accepting anything mne.io.Raw.pick() accepts. By default every channel is used, which for an unfiltered recording will include non-data channels such as stimulus triggers.

binning, delay, trim_cycles

passed to pyPTE.PTE

Returns:

(dPTE_df, raw_PTE_df)tuple of pandas.DataFrame objects

The dPTE and raw PTE matrices, indexed in both dimensions by channel name, so entry [i, j] describes information flow from channel i to channel j

pyPTE.adapters.mne_adapter.PTE_from_epochs(epochs, picks=None, *, binning='scott', delay='zero-crossing', trim_cycles=0.0, time_reversal=False)

Computes one dPTE and raw PTE matrix per epoch of an mne.Epochs object

The delay and the bins are estimated once, over all epochs together, and shared by every epoch. A short epoch gives a noisy estimate of either on its own, and matrices computed with different bin counts carry different estimator bias, which a test across epochs would mistake for an effect.

Parameters:

epochsmne.Epochs

epoched EEG or MEG data in sensor space

picksstr | list | slice | None

channels to analyse, accepting anything mne.Epochs.pick() accepts; by default every channel

binning, delay, trim_cycles

as for pyPTE.PTE, applied to every epoch with shared settings

time_reversalbool

return the time-reversal-differenced dPTE of each epoch, as for pyPTE.PTE. Passed to group_test, this is the robust test of direction: directions produced by signal-to-noise differences or instantaneous mixing cancel in every epoch.

Returns:

(dPTE, raw_PTE)tuple of numpy.ndarray objects

n_epochs x m x m arrays, ready for pyPTE.group_test, group_contrast or cluster_permutation. Channels follow epochs.ch_names after picks, and entry [k, i, j] is the flow from channel i to channel j in epoch k.

pyPTE.adapters.mne_adapter.interpolate_mne(raw, raw_reference)

Restores channels missing from a recording by interpolating them

MNE can only interpolate channels that are present and marked as bad, so a recording that is missing channels outright cannot be repaired directly. This function inserts the missing channels as silent placeholders carrying the sensor positions of a reference recording, marks them bad, and lets mne.io.Raw.interpolate_bads() fill them in.

Parameters:

rawmne.io.Raw

The object missing channels to be interpolated

raw_referencemne.io.Raw

The reference object containing all desired channels, used as the source of the sensor positions for the missing channels

Returns:

interpolatedmne.io.Raw

New object containing all information from the original raw object and interpolated channels

Raises:

ValueError

If the two recordings do not share a sampling frequency, in which case the placeholder channels could not be concatenated onto the timeline

pyPTE.adapters.pandas_adapter.PTE_from_dataframe(data_frame, *, binning='scott', delay='zero-crossing', trim_cycles=0.0)

Computes dPTE and raw PTE matrices for the channels of a pandas.DataFrame

Parameters:

data_framepandas.DataFrame

This object contains time-series data where pandas.DataFrame.index corresponds to the time samples and pandas.DataFrame.columns represents the individual channels

binning, delay, trim_cycles

passed to pyPTE.PTE

Returns:

(dPTE_df, raw_PTE_df)tuple of pandas.DataFrame objects

The results from pyPTE.pyPTE.PTE are stored as pandas.DataFrames, indexed in both dimensions by pandas.DataFrame.columns of the input, so entry [i, j] describes information flow from channel i to channel j

pyPTE.core.handle_multi.multi_process(measurements, *, binning='scott', delay='zero-crossing', trim_cycles=0.0, n_jobs=None)

Computes PTE for several measurements in parallel

Parameters:

measurementsdict

dict : key, (n_channels, n_samples) array

binning, delay, trim_cycles

passed to pyPTE.PTE for every measurement

n_jobsint | None

worker processes; every CPU by default or with -1, and 1 runs in this process

Returns:

resultslist of dict

one dict per measurement: key, (dPTE, rawPTE) tuple