做什么（One-liner）

Engle-Granger 2 步协整检验：两条序列是否存在 long-run 稳态关系，返回 t-stat / p-value / hedge ratio / spread z-score。配对交易的必备前置筛选。

怎么用

Canvas 拖 cointegration_v1，填 series_a、series_b（必填）+ significance（可选，默认 0.05）。输出布尔判断 + 完整统计量。

典型用法：

series_a = SPY 价格
series_b = IVV 价格          # 都跟踪 S&P 500，应该高度协整
→ is_cointegrated: True, hedge_ratio ≈ 1.0, z_score ≈ 0

核心公式

Step 1 — OLS:   a_t = α + β · b_t + ε_t
Step 2 — ADF:   H0: ε_t has unit root (not cointegrated)
                H1: ε_t is I(0) stationary
                → p-value < significance → reject H0 → cointegrated

spread_t = a_t - α - β · b_t
z_t = (spread_t - mean(spread)) / std(spread, ddof=0)

Rounding 契约（golden 锁定）：

• t_stat / p_value / critical_values / z_score → round(4)
• hedge_ratio / spread_mean / spread_std → round(6)

假设与适用场景

假设：两序列都 I(1) + 线性协整 + constant-only（无 trend）+ 同步时间戳。

适用：ETF 对配对交易、跨市场套利、宏观 long-run 关系；n≥30（实操 n≥100 更稳）。

不适用：HFT / tick、> 2 序列（用 Johansen）、非线性 / regime-switch。

输入 / 输出契约

{series_a, series_b, significance?} → {is_cointegrated, t_statistic, p_value, critical_values: {1%, 5%, 10%}, hedge_ratio, spread_mean, spread_std, current_z_score, n_observations, _method}。详见 frontmatter。

已知局限

1. Pairwise only（> 2 需 Johansen）
2. n=30 低 power，实操 n≥100 更可靠
3. Constant-only（无 deterministic trend）
4. 不输出 β 的 SE / CI
5. 不做 structural break test（Gregory-Hansen 未实现）
6. spread std 用 ddof=0（Bloomberg 有时用 ddof=1）

参考文献

Engle-Granger (1987) 诺奖原始论文 + Hamilton (1994) Ch.19 教科书 + MacKinnon (2010) critical values 表（statsmodels 内部使用）。详见 frontmatter。

Golden Test

tests/golden/fixtures/tier2/cointegration/，1e-12 tolerance（post-rounding byte-equality）。4 tests：

• matches_reference — field-by-field byte equality vs wrapper-mirrored reference
• determinism — 5 reruns byte-identical
• rejects_short_series — n<30 → error payload
• significance_threshold_matters — significance 改变 is_cointegrated 布尔但不影响 t_stat / p_value / hedge_ratio 等 intrinsic 量

参考实现走同样的 statsmodels.coint + np.linalg.lstsq OLS 派生，锁定 Pangura 的 wrapper 行为（输入 cast / rounding / design matrix / std ddof）。

Changelog

• 1.0.0 (2026-04-20) — 首次 Active