Transform API¶

Transformers expose incremental learning and one-event mapping. Pipeline learning applies their post-update transform; direct transform_one calls do not learn.

Preprocessing¶

FeatureSchemaGuard ¶

Python

FeatureSchemaGuard(features: Sequence[str] | None = None, *, sort_features: bool = True)

Bases: BaseTransformer

Validate finite numeric values and a stable set of feature names.

Supply features to enforce an application schema from the first event. If omitted, the first successfully learned event establishes the schema. The transformer preserves feature names and values while returning them in the established order.

Parameters:

Name	Type	Description	Default
`features`	`Sequence[str] \| None`	Expected feature names, or `None` to learn them from the first event.	`None`
`sort_features`	`bool`	Sort names when learning a schema from the first event.	`True`

feature_names `property` ¶

Python

feature_names: tuple[str, ...] | None

Return the configured or learned feature order.

learn_one ¶

Python

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

Validate an event and commit its schema after successful validation.

transform_one ¶

Python

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

Validate and return an ordered, float-valued copy of an event.

reset ¶

Python

reset() -> None

Forget a learned schema while preserving constructor configuration.

MinMaxScaler ¶

Python

MinMaxScaler(feature_range: tuple[float, float] = (0, 1))

Bases: BaseTransformer

Min-max scaler for normalizing features to a specified range.

Scales each feature linearly to a target range, typically [0, 1]. This scaling is useful for algorithms that are sensitive to the scale of input features.

Parameters:

Name	Type	Description	Default
`feature_range`	`tuple[float, float]`	Target range for scaled features.	`(0, 1)`

Examples:

Python

from aberrant.transform.preprocessing import MinMaxScaler

scaler = MinMaxScaler(feature_range=(0, 1))
scaler.learn_one({"x": 5.0, "y": 10.0})
transformed = scaler.transform_one({"x": 3.0, "y": 8.0})

Initialize the MinMaxScaler.

Parameters:

Name	Type	Description	Default
`feature_range`	`tuple[float, float]`	The desired range of transformed features (default is (0, 1)).	`(0, 1)`

learn_one ¶

Python

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

Update the min and max values for each feature in the input data.

Parameters:

Name	Type	Description	Default
`x`	`dict[str, float]`	A dictionary of feature-value pairs.	required

transform_one ¶

Python

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

Scale the input data to the specified feature range.

Parameters:

Name	Type	Description	Default
`x`	`dict[str, float]`	A dictionary of feature-value pairs.	required

Returns:

Type	Description
`dict[str, float]`	The scaled feature-value pairs.

Raises:

Type	Description
`ValueError`	If feature hasn't been seen during learning.

StandardScaler ¶

Python

StandardScaler(with_std: bool = True)

Bases: BaseTransformer

Standard scaler for normalizing features using z-score normalization.

Transforms features to have zero mean and unit variance (when with_std=True). This is useful for algorithms that assume features are normally distributed and on similar scales.

Parameters:

Name	Type	Description	Default
`with_std`	`bool`	Whether to scale to unit variance.	`True`

Examples:

Python

from aberrant.transform.preprocessing import StandardScaler

scaler = StandardScaler()
scaler.learn_one({"x": 5.0, "y": 10.0})
transformed = scaler.transform_one({"x": 3.0, "y": 8.0})

Initialize the StandardScaler.

Parameters:

Name	Type	Description	Default
`with_std`	`bool`	Whether normalization should be divided by standard deviation.	`True`

learn_one ¶

Python

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

Update the mean and standard deviation for each feature incrementally.

Uses Welford's online algorithm for numerical stability.

Parameters:

Name	Type	Description	Default
`x`	`dict[str, float]`	A dictionary of feature-value pairs.	required

transform_one ¶

Python

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

Transform input data to z-scores (standard scores).

Parameters:

Name	Type	Description	Default
`x`	`dict[str, float]`	A dictionary of feature-value pairs.	required

Returns:

Type	Description
`dict[str, float]`	The standardized feature-value pairs.

Raises:

Type	Description
`ValueError`	If feature hasn't been seen during learning.

Projection¶

IncrementalPCA ¶

Python

IncrementalPCA(n_components: int, n0: int = 50, keys: list[str] | None = None, tol: float = 1e-07, forgetting_factor: float | None = None)

Bases: BaseTransformer

Incremental Principal Component Analysis for online dimensionality reduction.

Implements an uncentered online PCA algorithm that can process data points one at a time, maintaining principal components without storing all historical data. Inputs are projected around the origin; center or standardize them upstream when conventional mean-centered PCA semantics are required.

Parameters:

Name	Type	Description	Default
`n_components`	`int`	Number of principal components to keep.	required
`n0`	`int`	Initial number of samples for warm-up phase. Must be at least `n_components` to establish every output component.	`50`
`keys`	`list[str] \| None`	Feature names. If None, inferred from first sample.	`None`
`tol`	`float`	Finite, non-negative tolerance for considering residual significance.	`1e-07`
`forgetting_factor`	`float \| None`	Weight for new values (0 < f < 1). If None, uses 1/t.	`None`

Examples:

Python

from aberrant.transform.projection import IncrementalPCA

pca = IncrementalPCA(n_components=2)
pca.learn_one({"x": 1.0, "y": 2.0, "z": 3.0})
transformed = pca.transform_one({"x": 1.5, "y": 2.5, "z": 3.5})

Initialize the IncrementalPCA transformer.

Parameters:

Name	Type	Description	Default
`n_components`	`int`	Number of principal components to keep.	required
`n0`	`int`	Initial number of samples for warm-up phase before switching to online mode. Default is 50.	`50`
`keys`	`Optional[list[str]]`	List of feature names. If None, they will be inferred from the first sample. Default is None.	`None`
`tol`	`float`	Tolerance for considering whether a new data point contributes significantly to the subspace. Default is 1e-7.	`1e-07`
`forgetting_factor`	`Optional[float]`	If None (default) it is a stationary process. Larger f will give new values more weight. Must be in the interval ]0, 1[.	`None`

Implements an online PCA algorithm based on the incremental SVD approach from: - Brand, M. (2002). "Incremental Singular Value Decomposition of Uncertain Data with Missing Values" - Arora, R., Cotter, A., Livescu, K., & Srebro, N. (2012). "Stochastic optimization for PCA and PLS"

The implementation follows the 'incRpca' function from the R package 'onlinePCA: Online Principal Component Analysis' and uses the mathematical framework described in: - Cardot, H. & Degras, D. (2015). "Online Principal Component Analysis in High Dimension: Which Algorithm to Choose?"

Algorithm Steps: 1. Initialization phase: Collect n0 samples and perform uncentered PCA 2. Online phase: For each new sample x_t at time t: - Apply forgetting factor: λ ← (1-f)λ where f = 1/t - Scale new sample: x ← √f * x_t - Project onto current subspace: x̂ = U^T x - Compute residual: r = x - U x̂ - If ||r|| > tol, expand subspace with normalized residual - Update eigendecomposition of diag(λ) + x̂x̂^T - Keep top n_components eigenvalues/vectors

feature_names `property` ¶

Python

feature_names: list[str] | None

Established feature names in projection order.

n_features `property` ¶

Python

n_features: int

Number of established input features.

learn_one ¶

Python

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

Update PCA components incrementally using a single sample.

Parameters:

Name	Type	Description	Default
`x`	`Dict[str, float]`	A dictionary with feature names as keys and values as the data point dimensions.	required

Raises:

Type	Description
`ValueError`	If `n_components` is greater than the number of features in `x`.

transform_one ¶

Python

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

Transform a single data point using the learned PCA components.

Parameters:

Name	Type	Description	Default
`x`	`Dict[str, float]`	A dictionary with feature names as keys and values as the data point dimensions.	required

Returns:

Type	Description
`dict[str, float]`	Transformed data point as dictionary with component names as keys.

RandomProjection ¶

Python

RandomProjection(n_components: int, keys: list[str] | None = None, seed: int | None = None)

Bases: BaseTransformer

Sparse Achlioptas random projection for streaming feature mappings.

A fixed matrix maps the input vector to n_components output values named component_0, component_1, and so on. Matrix entries are sampled from {-sqrt(3/k), 0, sqrt(3/k)}, where k is n_components. Learning establishes feature order but does not adapt the matrix afterward.

Parameters:

Name	Type	Description	Default
`n_components`	`int`	Number of projected dimensions. It cannot exceed the number of input features.	required
`keys`	`list[str] \| None`	Explicit feature order. If omitted, the first learned mapping's insertion order is used.	`None`
`seed`	`int \| None`	Seed for the transformer's local NumPy generator.	`None`

References

Achlioptas, D. (2003). Database-friendly random projections: Johnson-Lindenstrauss with binary coins. https://doi.org/10.1016/S0022-0000(03)00025-4

Initialize the projection and, when possible, its random matrix.

feature_names `property` ¶

Python

feature_names: list[str] | None

Established feature names in projection order.

learn_one ¶

Python

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

Learn the number of dimensions from the first data point.

Parameters:

Name	Type	Description	Default
`x`	`dict[str, float]`	A dictionary with feature names as keys and values as data point dimensions.	required

Raises:

Type	Description
`ValueError`	If the input is invalid or `n_components` exceeds its feature count.

transform_one ¶

Python

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

Transform a single data point using random projection.

Parameters:

Name	Type	Description	Default
`x`	`dict[str, float]`	A dictionary with feature names as keys and values as data point dimensions.	required

Returns:

Type	Description
`dict[str, float]`	Transformed data point as dictionary with component names as keys.

Raises:

Type	Description
`RuntimeError`	If called before learning feature names.
`ValueError`	If values are non-numeric or non-finite, or the feature schema differs from the learned schema.

Transform API¶

Preprocessing¶

FeatureSchemaGuard ¶

feature_names property ¶

learn_one ¶

transform_one ¶

reset ¶

MinMaxScaler ¶

learn_one ¶

transform_one ¶

StandardScaler ¶

learn_one ¶

transform_one ¶

Projection¶

IncrementalPCA ¶

feature_names property ¶

n_features property ¶

learn_one ¶

transform_one ¶

RandomProjection ¶

feature_names property ¶

learn_one ¶

transform_one ¶

feature_names `property` ¶

feature_names `property` ¶

n_features `property` ¶

feature_names `property` ¶