| 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:
- 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.
- 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.
- Hazard. Geometric with rate 1/lambda_run. lambda_run is the
prior mean run length between change points.
- 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.
- Segments. The boundaries partition the return series into
segments; per-segment stats let a reader see the shift.
Foundations used
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.
