/change-point-detector

name: change-point-detector
description: Bayesian Online Change-Point Detection (BOCPD) on a ticker's daily log returns. Detects points in time where the return-generating distribution changed (regime shift in mean, vol, or both), reports the confidence at each detected boundary, and emits per-segment statistics (annualized return, annualized vol) so the reader can see what changed. Uses Adams and MacKay (2007) BOCPD with a Normal-Gamma prior on (mu, tau) and a Student-t predictive so hyperparameters update in closed form. Requires Stocks Basic. Runs on the free tier.

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`](../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.