/anomaly-detection-time-series

name: anomaly-detection-time-series
description: Formal time-series methods that augment the hand-coded fingerprint library in traffic-change-diagnosis. Use this skill when traffic-change-diagnosis fingerprints overlap, when the user asks "is this real?", or when the change date is contested. Applies STL decomposition, Bayesian online changepoint detection, Prophet, quantile regression, sequential probability ratio test, and Granger causality. Use whenever interpreting a series where day-of-week confounds an eyeballed drop, where two candidate causes share a week, or where an alert needs to fire before an analyst sees the chart. Pairs with analytics-diagnostic-method for the surrounding investigation and with sequential-monitoring for the SPRT details. Triggers when Clamp MCP traffic_timeseries returns a series spanning more than 14 days, or when via Clamp the user shares a daily/hourly metric history that needs a non-eyeball verdict.
when_to_use: When two traffic-change-diagnosis fingerprints fit the same drop with similar confidence and one needs to be picked. When the user asks "is this drop real?" or "did this actually start Tuesday?". When the change date itself is being argued about. When the question is a counterfactual ("where would we be without the drop?"). When two events (deploy + algorithm update + holiday) collided in the same week and only one is the real cause.

Anomaly detection for time series

The fingerprint library in `traffic-change-diagnosis` is a fast first pass: it pattern-matches the *shape* of a drop against twelve common causes. It is right most of the time and wrong when it matters most — when two fingerprints fit the same shape, when the user's eyeballed change date is off by a day, or when a counterfactual baseline is needed instead of a slope match. This skill adds six formal methods that resolve those cases. None of them replace the fingerprints; they adjudicate when fingerprints conflict.

When NOT to use this

• The fingerprint match is unambiguous (single hypothesis, >0.7 confidence in the diagnosis worksheet). Running STL or BOCD on a clean tracking-regression drop is ceremony.
• The series is shorter than 14 days. STL needs at least two full seasonal cycles; BOCD's posterior is noisy with less than ~30 observations; Prophet needs more history than that to fit changepoints. For short series, stick to `analytics-diagnostic-method`'s denominator + sample-size discipline.
• The user wants a real-time alert on a single metric and hasn't already decided what "anomalous" means. That's a monitoring-design conversation, not a detection method; load `sequential-monitoring` instead.
• The metric is count-based with most days at zero (e.g. a niche conversion event). STL and Prophet assume continuous-ish residuals; you'll get nonsense decompositions. Use Poisson-tail tests instead.

Pick one method per question

Do not run all six on every series. Each method answers a different question. Pick by question shape:

| Question | Method | Output | |---|---|---| | Is the change date the user gave actually the change date? | BOCD | Posterior P(changepoint = day t) for every t | | Is today's number real, or is Tuesday always like this? | STL decomposition | Residual z-score against seasonal baseline | | Where would the series be without the drop? | Prophet | Forecast interval treating pre-drop as baseline | | Is *this hour* anomalous, given the usual hour-of-day spread? | Quantile regression | P10/P50/P90 bands per hour | | Should the alert fire now or wait for more data? | SPRT | Log-likelihood ratio crossing a Wald boundary | | X and Y both happened this week — did X precede Y predictively? | Granger causality | F-test on lagged regressors |

If the question doesn't appear in this table, you're probably back in fingerprint territory. Don't reach for these.

The six methods

Method 1. STL decomposition (Cleveland 1990)

STL — Seasonal-Trend decomposition using LOESS — splits the series into three additive components: a smooth trend, a periodic seasonal, and a residual. Each is fit by iterated LOESS smoothing, alternating between trend-pass and seasonal-pass until they converge.

The trend captures slow drift. The seasonal captures day-of-week (period=7) or hour-of-day (period=24) cycles. The residual is what's left — and that's where anomalies show up.

**Use it when:** the drop falls on a structurally low day. A Tuesday tracking regression looks identical to "Tuesdays are slow." STL's residual z-scores the day against its own seasonal baseline, so a -30% drop on a normally -25% Tuesday flags as +0.5σ residual (nothing), while a -30% drop on a normally +10% Tuesday flags as -3σ (real).

**How to read it:** compute residual / stdev(residual) over a clean window. |z| > 2.5 is a flag, |z| > 3.0 is a real anomaly. Robust STL (the default in `statsmodels.tsa.seasonal.STL`) handles outliers in the fit itself by downweighting them in the LOESS pass, so a single bad day doesn't poison the seasonal estimate.

**Knobs that matter:**

| Parameter | Default | When to change | |---|---|---| | `period` | required | 7 for daily web traffic, 24 for hourly, 168 for hourly with weekly cycle | | `seasonal` | 7 | Larger window = smoother seasonal; raise if seasonal is bouncing | | `trend` | auto | Lower if trend over-smooths real shifts; raise if it tracks noise | | `robust` | False | Set True if you have known outliers (deploys, holidays) in the window |

**Limit:** STL assumes additive structure. Multiplicative seasonality (traffic that scales proportionally with the trend) needs a log transform first — fit STL on log(y) and exponentiate the components.

Method 2. Bayesian online changepoint detection (Adams & MacKay 2007)

BOCD maintains a posterior distribution over the *run length* — how many days have passed since the last changepoint. At each new observation it updates the posterior by message-passing: P(run_length = r | data) is computed by combining the