Skip to content

Time-Series Models API

XLagDAMP

Python
XLagDAMP(subsequence_length: int, x_lag: int | None = None, start_index: int | None = None, eps: float = 1e-12)

Bases: BaseModel

Pure-online X-Lag Amnesic Discord Aware Matrix Profile detector.

Each event supplies one scalar time-series value. Once enough history is available, the model scores the subsequence ending at the current event by its z-normalized Euclidean distance to its nearest preceding subsequence. Higher scores indicate stronger left-discord candidates.

This implementation follows the authors' DAMP_X_Lag_Amnesic.m source:

  • backward processing only (lookahead=0), the authors' pure-online mode,
  • MASS_V2 distance profiles with population standard deviations,
  • iterative doubling starting at 2^nextpow2(8 * subsequence_length),
  • best-so-far early abandoning,
  • exact search over at most the most recent x_lag values.

X-Lag amnesia bounds both memory and worst-case search history. As in the reference algorithm, early-abandoned scores are approximate: they are bounded by the exact left-discord score and the current best-so-far score. The highest peaks are the meaningful discord candidates.

Parameters:

Name Type Description Default
subsequence_length int

Number of consecutive values in each subsequence.

 required
x_lag int | None

Maximum number of values searched backward. Defaults to the authors' 16 * subsequence_length.

 None
start_index int | None

One-based subsequence start index at which processing begins. Defaults to the authors' recommendation of at least four cycles, 4 * subsequence_length.

 None
eps float

Numerical threshold used to reject constant subsequences.

 1e-12
Notes
  • Input must contain exactly one consistently named numeric feature.
  • Scores are 0.0 before start_index is reached.
  • Constant subsequences are rejected, matching the reference implementation's input restriction.
  • State is bounded by x_lag + subsequence_length - 1 learned values.
References

Lu, Y., Wu, R., Mueen, A., Zuluaga, M. A., & Keogh, E. (2022). Matrix Profile XXIV: Scaling Time Series Anomaly Detection to Trillions of Datapoints and Ultra-fast Arriving Data Streams. https://doi.org/10.1145/3534678.3539271

Original authors' implementation and documentation: https://sites.google.com/view/discord-aware-matrix-profile/documentation

n_samples_seen property

Python
n_samples_seen: int

Number of values processed through learn_one.

n_history property

Python
n_history: int

Number of learned values retained in bounded history.

n_subsequences_processed property

Python
n_subsequences_processed: int

Number of subsequences processed after warmup.

best_score property

Python
best_score: float

Highest exact left-discord score observed so far.

last_score property

Python
last_score: float

Score computed during the most recent learn_one call.

is_ready property

Python
is_ready: bool

Whether the next event starts a processable subsequence.

reset

Python
reset() -> None

Reset learned state while preserving hyperparameters.

learn_one

Python
learn_one(x: dict[str, float]) -> None

Process one value and update the online DAMP state.

score_one

Python
score_one(x: dict[str, float]) -> float

Score the subsequence ending at this value without mutating state.