MODULE REFERENCE

timeseries

anomx.detection.scorers.timeseries

Native time-series residual, distribution, and learned anomaly scorers.

Scores preserve the time axis and component names. Window scorers learn only from explicit training data. Their default trailing windows are causal; setting window_agg=True averages all windows covering a point and is therefore an offline operation that can use later observations.

AnomalyScorer

AnomalyScorer

Bases: Scorer

TimeSeries scorer contract, distinct from legacy scored-table components.

score consumes observations or residuals. score_from_prediction aligns actual and predicted timestamps, then scores their absolute residuals unless a concrete scorer specifies another transformation. All methods accept one series or equal-length sequences of series.

Members

is_trainableattribute
capabilitiesattribute
capabilities = ComponentCapabilities(supports_sequences=True, supports_unordered_samples=False, requires_training=False)
scoremethod
score(series: TimeSeries | Sequence[TimeSeries]) -> TimeSeries | list[TimeSeries]
Signature parameters
ParameterTypeDefault
seriesTimeSeries | Sequence[TimeSeries]required

Returns TimeSeries | list[TimeSeries]

score_from_predictionmethod
score_from_prediction(actual_series: TimeSeries | Sequence[TimeSeries], pred_series: TimeSeries | Sequence[TimeSeries]) -> TimeSeries | list[TimeSeries]
Signature parameters
ParameterTypeDefault
actual_seriesTimeSeries | Sequence[TimeSeries]required
pred_seriesTimeSeries | Sequence[TimeSeries]required

Returns TimeSeries | list[TimeSeries]

CauchyNLLScorer

CauchyNLLScorer(window: int = 1, min_scale: float = 1e-08)

Bases: NLLScorer

Cauchy negative log likelihood using robust median and half-IQR estimates.

Signature parameters
ParameterTypeDefault
windowint1
min_scalefloat1e-08

Members

component_keyattribute
component_key = 'cauchy_nll'

DifferenceScorer

DifferenceScorer

Bases: AnomalyScorer

Signed per-component difference actual - predicted (no fitting).

Members

component_keyattribute
component_key = 'difference'
scorer_familyattribute

ExponentialNLLScorer

ExponentialNLLScorer(window: int = 1, min_scale: float = 1e-08)

Bases: NLLScorer

Exponential negative log likelihood for nonnegative prediction samples.

Signature parameters
ParameterTypeDefault
windowint1
min_scalefloat1e-08

Members

component_keyattribute
component_key = 'exponential_nll'

GammaNLLScorer

GammaNLLScorer(window: int = 1, min_scale: float = 1e-08)

Bases: NLLScorer

Gamma negative log likelihood with method-of-moments sample parameters.

Signature parameters
ParameterTypeDefault
windowint1
min_scalefloat1e-08

Members

component_keyattribute
component_key = 'gamma_nll'

GaussianNLLScorer

GaussianNLLScorer(window: int = 1, min_scale: float = 1e-08)

Bases: NLLScorer

Gaussian negative log likelihood using sample mean and standard deviation.

Signature parameters
ParameterTypeDefault
windowint1
min_scalefloat1e-08

Members

component_keyattribute
component_key = 'gaussian_nll'

KMeansScorer

KMeansScorer(window: int = 1, k: int = 8, component_wise: bool = False, window_agg: bool = False, **kwargs: object)

Bases: WindowedAnomalyScorer

Euclidean distance to the closest fitted normal-window cluster center.

Signature parameters
ParameterTypeDefault
windowint1
kint8
component_wiseboolFalse
window_aggboolFalse
**kwargsobject—

Members

component_keyattribute
scorer_familyattribute
scorer_family = 'representation'

LaplaceNLLScorer

LaplaceNLLScorer(window: int = 1, min_scale: float = 1e-08)

Bases: NLLScorer

Laplace negative log likelihood using sample median and absolute deviation.

Signature parameters
ParameterTypeDefault
windowint1
min_scalefloat1e-08

Members

component_keyattribute
component_key = 'laplace_nll'

NLLScorer

NLLScorer(window: int = 1, min_scale: float = 1e-08)

Bases: AnomalyScorer

Negative log likelihood fitted separately to prediction samples per point.

Requires deterministic observations and stochastic predictions (at least two samples). Degenerate scales are floored by min_scale; observations outside a distribution's support receive the finite cap -log(tiny). window averages successive point scores over a causal trailing window.

Signature parameters
ParameterTypeDefault
windowint1
min_scalefloat1e-08

Members

scorer_familyattribute
scorer_family = 'likelihood'
score_from_predictionmethod
score_from_prediction(actual_series: SeriesLike, pred_series: SeriesLike) -> TimeSeries | list[TimeSeries]
Signature parameters
ParameterTypeDefault
actual_seriesSeriesLikerequired
pred_seriesSeriesLikerequired

Returns TimeSeries | list[TimeSeries]

NormScorer

NormScorer(ord: float = 2, component_wise: bool = False)

Bases: AnomalyScorer

Absolute component residuals or their vector norm at each timestamp.

component_wise=True returns one absolute score per component. Otherwise ord chooses the numpy vector norm (default Euclidean).

Signature parameters
ParameterTypeDefault
ordfloat2
component_wiseboolFalse

Members

component_keyattribute
scorer_familyattribute
scorer_family = 'residual'

OutlierEstimator

OutlierEstimator

Bases: Protocol

Structural contract accepted by the optional PyOD adapter.

Members

fitmethod
fit(values: np.ndarray) -> Self
Signature parameters
ParameterTypeDefault
valuesnp.ndarrayrequired

Returns Self

decision_functionmethod
decision_function(values: np.ndarray) -> np.ndarray
Signature parameters
ParameterTypeDefault
valuesnp.ndarrayrequired

Returns np.ndarray

PoissonNLLScorer

PoissonNLLScorer(window: int = 1, min_scale: float = 1e-08)

Bases: NLLScorer

Poisson negative log likelihood for nonnegative integer observations.

Signature parameters
ParameterTypeDefault
windowint1
min_scalefloat1e-08

Members

component_keyattribute
component_key = 'poisson_nll'

PyODScorer

PyODScorer(model: OutlierEstimator, window: int = 1, component_wise: bool = False, window_agg: bool = False)

Bases: WindowedAnomalyScorer

Adapt a PyOD-compatible estimator's fit/decision_function to windows.

model must implement fit(X) and decision_function(X) with larger values meaning more anomalous. A deep copy is fitted per component so that models never share fitted state. Import/install PyOD only when choosing a PyOD model; this adapter itself has no PyOD dependency.

Signature parameters
ParameterTypeDefault
modelOutlierEstimatorrequired
windowint1
component_wiseboolFalse
window_aggboolFalse

Members

component_keyattribute
component_discoverableattribute
component_discoverable = False
scorer_familyattribute
scorer_family = 'representation'

WassersteinScorer

WassersteinScorer(window: int = 10, component_wise: bool = False, window_agg: bool = False)

Bases: WindowedAnomalyScorer

One-dimensional Wasserstein distance from each window to training values.

Components are flattened into one empirical distribution unless component_wise=True. This is not multivariate optimal transport.

Signature parameters
ParameterTypeDefault
windowint10
component_wiseboolFalse
window_aggboolFalse

Members

component_keyattribute
component_key = 'wasserstein'
scorer_familyattribute
scorer_family = 'direct_data'
fitmethod
fit(series: TimeSeries | Sequence[TimeSeries]) -> WassersteinScorer
Signature parameters
ParameterTypeDefault
seriesTimeSeries | Sequence[TimeSeries]required

Returns WassersteinScorer

WindowedAnomalyScorer

WindowedAnomalyScorer(window: int = 1, component_wise: bool = False, window_agg: bool = False)

Bases: AnomalyScorer

Fit and score sliding windows without crossing series boundaries.

Signature parameters
ParameterTypeDefault
windowint1
component_wiseboolFalse
window_aggboolFalse

Members

is_trainableattribute
capabilitiesattribute
capabilities = ComponentCapabilities(supports_sequences=True, supports_unordered_samples=False, requires_training=True)
fitmethod
fit(series: TimeSeries | Sequence[TimeSeries]) -> WindowedAnomalyScorer

Learn normal windows from one or more independent training series.

Signature parameters
ParameterTypeDefault
seriesTimeSeries | Sequence[TimeSeries]required

Returns WindowedAnomalyScorer

fit_from_predictionmethod
fit_from_prediction(actual_series: SeriesLike, pred_series: SeriesLike) -> WindowedAnomalyScorer

Learn the distribution of absolute training prediction errors.

Signature parameters
ParameterTypeDefault
actual_seriesSeriesLikerequired
pred_seriesSeriesLikerequired

Returns WindowedAnomalyScorer

fit_scoremethod
fit_score(series: SeriesLike) -> TimeSeries | list[TimeSeries]

Fit and score the same series (use separate validation data for evaluation).

Signature parameters
ParameterTypeDefault
seriesSeriesLikerequired

Returns TimeSeries | list[TimeSeries]