Chronos

class dtaianomaly.anomaly_detection.Chronos(window_size: int | Literal['fft', 'acf', 'mwf', 'suss'], model_path: Literal['tiny', 'mini', 'small', 'base', 'large', 'bolt_tiny, bolt_mini', 'bolt_small', 'bolt_large'] = 'bolt_small', batch_size: int = 16, forecast_horizon: int = 1, do_fine_tuning: bool = False, fine_tune_kwargs: dict[str, any] | None = None, device: str = 'cpu')[source]

Detect anomalies in time series using Chronos [2].

Chronos is pre-trained time series foundation model for time series forecasting. By computing the difference between the forecasted values and the actual observations, Chronos is able to detecat anomalies in time series. Chronos first bins the incoming time series sequences to obtain a finite set of values, after which an encoder-decoder model is used to forecast the sequence. The network is trained with a cross-entropy loss, using a combination of real, synthetic and semi-synthetic data.

Parameters:

window_sizeint or str: The window size to use for extracting sliding windows from the time series. This value will be passed to compute_window_size().
model_path{‘tiny’, ‘mini’, ‘small’, ‘base’, ‘large’, ‘bolt_tiny’, ‘bolt_mini’, ‘bolt_small’, ‘bolt_large’}, default=’bolt_small’: The Chronos-model to use for forecasting.
batch_sizeint, default=16: The number of windows to feed simultaneously to Chronos, within a batch.
forecast_horizonint, default=1: The number of samples to forecast for each window.
do_fine_tuningbool, default=False: Whether to fine tune the model during fitting. If False, then the model will perform zero-shot forecasting.
fine_tune_kwargsdict, default=None: Additional arguments for finetuning Chronos. Check out https://auto.gluon.ai/dev/tutorials/timeseries/forecasting-model-zoo.html#autogluon.timeseries.models.ChronosModel for more information on the options.
devicestr, default=’cpu’: The device to use for running Chronos.

Attributes:

window_size_int: The effectively used window size for this anomaly detector
chronos_autogluon.timeseries.TimeSeriesPredictor: The Chronos model used for forecasting the time series

Warning

If you want to run Chronos, be sure to install the optional dependency chronos:

pip install dtaianomaly[chronos]

Notes

Chronos only handles univariate time series.

Examples

>>> from dtaianomaly.anomaly_detection import Chronos
>>> from dtaianomaly.data import demonstration_time_series
>>> x, y = demonstration_time_series()
>>> chronos = Chronos(10).fit(x)
>>> chronos.decision_function(x)
array([0.00027719, 0.00027719, 0.00027719, ..., 0.00058781, 0.02628242,
       0.00010728]...)

check_is_fitted() → None

Raise an error if this object is not fitted.

Check whether this object is fitted, and if it is not fitted, an exception is thrown.

Raises:

NotFittedError: If this object is not fitted.

decision_function(X: ndarray) → array

Compute anomaly scores.

Compute the anomaly scores for the given time series using this detector.

Parameters:

Xarray-like of shape (n_samples, n_attributes): Input time series.

Returns:

array-like of shape (n_samples): The computed anomaly scores.

fit(X: ndarray, y: ndarray = None, **kwargs) → BaseDetector

Fit this detector.

Fit this detector to the given data.

Parameters:

Xarray-like of shape (n_samples, n_attributes): Input time series.
yarray-like, default=None: Ground-truth information.
**kwargs: Additional parameters to be used to fit the anomaly detector.

Returns:

BaseDetector: Returns the instance itself.

is_fitted() → bool

Check whether this object is fitted.

Check whether all the attributes of this object that end with an underscore (‘_’) has been initialized.

Returns:

bool: True if and only if all the attributes of this object ending with ‘_’ are initialized.

predict_confidence(X: ndarray, X_train: ndarray = None, contamination: float = 0.05, decision_scores_given: bool = False)

Predict the confidence of the anomaly scores on the test given test data [26].

This method implements ExCeeD (Example-wise Confidence of anomaly Detectors) to estimate the confidence. ExCeed transforms the predicted decision scores to probability estimates using a Bayesian approach, which enables to assign a confidence score to each prediction which captures the uncertainty of the anomaly detector in that prediction.

Parameters:

Xarray-like of shape (n_samples, n_attributes): The test time series for which the confidence of anomaly scores should be predicted.
X_trainarray-like of shape (n_samples_train, n_attributes), default=None: The training time series, which can be used as reference. If X_train=None, the test set is used as reference set.
contaminationfloat, default=0.05: The (estimated) contamination rate for the data, i.e., the expected percentage of anomalies.
decision_scores_givenbool, default=False: Whether the given X and X_train represent time series data or decision scores. If decision_scores_given=False (default), then the given arrays are interpreted as time series. Otherwise, they are interpreted as decision scores, as computed by decision_function().

Returns:

array-like of shape (n_samples): The confidence of this anomaly detector in each prediction in the given test time series.

predict_proba(X: ndarray) → ndarray

Predict anomaly probabilities.

Estimate the probability of a sample of X being anomalous, based on the anomaly scores obtained from decision_function by rescaling them to the range of [0, 1] via min-max scaling.

Parameters:

Xarray-like of shape (n_samples, n_attributes): Input time series.

Returns:

array-like of shape (n_samples): 1D array with the same length as X, with values in the interval [0, 1], in which a higher value implies that the instance is more likely to be anomalous.

Raises:

ValueError: If scores is not a valid array.
ValueError: If the prediction scores from ‘decision_function’ are constant, but not in the interval [0, 1], because these values can not unambiguously be transformed to an anomaly probability.

requires_fitting() → bool

Check whether this object requires fitting.

Check whether any of the attributes of this object ends with an underscore (‘_’), which indicates that the attribute is set when the object is fitted. Note that this method does not check whether the object is fitted, i.e., whether the attributes have been set.

Returns:

bool: True if and only if this object has attributes that end with ‘_’.

save(path: str | Path) → None

Save this detector.

Save detector to disk as a pickle file with extension .dtai. If the given path consists of multiple subdirectories, then the not existing subdirectories are created.

Parameters:

pathstr or Path: Location where to store the detector.