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.

learning_transaction ¶

Python

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

Restore the feature schema if a pipeline update fails.

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), clip: bool = False)

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)`
`clip`	`bool`	Bound transformed values to `feature_range`. False preserves extrapolation beyond the extrema learned so far.	`False`

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)`
`clip`	`bool`	Whether transformed values are clipped to the target range.	`False`

learning_transaction ¶

Python

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

Restore extrema if this or a downstream pipeline stage rejects an event.

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`

learning_transaction ¶

Python

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

Restore running moments if a pipeline update fails.

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.

RollingRobustScaler ¶

Python

RollingRobustScaler(window_size: int = 256, min_samples: int = 1, fallback_scale: float = 1.0)

Bases: BaseTransformer

Center each feature by its recent median and divide by its recent IQR.

Quartiles use linear interpolation at positions (n - 1) * q. Each feature retains its last window_size observations independently; missing features neither advance nor evict that feature's window. A zero interquartile range uses fallback_scale, preserving novel deviations from a constant reference instead of mapping every candidate to zero.

transform_one is read-only and uses provisional statistics even before min_samples observations. Read is_ready to exclude this warm-up from evaluation. Freeze a ready calibration before fitting a downstream model when its stored references must share one coordinate system. Adaptive updates do not re-express downstream points or split boundaries.

For F features in an event and window size W, adaptive learning costs O(F W log W), transformation O(F), and persistent storage O(D W) for D distinct learned features. Use a schema guard to bound D. Frozen learning validates inputs in O(F) and leaves calibration unchanged.

Parameters:

Name	Type	Description	Default
`window_size`	`int`	Maximum observations retained per feature.	`256`
`min_samples`	`int`	Minimum retained observations per learned feature for readiness; this does not disable provisional transformation.	`1`
`fallback_scale`	`float`	Positive finite divisor used only when IQR is zero.	`1.0`

sample_counts `property` ¶

Python

sample_counts: dict[str, int]

Return an owned snapshot of retained observations per feature.

is_ready `property` ¶

Python

is_ready: bool

Whether every learned feature has at least min_samples values.

An empty scaler is not ready. Learning a new feature can make an adaptive scaler unready again; use a schema guard for fixed inputs.

is_frozen `property` ¶

Python

is_frozen: bool

Whether learning validates events without updating calibration.

freeze ¶

Python

freeze() -> None

Freeze a ready calibration; unseen features are then rejected.

unfreeze ¶

Python

unfreeze() -> None

Resume rolling updates from the retained calibration window.

reset ¶

Python

reset() -> None

Clear all learned features and unfreeze, preserving parameters.

learning_transaction ¶

Python

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

Restore this event's windows if a downstream pipeline update fails.

learn_one ¶

Python

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

Validate and stage all feature windows before committing any update.

transform_one ¶

Python

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

Scale without learning; reject unseen features or non-finite output.

Select ¶

Python

Select(features: list[str])

Bases: Passthrough

Select named features in the explicitly supplied order.

Rename ¶

Python

Rename(mapping: dict[str, str])

Bases: Passthrough

Rename selected keys, preserving order and rejecting name collisions.

Passthrough ¶

Bases: BaseTransformer

Copy a finite feature mapping without changing names or values.

learning_transaction ¶

Python

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

Stateless operations need no restoration on downstream failure.

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.

learning_transaction ¶

Python

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

Restore PCA state if a pipeline update fails; arrays are replaced, not edited.

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.

learning_transaction ¶

Python

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

Restore schema and matrix initialization if a pipeline update fails.

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 ¶

learning_transaction ¶

transform_one ¶

reset ¶

MinMaxScaler ¶

learning_transaction ¶

learn_one ¶

transform_one ¶

StandardScaler ¶

learning_transaction ¶

learn_one ¶

transform_one ¶

RollingRobustScaler ¶

sample_counts property ¶

is_ready property ¶

is_frozen property ¶

freeze ¶

unfreeze ¶

reset ¶

learning_transaction ¶

learn_one ¶

transform_one ¶

Select ¶

Rename ¶

Passthrough ¶

learning_transaction ¶

Projection¶

IncrementalPCA ¶

feature_names property ¶

n_features property ¶

learning_transaction ¶

learn_one ¶

transform_one ¶

RandomProjection ¶

feature_names property ¶

learn_one ¶

learning_transaction ¶

transform_one ¶

feature_names `property` ¶

sample_counts `property` ¶

is_ready `property` ¶

is_frozen `property` ¶

feature_names `property` ¶

n_features `property` ¶

feature_names `property` ¶