Two signals in. Four-axis coupling profile out. Are they coupled? How? Who drives who?
pip install begump
from gump.couple import profile, quick
# Full 4-axis profile
result = profile(signal_a, signal_b, fs=256)
print(result['K_overall']) # 0.87
print(result['K_filter']) # phase-amplitude coupling
print(result['K_bind']) # temporal binding
print(result['K_hierarchy']) # spectral slope ratio
print(result['K_direction']) # who drives who (-1 to +1)
print(result['diagnosis']) # "strongly coupled, A drives B"
# Quick — one-line verdict
print(quick(signal_a, signal_b, fs=256))
# "COUPLED (filter=0.84, bind=0.91, hier=0.79, dir=+0.32) K=0.87"
K_filter — Phase-amplitude coupling. Does the phase of one signal modulate the amplitude of the other? High = resonant lock.
K_bind — Temporal binding. Do they share structure across time windows? Windowed cross-correlation peak.
K_hierarchy — Spectral slope ratio. Do they occupy the same complexity regime? Ratio of 1/f slopes.
K_direction — Granger-like direction. Who predicts who? Negative = B drives A. Positive = A drives B. Zero = mutual.
K_overall is the geometric mean of the first three axes. The diagnosis combines all four into plain English: "decoupled", "weakly coupled", "coupled, mutual", "strongly coupled, A drives B", "phase-locked".