Change point detector

change-point-detector

You hand over a ticker. The skill pulls 2 years of daily closes, computes log returns, and runs Bayesian Online Change-Point Detection. Reports the specific dates where the return distribution appears to have shifted, the confidence at each boundary, and the annualized return + vol per segment so you can see what changed.

When to invoke

• "When did SPY's regime shift this cycle?"
• Sharpening market-regime when the rule buckets miss the edge
• Auditing a pairs-scanner result: "did this pair's cointegration break, and if so when?"
• Post-hoc labeling on a name that behaved differently pre- and post-a specific event

Not for: real-time entries. BOCPD lags real change points by 5-20 observations; the algorithm needs enough post-shift data to update the posterior.

What you need

• A ticker (--ticker)
• MASSIVE_API_KEY exported
• Stocks Basic minimum

Optional:

• --lookback-days (default 504, ~2 years). Minimum 100.
• --lambda-run (default 250): prior mean run length between change points in observations. 250 = "expect roughly one change per year." Raise to 500 to suppress smaller regime edges; lower to 100 to be more sensitive to short-lived regimes.

What you get back

Two output layers from one run.

Layer 1: canonical JSON. change_points with per-detection date, index, and posterior confidence. segments with per-segment n_obs, mean/std daily return, and annualized return + vol. current_run_length_obs for how many observations since the last detected boundary. Full setup echoed (lambda_run_prior, threshold).

Layer 2: rendered note. Header + summary of counts, detected change point list, segment stats table, one-line Take comparing current vs prior regime.

How it works

Adams and MacKay (2007) BOCPD:

1. Model. Assume returns are drawn from a Normal, with unknown mean mu and precision tau. Put a Normal-Gamma prior on (mu, tau) with hyperparameters (mu0=0, kappa0=1, alpha0=0.1, beta0=0.01). This gives a Student-t predictive with closed-form updates when a new observation arrives.
2. Run length posterior. Maintain P(r_t = r | x_{1:t}), the posterior over "run length since last change point." At each t:
   • Growth: with prob 1 - hazard, r_t = r_{t-1} + 1. Weight by the Student-t predictive under the sufficient stats accumulated for that run.
   • Change: with prob hazard, r_t = 0. Weight by the marginal predictive summed over all previous run lengths.
   • Normalize.
3. Hazard. Geometric with rate 1/lambda_run. lambda_run is the prior mean run length between change points.
4. Detection. A time t is flagged as a change point when P(r_t = 0 | x_{1:t}) exceeds the threshold (0.5 by default). Consecutive detections within 20 observations are merged.
5. Segments. The boundaries partition the return series into segments; per-segment stats let a reader see the shift.

Foundations used

• massive-api-patterns for REST auth, retry, and daily aggs.

Output mode: note

Narrative note with a per-segment stats block. A single-name change point analysis is typically 0-5 segments; note format reads better than a table.

Endpoints used

• GET /v2/aggs/ticker/{T}/range/1/day/{from}/{to}?adjusted=true One call per run.

Doesn't handle (yet)

• Multivariate. Single-ticker only. A cross-name change-point detector on a portfolio's daily P&L would extend cleanly by swapping the univariate predictive for a multivariate one.
• PELT. Adams-MacKay BOCPD is Bayesian. PELT (Killick, Fearnhead, Eckley 2012) is a frequentist alternative that scales O(N) and gives L2-optimal segmentation. Queued as pelt-segmentation.
• Real-time flag. No streaming mode. Adding one would just wrap the same update inside a loop.
• Hyperparameter tuning. The prior on (mu, tau) is fixed and mild. A caller who cares about specific regime types (vol regime vs mean regime) could tune this.

These are clean PR extensions.