kats.detectors.cusum_model module¶

CUSUMDetectorModel is a wraper of CUSUMDetector to detect multiple change points

Typical usage example:

>>> # Define CUSUMDetectorModel
>>> model = CUSUMDetectorModel(
        scan_window=43200,
        historical_window=604800,
        threshold=0.01,
        delta_std_ratio=1.0,
        serialized_model=None,
        change_directions=["increase"],
        score_func=CusumScoreFunction.percentage_change,
        remove_seasonality=True,
    )
>>> # Run detector
>>> respond = model.fit_predict(tsd)
>>> # Plot anomaly score
>>> respond.scores.plot(cols=['value'])
>>> # Get change points in unixtime
>>> change_points = model.cps
class kats.detectors.cusum_model.CUSUMDetectorModel(serialized_model: Optional[bytes] = None, scan_window: Optional[int] = None, historical_window: Optional[int] = None, step_window: Optional[int] = None, threshold: float = 0.01, delta_std_ratio: float = 1.0, magnitude_quantile: Optional[float] = None, magnitude_ratio: float = 1.3, change_directions: Optional[List[str]] = None, score_func: Union[str, kats.detectors.cusum_model.CusumScoreFunction] = <CusumScoreFunction.change: 'change'>, remove_seasonality: bool = False)[source]¶

Bases: kats.detectors.detector.DetectorModel

CUSUMDetectorModel for detecting multiple level shift change points

CUSUMDetectorModel runs CUSUMDetector multiple times to detect multiple change points. In each run, CUSUMDetector will use historical_window + scan_window as input time series, and find change point in scan_window. The DetectorModel stores change points and returns anomaly score.

cps¶

Change points detected in unixtime.

alert_fired¶

If a change point is detected and the anomaly still present.

pre_mean¶

Previous baseline mean.

pre_std¶

Previous baseline std.

number_of_normal_scan¶

Number of scans with mean returned back to baseline.

alert_change_direction¶

Increase or decrease.

scan_window¶

Length in seconds of scan window.

historical_window¶

Length in seconds of historical window.

step_window¶

The time difference between CUSUM runs.

threshold¶

CUSUMDetector threshold.

delta_std_ratio¶

The mean delta have to larger than this parameter times std of the data to be consider as a change.

magnitude_quantile¶

See in CUSUMDetector.

magnitude_ratio¶

See in CUSUMDetector.

score_func¶

The score function to calculate the anomaly score.

remove_seasonality¶

If apply STL to remove seasonality.

fit_predict(data: kats.consts.TimeSeriesData, historical_data: Optional[kats.consts.TimeSeriesData] = None) → kats.detectors.detector_consts.AnomalyResponse[source]¶

This function combines fit and predict and return anomaly socre for data. It requires scan_window > step_window. The relationship between two consective cusum runs in the loop is shown as below:

>>> |---historical_window---|---scan_window---|
>>>                                           |-step_window-|
>>>               |---historical_window---|---scan_window---|

  • scan_window: the window size in seconds to detect change point

  • historical_window: the window size in seconds to provide historical data

  • step_window: the window size in seconds to specify the step size between two scans

Parameters
Returns

The anomaly response contains the anomaly socres.

predict(data: kats.consts.TimeSeriesData, historical_data: Optional[kats.consts.TimeSeriesData] = None) → kats.detectors.detector_consts.AnomalyResponse[source]¶

predict is not implemented

serialize() → bytes[source]¶

Retrun serilized model.

class kats.detectors.cusum_model.CusumScoreFunction(value)[source]¶

Bases: enum.Enum

An enumeration.

kats.detectors.cusum_model.change(data: kats.consts.TimeSeriesData, pre_mean: float, **kwargs: Any) → kats.consts.TimeSeriesData[source]¶

Calculate absolute change

Parameters

  • data – The data need to calculate the score

  • pre_mean – Baseline mean

kats.detectors.cusum_model.percentage_change(data: kats.consts.TimeSeriesData, pre_mean: float, **kwargs: Any) → kats.consts.TimeSeriesData[source]¶

Calculate percentage change absolute change / baseline change

Parameters

  • data – The data need to calculate the score

  • pre_mean – Baseline mean

kats.detectors.cusum_model.z_score(data: kats.consts.TimeSeriesData, pre_mean: float, pre_std: float) → kats.consts.TimeSeriesData[source]¶

Calculate z score: absolute change / std

Parameters

  • data – The data need to calculate the score

  • pre_mean – Baseline mean

  • pre_std – Baseline std