When Did Your Metric Actually Shift? Find The Break Dates

How it works

The series is ordered by date, rows sharing a date are averaged into one point, and binary segmentation then searches it for level shifts. Every admissible split is scored with the Gaussian change-in-mean likelihood ratio: a segment of length m with residual sum of squares RSS costs m x log(RSS / m), and a candidate scores the whole-segment cost minus the two piece costs, computed directly over cumulative sums in base R. The best-scoring split is accepted only if it beats a modified-BIC penalty of 3 x log(n), which replaces the plain BIC form because the maximum statistic over every candidate location clears 2 x log(n) on pure noise too often; each accepted split is then searched again, up to a stated maximum number of breaks and never closer than the minimum segment length to a boundary. Each accepted break gets a permutation p-value from 499 reshuffles of its surrounding window, compared against the largest statistic anywhere in that window so the p-value is conservative. Residual lag-1 autocorrelation and a smooth-trend comparison are both computed and reported as cautions when they fire.

Use it when you have a metric measured over time and want to know whether, and exactly when, its level stepped up or down, without having to nominate the date yourself.

Not when you already know the date something happened and want its effect measured (use the interrupted time series tool, which also estimates the change in trend), not for forecasting where the series is heading, not for recurring seasonal ups and downs (use the seasonality tool), and not as evidence that any particular event caused a break. It locates shifts, it does not explain them.

What data do you need?

One row per period with the date and the metric. For example, daily active users around an unknown change:

Minimum 20 rows · Best with 60-2,000 evenly spaced periods

What's in the report?

Standard-library analysis: when did my metric shift? Detect structural breaks and level changes in a time series with dates and magnitudes. Map a date column and a numeric series and get every point at which the average level moved: the date of each break, the mean level before and after, the size and direction of the move in units and percent, a permutation p-value per break, and the series charted with the fitted step level so each break is visible as a riser. Binary segmentation with a Gaussian change-in-mean likelihood ratio decides how many breaks the data supports, guarded by a minimum segment length, a modified-BIC penalty and a stated maximum number of changepoints, and when nothing clears the penalty the report says so and shows the candidate it rejected.