Skip to content

Statistical Models API¶

Univariate models score the candidate-induced change in one moving statistic. Unless otherwise stated, abs_diff=True returns the magnitude and abs_diff=False preserves direction.

All univariate models share these constructor parameters unless their API signature adds another one:

Parameter	Meaning
`window_size`	Maximum number of learned values retained. It must be positive.
`key`	Required feature name. If omitted, the first learned sample locks the model to its sole feature name. Every sample must contain exactly that one feature.
`abs_diff`	Return the absolute candidate-induced change when `True`; preserve its sign when `False`.

MovingQuantile.quantile is a probability in the closed interval [0, 1] and uses linear interpolation. MovingGeometricAverage accepts only positive values when scoring and ignores non-positive values while learning. Its absoluteValues=False mode computes the geometric mean of the retained values; despite the inherited parameter name, absoluteValues=True instead computes the geometric mean of successive ratios.

Univariate¶

MovingAverage ¶

Python

MovingAverage(window_size: int, key: str | None = None, abs_diff: bool = True)

Bases: _BaseMovingUnivariate

Score the change in arithmetic mean after adding a candidate value.

MovingHarmonicAverage ¶

Python

MovingHarmonicAverage(window_size: int, key: str | None = None, abs_diff: bool = True)

Bases: _BaseMovingUnivariate

Score harmonic-mean change, ignoring zero values during learning.

MovingGeometricAverage ¶

Python

MovingGeometricAverage(window_size: int, key: str | None = None, absoluteValues: bool = False, abs_diff: bool = True)

Bases: _BaseMovingUnivariate

Score geometric-mean changes for values or successive growth factors.

MovingMedian ¶

Python

MovingMedian(window_size: int, key: str | None = None, abs_diff: bool = True)

Bases: _BaseMovingUnivariate

Score the change in median after adding a candidate value.

MovingQuantile ¶

Python

MovingQuantile(window_size: int, key: str | None = None, quantile: float = 0.5, abs_diff: bool = True)

Bases: _BaseMovingUnivariate

Score the change in a configured linearly interpolated quantile.

MovingVariance ¶

Python

MovingVariance(window_size: int, key: str | None = None, abs_diff: bool = True)

Bases: _BaseMovingUnivariate

Score the change in population variance.

MovingInterquartileRange ¶

Python

MovingInterquartileRange(window_size: int, key: str | None = None, abs_diff: bool = True)

Bases: _BaseMovingUnivariate

Score the change in linearly interpolated interquartile range.

MovingAverageAbsoluteDeviation ¶

Python

MovingAverageAbsoluteDeviation(window_size: int, key: str | None = None, abs_diff: bool = True)

Bases: _BaseMovingUnivariate

Score the change in mean absolute deviation from the mean.

MovingKurtosis ¶

Python

MovingKurtosis(window_size: int, key: str | None = None, abs_diff: bool = True)

Bases: _BaseMovingUnivariate

Score the change in Pearson kurtosis.

MovingSkewness ¶

Python

MovingSkewness(window_size: int, key: str | None = None, abs_diff: bool = True)

Bases: _BaseMovingUnivariate

Score the change in population skewness.

Bivariate and multivariate¶

MovingCovariance ¶

Python

MovingCovariance(window_size: int, bias: bool = True, keys: list[str] | None = None, abs_diff: bool = True)

Bases: BaseModel

Moving covariance anomaly detection model.

Calculates the difference between the covariance of a window with a new value and the covariance of the current window. Designed for bivariate data streams.

Parameters:

Name	Type	Description	Default
`window_size`	`int`	Number of recent values to consider.	required
`bias`	`bool`	If False, applies Bessel correction (ddof=1).	`True`
`keys`	`list[str] \| None`	Feature names for the two variables. If None, uses first learned keys.	`None`
`abs_diff`	`bool`	If True, returns absolute difference.	`True`

Raises:

Type	Description
`ValueError`	If window_size is not positive.

Examples:

Python

from aberrant.model.stat import MovingCovariance

model = MovingCovariance(window_size=10)
model.learn_one({"x": 1.0, "y": 2.0})
score = model.score_one({"x": 1.5, "y": 2.5})

Initialize the moving covariance model.

learn_one ¶

Python

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

Update the model with a single data point.

Parameters:

Name	Type	Description	Default
`x`	`dict[str, float]`	Dictionary with exactly two key-value pairs.	required

Raises:

Type	Description
`ValueError`	If input doesn't contain exactly two features.

score_one ¶

Python

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

Compute anomaly score based on covariance change.

Calculates covariance(window + x) - covariance(window).

Parameters:

Name	Type	Description	Default
`x`	`dict[str, float]`	Data point to score.	required

Returns:

Type	Description
`float`	Covariance difference. Returns 0.0 if insufficient data.

MovingCorrelationCoefficient ¶

Python

MovingCorrelationCoefficient(window_size: int, bias: bool = True, keys: list[str] | None = None, abs_diff: bool = True)

Bases: BaseModel

Score the candidate-induced change in bivariate Pearson correlation.

The detector compares the correlation of the retained two-feature window with the correlation after temporarily appending the candidate. It returns the absolute change by default; set abs_diff=False to preserve its sign. Windows with fewer than two paired values have correlation 0.0.

Parameters:

Name	Type	Description	Default
`window_size`	`int`	Maximum number of recent paired observations to retain.	required
`bias`	`bool`	Use population normalization when true and sample normalization when false. The normalization cancels in Pearson correlation but is also applied consistently to covariance and standard deviations.	`True`
`keys`	`list[str] \| None`	Explicit names for the two features. If omitted, the first successfully learned mapping establishes a sorted schema.	`None`
`abs_diff`	`bool`	Return the magnitude of the change when true.	`True`

Initialize the bounded bivariate window.

learn_one ¶

Python

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

Append one validated, finite bivariate observation.

Parameters:

Name	Type	Description	Default
`x`	`dict[str, float]`	Mapping containing exactly the established two feature names.	required

Raises:

Type	Description
`ValueError`	If values are invalid or the feature schema differs.

score_one ¶

Python

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

Return the correlation change induced by a candidate observation.

Parameters:

Name	Type	Description	Default
`x`	`dict[str, float]`	Candidate with exactly the established two feature names.	required

Returns:

Type	Description
`float`	Absolute or signed correlation difference according to `abs_diff`.

MovingMahalanobisDistance ¶

Python

MovingMahalanobisDistance(window_size: int, bias: bool = True, keys: list[str] | None = None)

Bases: BaseModel

Score squared Mahalanobis distance from a recent reference window.

The score uses the retained observations' feature mean and covariance matrix. It is 0.0 until three observations have been learned. A small, scale-aware diagonal term is added when the covariance matrix is singular or numerically ill-conditioned.

Parameters:

Name	Type	Description	Default
`window_size`	`int`	Maximum number of recent observations to retain.	required
`bias`	`bool`	Pass population normalization to NumPy covariance when true; use sample normalization when false.	`True`
`keys`	`list[str] \| None`	Explicit feature order. If omitted, the first successfully learned mapping establishes a sorted schema.	`None`

Initialize the bounded multivariate window.

learn_one ¶

Python

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

Append one validated, finite observation.

Parameters:

Name	Type	Description	Default
`x`	`dict[str, float]`	Feature mapping matching the established schema.	required

score_one ¶

Python

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

Calculate squared Mahalanobis distance to the window mean.

Parameters:

Name	Type	Description	Default
`x`	`dict[str, float]`	Candidate feature mapping; it is not appended by this method.	required

Returns:

Type	Description
`float`	Squared Mahalanobis distance, or `0.0` before three reference
`float`	observations exist.