milia.anomaly.ensemble#

Detector ensembles: several detectors’ scores rescaled to a common range and combined.

Each member is fitted on the same training data. Its training anomaly scores fix a min-max rescaling that is then reused for every later query, so a calibration score and a query score stay on the same scale. The rescaled scores are combined by mean, max, median or average-of-maximum (Aggarwal and Sathe, 2015), implemented directly rather than through pyod or combo.

Module Attributes

DEFAULTS

The five-detector default ensemble, two parametric and three non-parametric.

FAMILIES

Detector families compared in the anomaly chapter.

Functions

combine(rescaled[, combiner, buckets, ...])

Combine rescaled scores into one score per row.

members([names])

Named, unfitted detectors for an ensemble.

rescale(scores, bounds)

Columnwise min-max rescaling with fixed, pre-fitted bounds.

scores(detectors, train, query)

Fit each detector on the training rows and score the query rows.

standardised(name, **settings)

A registered detector on features standardised with its training rows.

Classes

Ensemble([detectors, combiner, buckets, ...])

A combination of detectors, itself a detector.

milia.anomaly.ensemble.DEFAULTS: tuple[tuple[str, dict], ...] = (('mahalanobis', {}), ('kde', {'bandwidth': 1.0}), ('iforest', {}), ('lof', {}), ('ecod', {}))#

The five-detector default ensemble, two parametric and three non-parametric.

milia.anomaly.ensemble.FAMILIES: dict[str, tuple[str, ...]] = {'all': ('mahalanobis', 'kde', 'iforest', 'lof', 'ecod'), 'nonparametric': ('iforest', 'lof', 'ecod'), 'parametric': ('mahalanobis', 'kde')}#

Detector families compared in the anomaly chapter.

milia.anomaly.ensemble.standardised(name, **settings)#

A registered detector on features standardised with its training rows.

Standardisation gives every detector the same scale, so differences between detectors reflect their assumptions rather than the units of the features.

Parameters:
  • name (str) – Registered detector name.

  • **settings – The detector’s hyperparameters.

Return type:

Pipeline

Returns:

An unfitted pipeline whose score_samples is the detector’s (higher meaning more normal).

Examples

>>> model = standardised("lof", n_neighbors=5).fit(np.random.default_rng(0).normal(size=(50, 3)))
>>> model.score_samples(np.zeros((1, 3))).shape
(1,)
milia.anomaly.ensemble.members(names=None)#

Named, unfitted detectors for an ensemble.

Parameters:

names (Sequence[str] | None) – Registry names; the five DEFAULTS when omitted. KDE gets the default bandwidth of 1.

Return type:

list[tuple[str, BaseDetector]]

Returns:

(name, detector) pairs.

Examples

>>> [name for name, _ in members()]
['mahalanobis', 'kde', 'iforest', 'lof', 'ecod']
milia.anomaly.ensemble.rescale(scores, bounds)#

Columnwise min-max rescaling with fixed, pre-fitted bounds.

Bounds are fitted once on training scores and reused, so a calibration score and a query score stay on the same scale. A column with no spread maps to 0.

Parameters:
  • scores (ndarray) – Raw scores, shape (n, detectors).

  • bounds (ndarray) – (min, max) per detector, shape (detectors, 2).

Return type:

ndarray

Returns:

Rescaled scores, same shape.

Examples

>>> rescale(np.array([[1.0, 5.0]]), np.array([[0.0, 2.0], [1.0, 1.0]])).tolist()
[[0.5, 0.0]]
milia.anomaly.ensemble.combine(rescaled, combiner='mean', buckets=2, random_state=0)#

Combine rescaled scores into one score per row.

"mean", "max" and "median" reduce across detectors. "aom" (average of maximum; Aggarwal and Sathe, 2015) shuffles the detectors into buckets equal groups, takes the maximum within each and averages across them.

Parameters:
  • rescaled (ndarray) – Scores on [0, 1], shape (n, detectors).

  • combiner (Literal['mean', 'max', 'median', 'aom']) – "mean", "max", "median" or "aom".

  • buckets (int) – Groups for "aom".

  • random_state (int) – Seed of the "aom" shuffle.

Return type:

ndarray

Returns:

One combined score per row.

Raises:

ValueError – If the combiner is unknown, or the detectors cannot be split into equal buckets.

Examples

>>> combine(np.array([[0.2, 0.8]]), "mean").tolist(), combine(np.array([[0.2, 0.8]]), "max").tolist()
([0.5], [0.8])
milia.anomaly.ensemble.scores(detectors, train, query)#

Fit each detector on the training rows and score the query rows.

Parameters:
Return type:

dict[str, ndarray]

Returns:

Name to anomaly scores (higher = more anomalous).

Examples

>>> import numpy as np
>>> from milia import make
>>> rng = np.random.default_rng(0)
>>> train, query = rng.normal(size=(200, 2)), np.array([[0.0, 0.0], [8.0, 8.0]])
>>> out = scores(members(["ecod", "copod"]), train, query)
>>> sorted(out), bool(out["ecod"][1] > out["ecod"][0])
(['copod', 'ecod'], True)
class milia.anomaly.ensemble.Ensemble(detectors=None, combiner='mean', buckets=2, random_state=0, contamination=0.1)#

Bases: BaseDetector

A combination of detectors, itself a detector.

Parameters:
  • detectors (list[tuple[str, BaseDetector]] | None) – (name, detector) pairs; the five DEFAULTS when omitted.

  • combiner (Literal['mean', 'max', 'median', 'aom']) – "mean", "max", "median" or "aom".

  • buckets (int) – Groups for "aom".

  • random_state (int) – Seed for the "aom" shuffle.

  • contamination (float) – Expected share of outliers, used for the default threshold.

Variables:
  • detectors – The fitted members.

  • bounds – Rescaling bounds per member, shape (members, 2).

Examples

>>> import numpy as np
>>> rng = np.random.default_rng(0)
>>> train, cal = rng.normal(size=(200, 2)), rng.normal(size=(100, 2))
>>> model = Ensemble(detectors=members(["ecod", "iforest", "lof"]), combiner="max").fit(train).calibrate(cal)
>>> model.flag(np.array([[0.0, 0.0], [8.0, 8.0]])).tolist()
[False, True]
raw(X)#

Unscaled anomaly scores of every member.

Parameters:

X (ndarray) – Rows to score.

Return type:

ndarray

Returns:

Array of shape (n, members).