att.benchmarks

Benchmark coupling methods and sweep framework.

att.benchmarks.transfer_entropy(X, Y, k=1, bins=8, **kwargs)

Compute transfer entropy TE(X -> Y) using histogram estimation.

Measures information transfer from X to Y beyond Y’s own history.

Parameters:

• X (1D time series (same length))

• Y (1D time series (same length))

• k (history length (lag))

• bins (number of bins for discretization)

Returns:

float

Return type:

TE(X -> Y) in nats

att.benchmarks.pac(X, Y, n_bins=18, **kwargs)

Compute phase-amplitude coupling modulation index (Tort et al. 2010).

Measures how much the amplitude of Y is modulated by the phase of X. Uses raw Hilbert transform (no bandpass) — appropriate for broadband chaotic signals where PAC is expected to return near-zero.

Parameters:

• X (1D time series (same length))

• Y (1D time series (same length))

• n_bins (number of phase bins)

Returns:

float

Return type:

modulation index in [0, 1]

att.benchmarks.crqa(X, Y, embedding_dim=3, delay=1, radius=None, min_line=2, **kwargs)

Compute cross-recurrence quantification analysis determinism.

Parameters:

• X (1D time series)

• Y (1D time series)

• embedding_dim (embedding dimension for delay vectors)

• delay (time delay for embedding)

• radius (recurrence threshold; if None, auto-select 10th percentile of distances)

• min_line (minimum diagonal line length for determinism)

Returns:

float

Return type:

determinism (fraction of recurrence points on diagonal lines >= min_line)

class att.benchmarks.CouplingBenchmark(methods=None, normalization='rank')

Bases: object

Benchmark multiple coupling measures on the same system pairs.

Parameters:

• methods (list of method names, or None for all built-in methods) – Built-in: “binding_score”, “transfer_entropy”, “pac”, “crqa”

• normalization (str) – “rank” (default), “minmax”, “zscore”, or “none”

register_method(name, fn)

Register a custom coupling method.

Parameters:

• name (method name (appears in output))

• fn (callable(X, Y) -> float)

Return type:

None

run(X, Y, **kwargs)

Compute all registered methods on a single pair.

Returns:

dict

Return type:

{method_name: score}

Parameters:

• X (ndarray)

• Y (ndarray)

sweep(generator_fn, coupling_values, seed=None, transient_discard=1000)

Run all methods across a range of coupling values.

Parameters:

• generator_fn (callable(coupling, seed) -> (X, Y) tuple of arrays)

• coupling_values (coupling strengths to sweep)

• seed (random seed (same for all coupling values))

• transient_discard (samples to discard from start of each time series)

Returns:

DataFrame with columns

Return type:

coupling, method, score, score_normalized

Standalone coupling measurement methods for benchmarking.

att.benchmarks.methods.transfer_entropy(X, Y, k=1, bins=8, **kwargs)

Compute transfer entropy TE(X -> Y) using histogram estimation.

Measures information transfer from X to Y beyond Y’s own history.

Parameters:

• X (1D time series (same length))

• Y (1D time series (same length))

• k (history length (lag))

• bins (number of bins for discretization)

Returns:

float

Return type:

TE(X -> Y) in nats

att.benchmarks.methods.pac(X, Y, n_bins=18, **kwargs)

Compute phase-amplitude coupling modulation index (Tort et al. 2010).

Measures how much the amplitude of Y is modulated by the phase of X. Uses raw Hilbert transform (no bandpass) — appropriate for broadband chaotic signals where PAC is expected to return near-zero.

Parameters:

• X (1D time series (same length))

• Y (1D time series (same length))

• n_bins (number of phase bins)

Returns:

float

Return type:

modulation index in [0, 1]

att.benchmarks.methods.crqa(X, Y, embedding_dim=3, delay=1, radius=None, min_line=2, **kwargs)

Compute cross-recurrence quantification analysis determinism.

Parameters:

• X (1D time series)

• Y (1D time series)

• embedding_dim (embedding dimension for delay vectors)

• delay (time delay for embedding)

• radius (recurrence threshold; if None, auto-select 10th percentile of distances)

• min_line (minimum diagonal line length for determinism)

Returns:

float

Return type:

determinism (fraction of recurrence points on diagonal lines >= min_line)

class att.benchmarks.CouplingBenchmark(methods=None, normalization='rank')

Bases: object

Benchmark multiple coupling measures on the same system pairs.

Parameters:

• methods (list of method names, or None for all built-in methods) – Built-in: “binding_score”, “transfer_entropy”, “pac”, “crqa”

• normalization (str) – “rank” (default), “minmax”, “zscore”, or “none”

__init__(methods=None, normalization='rank')

Parameters:

• methods (list[str] | None)

• normalization (str)

register_method(name, fn)

Register a custom coupling method.

Parameters:

• name (method name (appears in output))

• fn (callable(X, Y) -> float)

Return type:

None

run(X, Y, **kwargs)

Compute all registered methods on a single pair.

Returns:

dict

Return type:

{method_name: score}

Parameters:

• X (ndarray)

• Y (ndarray)

sweep(generator_fn, coupling_values, seed=None, transient_discard=1000)

Run all methods across a range of coupling values.

Parameters:

• generator_fn (callable(coupling, seed) -> (X, Y) tuple of arrays)

• coupling_values (coupling strengths to sweep)

• seed (random seed (same for all coupling values))

• transient_discard (samples to discard from start of each time series)

Returns:

DataFrame with columns

Return type:

coupling, method, score, score_normalized