Skip to content

Reconstruction Models API

OnlineAutoencoderEnsemble is NumPy-backed and part of the base installation. Autoencoder, Architecture, and VanillaAutoencoder require aberrant[dl].

OnlineAutoencoderEnsemble

Python
OnlineAutoencoderEnsemble(max_ae_size: int = 10, feature_map_grace: int = 5000, ad_grace: int = 50000, learning_rate: float = 0.1, hidden_ratio: float = 0.75, adaptive_after_warmup: bool = False, seed: int | None = None)

Bases: BaseModel

Online anomaly detector using an ensemble of lightweight autoencoders.

The detector first learns feature groups from streaming correlations, then trains an ensemble of small autoencoders plus an output autoencoder. This implementation uses raw inputs, greedy correlation grouping, and simple NumPy autoencoders. The authors' implementation includes its own feature mapper and normalized denoising autoencoders, so scores are not expected to match it exactly.

The model is stateful and sample-wise: - learn_one updates model state with a single sample. - score_one computes one anomaly score without mutating state.

Warm-up phases: - feature_map_warmup: build feature groups from correlations. - detector_warmup: train ensemble and output autoencoders. - ready: score samples; optionally keep adapting if enabled.

Parameters:

Name Type Description Default
max_ae_size int

Maximum number of input features assigned to one ensemble autoencoder.

 10
feature_map_grace int

Number of learned samples used to estimate feature correlations before the autoencoder ensemble is created.

 5000
ad_grace int

Number of subsequent learned samples used to train the ensemble and output autoencoder before scoring begins. A value of zero trains once on the feature-map transition sample and becomes ready immediately.

 50000
learning_rate float

Positive stochastic-gradient step size used by every NumPy autoencoder.

 0.1
hidden_ratio float

Hidden-layer width as a fraction of input width, in (0, 1]. Width is rounded up and, for inputs wider than one, capped below the input width.

 0.75
adaptive_after_warmup bool

Continue training on calls to learn_one after the model reaches the ready phase.

 False
seed int | None

Seed for model-local NumPy generators. None selects nondeterministic generator initialization.

 None
References

Mirsky, Y., Doitshman, T., Elovici, Y., & Shabtai, A. (2018). Kitsune: An Ensemble of Autoencoders for Online Network Intrusion Detection. NDSS 2018. Original KitNET implementation: https://github.com/ymirsky/KitNET-py

phase property

Python
phase: str

Current warm-up/training phase.

is_ready property

Python
is_ready: bool

Whether the model is ready to produce non-zero anomaly scores.

reset

Python
reset() -> None

Public state reset.

learn_one

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

Update model state with a single sample.

score_one

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

Compute anomaly score for a sample without mutating model state.

Optional PyTorch model

Autoencoder

Python
Autoencoder(model: Architecture, optimizer: Optimizer, criterion: AutoencoderLoss)

Bases: BaseModel

Online autoencoder for anomaly detection.

This model trains an autoencoder architecture incrementally on data points and uses reconstruction error as an anomaly score.

Parameters:

Name Type Description Default
model Architecture

The neural network architecture (encoder-decoder).

 required
optimizer Optimizer

PyTorch optimizer for training.

 required
criterion AutoencoderLoss

Loss function for reconstruction error.

 required

Examples:

Python
from torch import nn, optim

from aberrant.model.deep import Autoencoder
from aberrant.utils.deep.architecture import VanillaAutoencoder

architecture = VanillaAutoencoder(input_size=10)
autoencoder = Autoencoder(
    model=architecture,
    optimizer=optim.Adam(architecture.parameters()),
    criterion=nn.MSELoss(),
)

learn_one

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

Update the autoencoder with a single data point.

Parameters:

Name Type Description Default
x dict[str, float]

Feature dictionary with string keys and float values.

 required

score_one

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

Compute anomaly score for a single data point.

Parameters:

Name Type Description Default
x dict[str, float]

Feature dictionary with string keys and float values.

 required

Returns:

Type Description
float

Reconstruction error as anomaly score.

Architecture

Python
Architecture(device: device | None = None)

Bases: ABC, Module

Abstract base class for defining neural network architectures.

This class ensures that any neural network architecture can be plugged into online anomaly detection models. It provides a consistent interface and device handling capabilities.

Subclasses must implement the forward and input_size methods.

Initialize the architecture.

Parameters:

Name Type Description Default
device device | None

The device to run the model on. If None, uses CPU.

 None

input_size abstractmethod property

Python
input_size: int

The expected input size for the network.

Returns:

Type Description
int

Number of input features.

forward abstractmethod

Python
forward(x: Tensor) -> Tensor

Forward pass through the network.

Parameters:

Name Type Description Default
x Tensor

Input tensor.

 required

Returns:

Type Description
Tensor

Output tensor.

make_torch_generator staticmethod

Python
make_torch_generator(seed: int | None, device: device | str = 'cpu') -> Generator

Create an independently seeded, model-owned generator.

VanillaAutoencoder

Python
VanillaAutoencoder(input_size: int, seed: int | None = None, device: device | None = None)

Bases: Architecture

Simple feedforward autoencoder with ReLU activations.

Architecture: input -> 64 -> 32 -> 16 -> 32 -> 64 -> output

Parameters:

Name Type Description Default
input_size int

Number of input features.

 required
seed int | None

Random seed for reproducibility (optional).

 None

input_size property

Python
input_size: int

Number of input features.

forward

Python
forward(x: Tensor) -> Tensor

Forward pass through encoder and decoder.