ChangepointDetector

This object can be used to detect changepoints in a time series using the CUSUMDetector.detector() and BOCPDetector.detector() functions from kats. See the helpful tutorial developed by the creators of Kats. The functions are left unadjusted in this object and are only adapted to interface with the Forecaster object from scalecast.

class src.scalecast.ChangepointDetector.ChangepointDetector(f)

Methods:

`DetectCPBOCPD`(**kwargs)	Detects changepoints using the BOCDPDetector.detector() function from kats.
`DetectCPCUSUM`(**kwargs)	Detects changepoints using the CUSUMDetector.detector() function from kats.
`DetectCPCUSUM_sliding`(historical_window, ...)	Detects multiple changepoints using the CUSUMDetector.detector() function from kats over a sliding window.
`WriteCPtoXvars`([f, future_dates, end])	Writes identified changepoints as variables to a Forecaster object.
`plot`()	Plots identified changepoints.

DetectCPBOCPD(**kwargs)

Detects changepoints using the BOCDPDetector.detector() function from kats. Docs: https://facebookresearch.github.io/Kats/api/kats.detectors.bocpd_model.html. Tutorial: https://github.com/facebookresearch/Kats/blob/main/tutorials/kats_202_detection.ipynb.

Parameters:: **kwargs – Passed to the function referenced above
Returns:: (list) A list of tuple of TimeSeriesChangePoint and CUSUMMetadata.

>>> from scalecast.ChangepointDetector import ChangepointDetector
>>> from scalecast.Forecaster import Forecaster
>>> import pandas_datareader as pdr
>>> df = pdr.get_data_fred('HOUSTNSA',start='1900-01-01',end='2021-06-01')
>>> f = Forecaster(y=df['HOUSTNSA'],current_dates=df.index)
>>> detector = ChangepointDetector(f)
>>> detector.DetectCPBOCPD()

DetectCPCUSUM(**kwargs)

Detects changepoints using the CUSUMDetector.detector() function from kats. This function assumes there is at most one increase change point and at most one decrease change point in the series. Use DetectCPCUSUM_sliding() or DetectCPBOCPD() to find multiple of each kind of changepoint. Saves output in the changepoints attribute. See https://facebookresearch.github.io/Kats/api/kats.detectors.cusum_detection.html.

Parameters:: **kwargs – Passed to the referenced kats function.
Returns:: (list) A list of tuple of TimeSeriesChangePoint and CUSUMMetadata.

>>> from scalecast.ChangepointDetector import ChangepointDetector
>>> from scalecast.Forecaster import Forecaster
>>> import pandas_datareader as pdr
>>> df = pdr.get_data_fred('HOUSTNSA',start='1900-01-01',end='2021-06-01')
>>> f = Forecaster(y=df['HOUSTNSA'],current_dates=df.index)
>>> detector = ChangepointDetector(f)
>>> detector.DetectCPCUSUM()

DetectCPCUSUM_sliding(historical_window, scan_window, step, **kwargs)

Detects multiple changepoints using the CUSUMDetector.detector() function from kats over a sliding window. This idea is taken from the kats example: https://github.com/facebookresearch/Kats/blob/main/tutorials/kats_202_detection.ipynb.

Parameters:

historical_window (int) – The number of periods to begin the initial search.
scan_window (int) – How far into the future to scan for changepoints after each step.
step (int) – How far to step forward after a scan.
**kwargs – Passed to the CUSUMDetector.detector() function. interest_window passed automatically based on the values passed to the other arguments in this function.

Returns:

(list) A list of tuple of TimeSeriesChangePoint and CUSUMMetadata.

>>> from scalecast.ChangepointDetector import ChangepointDetector
>>> from scalecast.Forecaster import Forecaster
>>> import pandas_datareader as pdr
>>> df = pdr.get_data_fred('HOUSTNSA',start='1900-01-01',end='2021-06-01')
>>> f = Forecaster(y=df['HOUSTNSA'],current_dates=df.index)
>>> detector = ChangepointDetector(f)
>>> detector.DetectCPCUSUM_sliding(20,10,5)

WriteCPtoXvars(f=None, future_dates=None, end=None)

Writes identified changepoints as variables to a Forecaster object.

Parameters:

f (Forecaster) – Optional. If you pass an object here, that object will receive the Xvars. Otherwise, it will pass to the copy of the object stored in the AnomalyDetector object when it was initialized. This Forecaster object is stored in the f attribute.
future_dates (int) – Optional. If you pass a future dates length here, it will write that many dates to the Forecaster object and future anomaly variables will be passed as arrays of 1s so that any algorithm you train will be able to use them into a future horizon.
end (None or 'auto') – Default None. If None, will use ‘2999-12-31’ as the end date for each identified changepoint. If “auto”, will use whatever changepoint end date identified by kats, but since this is usually the same value as the start date, the default behavior in this object is to use an indefinite end date (‘2999-12-31’).

Returns:

(Forecaster) An object with the Xvars written.

>>> from scalecast.ChangepointDetector import ChangepointDetector
>>> from scalecast.Forecaster import Forecaster
>>> import pandas_datareader as pdr
>>> df = pdr.get_data_fred('HOUSTNSA',start='1900-01-01',end='2021-06-01')
>>> f = Forecaster(y=df['HOUSTNSA'],current_dates=df.index)
>>> detector = ChangepointDetector(f)
>>> detector.DetectCPCUSUM()
>>> f = detector.WriteCPtoXvars(future_dates=12)

plot()

Plots identified changepoints.

>>> from scalecast.ChangepointDetector import ChangepointDetector
>>> from scalecast.Forecaster import Forecaster
>>> import matplotlib.pyplot as plt
>>> import pandas_datareader as pdr
>>> df = pdr.get_data_fred('HOUSTNSA',start='1900-01-01',end='2021-06-01')
>>> f = Forecaster(y=df['HOUSTNSA'],current_dates=df.index)
>>> detector = ChangepointDetector(f)
>>> detector.DetectCPCUSUM()
>>> detector.plot()
>>> plt.show()