Back to models
Detector

TSPulseAnomalyDetector

API referenceSource
Multivariate

Anomaly detector wrapping IBM TSPulse via granite-tsfm.

Quickstart

python
from sktime.detection.tspulse import TSPulseAnomalyDetector

estimator = TSPulseAnomalyDetector(model_path: str='ibm-granite/granite-timeseries-tspulse-r1', revision: str='main', mask_type: str='user', prediction_mode=None, aggregation_length: int=64, aggr_function: str='max', smoothing_length: int=8, least_significant_scale: float=0.01, least_significant_score: float=0.1, batch_size: int=128, predictive_score_smoothing: bool=False, anomaly_threshold: float | None=0.6, anomaly_percentile: float | None=None, config: dict | None=None)

Parameters(14)

model_pathstr, default=”ibm-granite/granite-timeseries-tspulse-r1”
Hugging Face model id or local path.
revisionstr, default=”main”
Model revision on the Hugging Face Hub.
mask_typestr, default=”user”

Patch-masking strategy during reconstruction. "user" applies masking from an optional past_observed_mask (the default for anomaly scoring). Other supported values include "block", "hybrid", "var_hybrid", and "random".

prediction_modestr or list of str, optional

Score type(s) computed on each context window before they are merged. Supported values:

  • "time": mean squared error between the input and the model’s time-domain reconstruction over the last aggregation_length points of the context window.

  • "fft": same error using the reconstruction from the frequency (FFT) branch.

  • "forecast": mean squared error between the next observed value and the model’s one-step forecast.

When None (default), uses ["time", "fft"]. A single string is wrapped in a one-element list. With several types, each produces its own score sequence; see smoothing_length and aggr_function.

aggregation_lengthint, default=64

Length of the context suffix used for patchwise stitched reconstruction when scoring with "time" or "fft". Also controls boundary padding when scores are aligned back to the full series length.

aggr_functionstr, default=”max”

How to merge score sequences from different entries in prediction_mode at each time point. One of "max", "min", or "mean".

smoothing_lengthint, default=8

Moving-average window applied to each score sequence listed in prediction_mode after boundary alignment, before aggr_function merges them. One-step "forecast" scores skip this smoothing unless predictive_score_smoothing is True.

least_significant_scalefloat, default=0.01

Value in (0, 1). Sets a variance-based floor on raw errors before scores are rescaled: deviations smaller than this fraction of the squared differences in the (standardized) input are treated as insignificant.

least_significant_scorefloat, default=0.1

Minimum scale factor applied when normalizing significant errors to the [0, 1] score range returned by the pipeline.

batch_sizeint, default=128
Batch size for pipeline inference.
predictive_score_smoothingbool, default=False

If True, apply smoothing_length smoothing to "forecast" scores as well; if False, forecast scores are left unsmoothed.

anomaly_thresholdfloat, optional, default=0.6

Scores strictly above this value are flagged as anomalies in predict. If None, anomaly_percentile is used instead.

anomaly_percentilefloat, optional, default=None

Percentile of the score vector on X used as the detection threshold when anomaly_threshold is None. Exactly one of anomaly_threshold and anomaly_percentile must be set.

configdict, optional, default=None

Extra keyword arguments forwarded to TSPulseForReconstruction.from_pretrained.

Any key you supply overrides the built-in default for that key, except for num_input_channels, which is always set from the number of columns in X at fit time.

If config is None, the following default override is applied:

  • ignore_mismatched_sizes=True: allows loading when channel or head shapes differ from the checkpoint

Other commonly useful overrides (see TSPulseConfig in granite-tsfm):

  • context_length: history length per window (checkpoint default often 512 for r1 models)

  • patch_length / patch_stride: patch size and stride for the encoder

  • decoder_mode: channel mixing in the decoder ("mix_channel" or "common_channel")

  • scaling: input normalization ("revin", "mean", "std", or None)

  • mask_ratio: fraction of patches masked when mask_type is not "user"

  • fft_time_consistent_masking: if True, masked series is used for the FFT branch during training-style masking

  • reconstruction_type: "patchwise" or "full" reconstruction

  • prediction_length: horizon for the forecast head when using prediction_mode="forecast"

Examples

>>> from sktime.detection.tspulse import TSPulseAnomalyDetector
>>> import pandas as pd
>>> import numpy as np
>>> idx = pd. date_range ("2020-01-01", periods = 200, freq = "D")
>>> X = pd. DataFrame (np. random. randn (200, 1), index = idx, columns = ["value" ])
>>> detector = TSPulseAnomalyDetector ()
>>> detector. fit (X)
>>> detector. predict (X)
>>> detector. predict_scores (X)

References

  1. [1 ] https://github.com/ibm-granite/granite-tsfm/blob/main/notebooks/hfdemo/tspulse_anomaly_detection.ipynb [2 ] https://arxiv.org/abs/2505.13033