Pairs Cointegration

Family: Stat-arb

What it computes

Emits PairsCointegrationTick ticks carrying hedge_ratio, adf, is_cointegrated off daily-close cache (2 symbols).

Available on the live and replay drives. The historical drive fails closed with KAIROS_ERR_HISTORICAL_UNWIRED until the relevant cache is hydrated externally.

Methodology

Engle-Granger (1987) 2-step + MacKinnon (1991) ADF critical value −3.34.

See the methodology overview for the citation index.

Inputs

Daily-close cache (2 symbols).

Key outputs

Hedge_ratio, adf, is_cointegrated. The full field set is in the tick table below.

Output schema (PairsCointegrationTick)

The field / type / description table below is regenerated from the PairsCointegrationTick Rust source by docs-site/scripts/inject-doc-tables.ts on every npm run docs:build. Do not hand-edit between the sentinels.

Field	Type	Description
symbol_a	Arc<str>	First leg of the pair — the symbol on the LHS of the regression. Interned.
symbol_b	Arc<str>	Second leg of the pair — the symbol on the RHS of the regression. Interned. Echoed on every emission so consumers can audit the spec wiring directly.
date	i32	Trading-session date (YYYYMMDD) at emission time.
ms_of_day	i32	Milliseconds since midnight ET at emission time. 0 for watermark-driven boot snapshots before any live tick.
hedge_ratio	f64	OLS slope δ̂ from the long-run regression. The per-share hedge ratio — short δ̂ shares of B per long share of A so the spread is mean-reverting under the cointegration null.
gamma_intercept	f64	OLS intercept γ̂ from the long-run regression. The equilibrium log-price differential.
adf_statistic	f64	Augmented Dickey-Fuller test statistic — ρ̂ / SE(ρ̂) per the canonical Dickey-Fuller (1979) construction on the regression residuals. Negative-and-large-magnitude values reject the unit-root null and indicate cointegration.
is_cointegrated	bool	Cointegration verdict — true when adf_statistic < critical_value (default -3.34 per MacKinnon (1991) 95% two-variable cutoff). The institutional pair-trading signal: flip to a long-spread / short-spread mean-reversion strategy when the pair is cointegrated.
residual_current	f64	Latest in-sample residual ε_T = log(price_a)_T − γ̂ − δ̂ · log(price_b)_T — the per-emit spread reading. Positive values indicate A is over-priced relative to the cointegrating vector; negative values indicate A is under-priced.
residual_zscore	f64	Standardized residual residual_current / σ_residual — the institutional spread z-score every pair-trading desk fires entry signals off (`
sessions_used	i32	Count of paired log-price observations the regression actually consumed. Values below lookback_sessions signal a warm-up regime where the fit is computed off a shorter window than the institutional target.
lookback_sessions	i32	The configured trailing-window length, echoed for audit so consumers can compare sessions_used against the target directly.

Configuration (PairsCointegrationParams)

Regenerated from the PairsCointegrationParams Rust source — see the note above.

Field	Type	Description
contracts	SecurityFilter	Contracts the subscription tracks. The analytic regresses symbol_a (the leg the [SecurityFilter] selects) against symbol_b (the fixed comparator on the spec). Stocks only — the analytic silently ignores option / index trades at the on_tick entry point.
conditions	ConditionPolicy	Trade-condition admission policy applied to every print.
venues	ExchangeFilter	Exchange / venue admission policy.
daily_close	Arc<DailyCloseCache>	Boot-time hydrated daily-close cache. Must hold at least lookback_sessions rows for BOTH symbol_a AND symbol_b for the regression window to populate fully (a shorter intersection yields a degraded fit with reduced statistical power).
symbol_b	Arc<str>	Fixed reference symbol — symbol_b on the regression log(price_a) = γ + δ · log(price_b) + ε. Subscribers thread the comparator leg through the spec; the per-contract [SecurityFilter] resolves symbol_a.
lookback_sessions	usize	Trailing-window length in trading sessions. Defaults to [DEFAULT_LOOKBACK_SESSIONS] (252 = one trading year).
critical_value	f64	ADF critical value below which is_cointegrated flips to true. Defaults to [COINTEGRATION_CRITICAL_VALUE_95] (-3.34 per MacKinnon (1991) Table 1, two-variable 95% quantile). Override with -3.90 for the 99% cutoff or -3.04 for the 90% cutoff.
adf_lags	i32	Augmentation order p of the residual ADF regression — the number of lagged first-difference terms Δε_{t-1} … Δε_{t-p} absorbing residual serial correlation (Said-Dickey 1984). Defaults to [DEFAULT_ADF_LAGS] (1); 0 selects the plain Dickey-Fuller regression; negative values clamp to 0.
min_emit_interval_ms	i32	Minimum interval between emissions per pair, in milliseconds. Defaults to [DEFAULT_MIN_EMIT_INTERVAL_MS] (60_000 ms / 1 min).

Example

Python

import kairos_thetadata as kt

client = kt.Client.connect(kt.Credentials.from_env())

def on_event(row):
    print(row)

sub = client.live().pairs_cointegration(["QQQ"]).on_event(on_event)
sub.wait(timeout_seconds=60.0)

TypeScript

import { Client, Credentials } from "kairos-thetadata";

const client = await Client.connect(Credentials.fromEnv());

await client
  .live()
  .pairsCointegration(["QQQ"])
  .onEvent((tick) => {
    console.log(tick);
  });

Rust

// Cargo.toml:
//   kairos = "0.1"

use kairos::{Client, PairsCointegrationRow};

# fn run() -> Result<(), Box<dyn std::error::Error>> {
let client = Client::connect(("me@example.com", "secret"))?;

let sub = client
    .live()
    .pairs_cointegration(["QQQ"])
    .on_event(|row: &PairsCointegrationRow| println!("hedge_ratio={} gamma={}", row.hedge_ratio, row.gamma_intercept))?;

// ... later, to stop delivery ...
sub.unsubscribe();
# Ok(())
# }