milia.anomaly.changepoint#

Change-point detection: when did a meter’s behaviour change?

Functions

binseg(series[, changes, model])

Binary segmentation into a fixed number of changes through ruptures.

cusum(series[, threshold, drift, baseline])

Two-sided Page CUSUM change points on a standardised series.

ewmapaths(series, baseline[, smoothing])

Exponentially weighted moving average of many standardised series, the alternative to paths().

firstalarms(statistic, limit[, baseline])

The point of each series' first exceedance of a decision limit.

pathlimit(statistic[, alpha])

Decision limit calibrated on series known not to change: the conformal quantile of their largest statistic.

paths(series, baseline[, drift])

One-sided CUSUM statistic of many series at once, each standardised by its own baseline.

pelt(series[, penalty, model, minimum])

Optimal segmentation by PELT (Killick, Fearnhead and Eckley, 2012) through ruptures.

milia.anomaly.changepoint.cusum(series, threshold=5.0, drift=0.5, baseline=None)#

Two-sided Page CUSUM change points on a standardised series.

The series is standardised by the mean and standard deviation of its first baseline points (a quarter of the series by default); an alarm fires when either cumulative sum exceeds threshold, and both sums reset. Needs no optional dependency.

Parameters:
  • series (ArrayLike) – Observations in time order.

  • threshold (float) – Alarm level, in standard deviations.

  • drift (float) – Allowance subtracted at each step, in standard deviations.

  • baseline (int | None) – Points used to estimate the in-control mean and spread.

Return type:

ndarray

Returns:

Indices at which an alarm fired.

Examples

>>> series = np.r_[np.zeros(50), np.full(50, 5.0)] + np.random.default_rng(0).normal(size=100)
>>> first = int(cusum(series, threshold=8.0)[0])
>>> 45 <= first <= 55  # the change is at index 50
True
milia.anomaly.changepoint.pelt(series, penalty=10.0, model='rbf', minimum=2)#

Optimal segmentation by PELT (Killick, Fearnhead and Eckley, 2012) through ruptures.

Parameters:
  • series (ArrayLike) – Observations in time order, 1-D or (n, d).

  • penalty (float) – Penalty per change point; larger finds fewer changes.

  • model (str) – Cost model of ruptures, e.g. "l2" (mean shifts) or "rbf".

  • minimum (int) – Smallest segment length.

Return type:

ndarray

Returns:

Indices where a new segment starts (the series end excluded).

Examples

>>> series = np.r_[np.zeros(50), np.full(50, 5.0)]
>>> pelt(series, model="l2").tolist()
[50]
milia.anomaly.changepoint.binseg(series, changes=1, model='l2')#

Binary segmentation into a fixed number of changes through ruptures.

Parameters:
  • series (ArrayLike) – Observations in time order, 1-D or (n, d).

  • changes (int) – Number of change points to find.

  • model (str) – Cost model of ruptures.

Return type:

ndarray

Returns:

Indices where a new segment starts (the series end excluded).

Examples

>>> binseg(np.r_[np.zeros(50), np.full(50, 5.0)]).tolist()
[50]
milia.anomaly.changepoint.paths(series, baseline, drift=0.5)#

One-sided CUSUM statistic of many series at once, each standardised by its own baseline.

Each row is standardised by its mean and standard deviation over its first baseline points, and the statistic \(S_t = \max(0, S_{t-1} + z_t - k)\) is accumulated from the point after the baseline (Page, 1954). Unlike cusum(), the statistic is returned rather than reset at an alarm, so that a decision limit can be calibrated on it (pathlimit()).

Parameters:
  • series (ArrayLike) – Observations in time order, shape (series, points).

  • baseline (int) – Number of initial points that define each series’ in-control mean and spread.

  • drift (float) – Allowance \(k\) in standard deviations; shifts smaller than about 2 * drift are ignored.

Return type:

ndarray

Returns:

The statistic, shape (series, points - baseline); column t is point baseline + t.

Examples

>>> rng = np.random.default_rng(0)
>>> series = rng.normal(1.0, 0.1, (2, 40))
>>> series[1, 25:] += 0.3
>>> statistic = paths(series, baseline=12)
>>> statistic.shape, bool(statistic[1].max() > statistic[0].max())
((2, 28), True)
milia.anomaly.changepoint.firstalarms(statistic, limit, baseline=0)#

The point of each series’ first exceedance of a decision limit.

Parameters:
  • statistic (ArrayLike) – Statistic from paths(), shape (series, points).

  • limit (float) – Decision limit.

  • baseline (int) – Offset added to the column index, so that the result counts from the start of the series.

Return type:

ndarray

Returns:

The point of the first alarm per series, or -1 for a series never alarmed.

Examples

>>> firstalarms(np.array([[0.0, 2.0, 6.0], [0.0, 1.0, 2.0]]), limit=5.0, baseline=10).tolist()
[12, -1]
milia.anomaly.changepoint.pathlimit(statistic, alpha=0.1)#

Decision limit calibrated on series known not to change: the conformal quantile of their largest statistic.

A series exchangeable with the calibration series, and without a change, crosses the limit within the horizon with probability at most about alpha. This replaces the nominal limit of a CUSUM, whose run length assumes independent observations with a known spread, by one that holds for the series at hand.

Parameters:
  • statistic (ArrayLike) – Statistic from paths() of the calibration series, shape (series, points).

  • alpha (float) – Target share of unchanged series alarmed within the horizon.

Return type:

float

Returns:

The calibrated limit.

Examples

>>> statistic = np.arange(20.0)[:, None] * np.ones((1, 3))
>>> pathlimit(statistic, alpha=0.1)
18.0
milia.anomaly.changepoint.ewmapaths(series, baseline, smoothing=0.2)#

Exponentially weighted moving average of many standardised series, the alternative to paths().

Each row is standardised by its baseline as in paths(), and the statistic \(E_t = \lambda z_t + (1 - \lambda) E_{t-1}\) starts at zero after the baseline (Roberts, 1959). It weighs recent points more and forgets old ones, so it reacts to a small shift more slowly than the CUSUM but recovers after a transient one.

Parameters:
  • series (ArrayLike) – Observations in time order, shape (series, points).

  • baseline (int) – Number of initial points that define each series’ in-control mean and spread.

  • smoothing (float) – Weight \(\lambda\) of the newest point, in (0, 1].

Return type:

ndarray

Returns:

The statistic, shape (series, points - baseline); compare it with pathlimit() as for paths().

Examples

>>> rng = np.random.default_rng(0)
>>> series = rng.normal(1.0, 0.1, (2, 40))
>>> series[1, 25:] += 0.3
>>> statistic = ewmapaths(series, baseline=12)
>>> bool(statistic[1, -1] > statistic[0, -1])
True