kats.detectors.cusum_detection module¶

CUSUM stands for cumulative sum, it is a changepoint detection algorithm.

In the Kats implementation, it has two main components:

  1. Locate the change point: The algorithm iteratively estimates the means

    before and after the change point and finds the change point maximizing/minimizing the cusum value until the change point has converged. The starting point for the change point is at the middle.

  2. Hypothesis testing: Conducting log likelihood ratio test where the null

    hypothesis has no change point with one mean and the alternative hypothesis has a change point with two means.

And here are a few things worth mentioning:

  • We assume there is only one increase/decrease change point;

  • We use Gaussian distribution as the underlying model to calculate the cusum

    value and conduct the hypothesis test;

Typical usage example:

>>> # Univariate CUSUM
>>> timeseries = TimeSeriesData(...)
>>> detector = CusumDetector(timeseries)
>>> #Run detector
>>> changepoints = detector.detector()
>>> # Plot the results
>>> detector.plot(changepoints)

The usage is the same for multivariate CUSUM except that the time series needs to be multivariate and that the plotting functions are not yet supported for this use case.

class kats.detectors.cusum_detection.CUSUMDetector(data: kats.consts.TimeSeriesData, is_multivariate: bool = False)[source]¶

Bases: kats.detectors.detector.Detector

detector(**kwargs) → List[Tuple[kats.consts.TimeSeriesChangePoint, kats.detectors.cusum_detection.CUSUMMetadata]][source]¶

Find the change point and calculate related statistics.

Parameters

  • threshold – Optional; float; significance level, default: 0.01.

  • max_iter – Optional; int, maximum iteration in finding the changepoint.

  • delta_std_ratio – Optional; float; the mean delta have to larger than this parameter times std of the data to be consider as a change.

  • min_abs_change – Optional; int; minimal absolute delta between mu0 and mu1.

  • start_point – Optional; int; the start idx of the changepoint, if None means the middle of the time series.

  • change_directions – Optional; list<str>; a list contain either or both ‘increase’ and ‘decrease’ to specify what type of change want to detect.

  • interest_window – Optional; list<int, int>, a list containing the start and end of interest windows where we will look for change points. Note that llr will still be calculated using all data points.

  • magnitude_quantile – Optional; float; the quantile for magnitude comparison, if none, will skip the magnitude comparison.

  • magnitude_ratio – Optional; float; comparable ratio.

  • magnitude_comparable_day – Optional; float; maximal percentage of days can have comparable magnitude to be considered as regression.

  • return_all_changepoints – Optional; bool; return all the changepoints found, even the insignificant ones.

Returns

A list of tuple of TimeSeriesChangePoint and CUSUMMetadata.

plot(change_points: List[Tuple[kats.consts.TimeSeriesChangePoint, kats.detectors.cusum_detection.CUSUMMetadata]]) → None[source]¶

Plot detection results from CUSUM.

Parameters

  • change_points – A list of tuple of TimeSeriesChangePoint and

  • CUSUMMetadata. –

class kats.detectors.cusum_detection.CUSUMMetadata(direction: str, cp_index: int, mu0: Union[float, numpy.ndarray], mu1: Union[float, numpy.ndarray], delta: Union[float, numpy.ndarray], llr_int: float, llr: float, regression_detected: bool, stable_changepoint: bool, p_value: float, p_value_int: float)[source]¶

Bases: object

CUSUM metadata

This is the metadata of the changepoint returned by CusumDetectors

direction¶

a str stand for the changepoint change direction ‘increase’ or ‘decrease’.

cp_index¶

an int for changepoint index.

mu0¶

a float indicates the mean before changepoint.

mu1¶

a float indicates the mean after changepoint.

delta¶

mu1 - mu0.

llr¶

log likelihood ratio.

llr_int¶

log likelihood ratio in the interest window.

regression_detected¶

a bool indicates if regression detected.

stable_changepoint¶

a bool indicates if we have a stable changepoint when locating the changepoint.

p_value¶

p_value of the changepoint.

p_value_int¶

p_value of the changepoint in the interest window.

class kats.detectors.cusum_detection.MultiCUSUMDetector(data: kats.consts.TimeSeriesData)[source]¶

Bases: kats.detectors.cusum_detection.CUSUMDetector

MultiCUSUM is similar to univariate CUSUM, but we use MultiCUSUM to find a changepoint in multivariate time series. The detector is used to detect changepoints in the multivariate mean of the time series. The cusum values and likelihood ratio test calculations assume the underlying distribution has a Multivariate Guassian distriubtion.

data¶

The input time series data from TimeSeriesData

detector(**kwargs) → List[Tuple[kats.consts.TimeSeriesChangePoint, kats.detectors.cusum_detection.CUSUMMetadata]][source]¶

Overwrite the detector method for MultiCUSUMDetector.

Parameters

  • threshold – Optional; float; significance level, default: 0.01.

  • max_iter – Optional; int, maximum iteration in finding the changepoint.

  • start_point – Optional; int; the start idx of the changepoint, if None means the middle of the time series.