API Reference

Abstract base class

class torchscalers.scaler.Scaler(*args, **kwargs)[source]

Bases: Module, ABC

Abstract base class for all scalers.

Subclasses must implement fit(), transform(), and inverse_transform(). The concrete fit_transform() method is provided here and delegates to those two methods, so subclasses get it for free.

All scalers inherit from torch.nn.Module so that they can be embedded in larger models, participate in state_dict() checkpointing, and have their buffers moved automatically via .to(device).

Calling a scaler instance directly (scaler(x)) is equivalent to calling transform() and is the idiomatic way to use a scaler inside a model’s forward method or in an torch.nn.Sequential pipeline.

Parameters:

args (Any)
kwargs (Any)

abstractmethod fit(x)[source]

Compute and store statistics from x.

Parameters:: x (Tensor) – Input tensor of shape [N] or [N, D].
Returns:: Returns the scaler instance to allow method chaining.
Return type:: self

abstractmethod transform(x)[source]

Apply the scaler to x using previously fitted statistics.

Parameters:: x (Tensor) – Input tensor of shape [N] or [N, D].
Returns:: Scaled tensor with the same shape as x.
Return type:: Tensor
Raises:: RuntimeError – If fit() has not been called yet.

abstractmethod inverse_transform(x)[source]

Reverse the scaling applied by transform().

Parameters:: x (Tensor) – Scaled tensor of shape [N] or [N, D].
Returns:: Tensor in the original scale, same shape as x.
Return type:: Tensor
Raises:: RuntimeError – If fit() has not been called yet.

fit_transform(x)[source]

Fit to x and immediately transform it.

Equivalent to calling self.fit(x).transform(x).

Parameters:: x (Tensor) – Input tensor of shape [N] or [N, D].
Returns:: Scaled tensor with the same shape as x.
Return type:: Tensor

forward(x)[source]

Apply the scaler to x; delegates to transform().

This makes scalers usable as standard torch.nn.Module objects — scaler(x) works identically to scaler.transform(x).

Parameters:: x (Tensor) – Input tensor of shape [N] or [N, D].
Returns:: Scaled tensor with the same shape as x.
Return type:: Tensor

Scalers

class torchscalers.minmax.MinMaxScaler(eps=1e-08)[source]

Bases: Scaler

Scale features to the range [0, 1] using per-feature min/max statistics.

Statistics are computed column-wise (over the sample dimension) for 2-D inputs [N, D], or as a single scalar for 1-D inputs [N].

The fitted min_, max_, and fitted flag are stored as torch.nn.Module buffers so they are included in state_dict() and move automatically with .to(device).

Parameters:: eps (float) – Minimum range value used as a fallback for constant features (where max == min), preventing division by zero. Defaults to 1e-8.

min_: Tensor

max_: Tensor

fitted: Tensor

fit(x)[source]

Compute and store per-feature min and max from x.

Parameters:: x (Tensor) – Input tensor of shape [N] or [N, D].
Returns:: Returns the scaler instance to allow method chaining.
Return type:: self

transform(x)[source]

Scale x to [0, 1] using the fitted min and max.

Parameters:: x (Tensor) – Input tensor of shape [N] or [N, D].
Returns:: Scaled tensor with the same shape as x.
Return type:: Tensor
Raises:: RuntimeError – If fit() has not been called yet.

inverse_transform(x)[source]

Reverse the scaling applied by transform().

Parameters:: x (Tensor) – Scaled tensor of shape [N] or [N, D].
Returns:: Tensor in the original scale, same shape as x.
Return type:: Tensor
Raises:: RuntimeError – If fit() has not been called yet.

class torchscalers.zscore.ZScoreScaler(eps=1e-08)[source]

Bases: Scaler

Standardize features to zero mean and unit variance (z-score normalization).

Statistics are computed column-wise (over the sample dimension) for 2-D inputs [N, D], or as a single scalar for 1-D inputs [N].

The fitted mean, std, and fitted flag are stored as torch.nn.Module buffers so they are included in state_dict() and move automatically with .to(device).

Parameters:: eps (float) – Minimum value the standard deviation is clamped to, preventing division by zero for constant features. Defaults to 1e-8.

mean: Tensor

std: Tensor

fitted: Tensor

fit(x)[source]

Compute and store mean and standard deviation from x.

Parameters:: x (Tensor) – Input tensor of shape [N] or [N, D].
Returns:: Returns the normalizer instance to allow method chaining.
Return type:: self

transform(x)[source]

Normalize x using the fitted mean and standard deviation.

Parameters:: x (Tensor) – Input tensor of shape [N] or [N, D].
Returns:: Standardized tensor with the same shape as x.
Return type:: Tensor
Raises:: RuntimeError – If fit() has not been called yet.

inverse_transform(x)[source]

Reverse the standardization applied by transform().

Parameters:: x (Tensor) – Standardized tensor of shape [N] or [N, D].
Returns:: Tensor in the original scale, same shape as x.
Return type:: Tensor
Raises:: RuntimeError – If fit() has not been called yet.

class torchscalers.robust.RobustScaler(eps=1e-08)[source]

Bases: Scaler

Scale features using statistics that are robust to outliers.

Centers features by subtracting the median, then scales by the interquartile range (IQR = Q75 - Q25). Because the median and IQR are not affected by extreme values, this scaler is well-suited to data containing outliers.

Statistics are computed column-wise (over the sample dimension) for 2-D inputs [N, D], or as a single scalar for 1-D inputs [N].

The fitted median_, iqr_, and fitted flag are stored as torch.nn.Module buffers so they are included in state_dict() and move automatically with .to(device).

Parameters:: eps (float) – Minimum IQR value used as a fallback for constant features (where IQR is zero), preventing division by zero. Defaults to 1e-8.

median_: Tensor

iqr_: Tensor

fitted: Tensor

fit(x)[source]

Compute and store per-feature median and IQR from x.

Parameters:: x (Tensor) – Input tensor of shape [N] or [N, D].
Returns:: Returns the scaler instance to allow method chaining.
Return type:: self

transform(x)[source]

Center and scale x using the fitted median and IQR.

Parameters:: x (Tensor) – Input tensor of shape [N] or [N, D].
Returns:: Scaled tensor with the same shape as x.
Return type:: Tensor
Raises:: RuntimeError – If fit() has not been called yet.

inverse_transform(x)[source]

Reverse the scaling applied by transform().

Parameters:: x (Tensor) – Scaled tensor of shape [N] or [N, D].
Returns:: Tensor in the original scale, same shape as x.
Return type:: Tensor
Raises:: RuntimeError – If fit() has not been called yet.

class torchscalers.maxabs.MaxAbsScaler(eps=1e-08)[source]

Bases: Scaler

Scale features by their maximum absolute value to the range [-1, 1].

Does not shift the data, so sparsity is preserved. Useful for data that is already centred around zero or that is sparse.

Statistics are computed column-wise (over the sample dimension) for 2-D inputs [N, D], or as a single scalar for 1-D inputs [N].

The fitted max_abs_, and fitted flag are stored as torch.nn.Module buffers so they are included in state_dict() and move automatically with .to(device).

Parameters:: eps (float) – Minimum value max_abs_ is clamped to, preventing division by zero for all-zero features. Defaults to 1e-8.

max_abs_: Tensor

fitted: Tensor

fit(x)[source]

Compute and store per-feature maximum absolute value from x.

Parameters:: x (Tensor) – Input tensor of shape [N] or [N, D].
Returns:: Returns the scaler instance to allow method chaining.
Return type:: self

transform(x)[source]

Scale x to [-1, 1] using the fitted maximum absolute value.

Parameters:: x (Tensor) – Input tensor of shape [N] or [N, D].
Returns:: Scaled tensor with the same shape as x.
Return type:: Tensor
Raises:: RuntimeError – If fit() has not been called yet.

inverse_transform(x)[source]

Reverse the scaling applied by transform().

Parameters:: x (Tensor) – Scaled tensor of shape [N] or [N, D].
Returns:: Tensor in the original scale, same shape as x.
Return type:: Tensor
Raises:: RuntimeError – If fit() has not been called yet.

class torchscalers.shift_scale.ShiftScaleScaler(shift, scale)[source]

Bases: Scaler

Apply a pre-specified shift and scale transformation: (x + shift) * scale.

Unlike data-driven scalers, ShiftScaleScaler requires no fitting step — the shift and scale parameters are provided at construction time. Calling fit() is a no-op.

This is useful when the normalization statistics are already known (e.g. from a dataset publication or domain knowledge) and should not be inferred from the data.

The shift_ and scale_ tensors are stored as torch.nn.Module buffers so they are included in state_dict() and move automatically with .to(device).

Parameters:

shift (Union[float, Tensor]) – Value(s) to add to x before scaling. Scalar or 1-D tensor of length D for feature-wise shifts.
scale (Union[float, Tensor]) – Value(s) to multiply (x + shift) by. Must be strictly positive. Scalar or 1-D tensor of length D.

Raises:

ValueError – If any value in scale is not strictly positive.

shift_: Tensor

scale_: Tensor

fitted: Tensor

fit(x)[source]

No-op — statistics are pre-specified at construction time.

Parameters:: x (Tensor) – Ignored.
Return type:: self

transform(x)[source]

Apply (x + shift) * scale to x.

Parameters:: x (Tensor) – Input tensor of shape [N] or [N, D].
Returns:: Scaled tensor with the same shape as x.
Return type:: Tensor

inverse_transform(x)[source]

Reverse the transformation: x / scale - shift.

Parameters:: x (Tensor) – Scaled tensor of shape [N] or [N, D].
Returns:: Tensor in the original scale, same shape as x.
Return type:: Tensor

class torchscalers.log.LogScaler(eps=1e-08)[source]

Bases: Scaler

Apply a natural log transformation: log(x + eps).

Useful for compressing heavy-tailed or skewed distributions (e.g. power-law data, financial returns, sensor readings). Can be chained with another scaler such as ZScoreScaler to both compress the dynamic range and standardize.

Requires no fitting step — calling fit() is a no-op.

Parameters:: eps (float) – Small constant added to x before taking the log to keep the argument strictly positive. Defaults to 1e-8.

fitted: Tensor

fit(x)[source]

No-op — no statistics to compute.

Parameters:: x (Tensor) – Ignored.
Return type:: self

transform(x)[source]

Apply log(x + eps) element-wise.

Parameters:: x (Tensor) – Input tensor. Values must satisfy x + eps > 0.
Returns:: Log-transformed tensor with the same shape as x.
Return type:: Tensor

inverse_transform(x)[source]

Reverse the log transform: exp(x) - eps.

Parameters:: x (Tensor) – Log-transformed tensor.
Returns:: Tensor in the original scale, same shape as x.
Return type:: Tensor

Composite scalers

class torchscalers.per_domain.PerDomainScaler(scaler_class, **scaler_kwargs)[source]

Bases: Module

Apply a separate scaler instance per string domain ID.

Useful in GNN pipelines and other settings where different node or edge types have distinct feature distributions that should be normalized independently.

Each domain’s scaler is stored inside an torch.nn.ModuleDict (_scalers), so all per-domain statistics are part of the module’s state_dict() and move with .to(device).

Parameters:

scaler_class (type[Scaler]) – The Scaler subclass to instantiate for each new domain (e.g. ZScoreScaler).
**scaler_kwargs (Any) – Keyword arguments forwarded to scaler_class when a new instance is created (e.g. eps=1e-6).

Examples

>>> from torchscalers import PerDomainScaler, ZScoreScaler
>>> pdn = PerDomainScaler(ZScoreScaler, eps=1e-8)
>>> pdn.fit("nodes", node_features)
>>> pdn.fit("edges", edge_features)
>>> node_norm = pdn.transform("nodes", node_features)

fit(domain_id, x)[source]

Fit a scaler for domain_id on x.

A new scaler instance is created the first time a domain_id is seen. Subsequent calls re-fit the existing instance.

Parameters:

domain_id (str) – String key identifying the domain (e.g. "nodes").
x (Tensor) – Input tensor of shape [N] or [N, D].

Returns:

Returns the PerDomainScaler instance to allow chaining.

Return type:

self

transform(domain_id, x)[source]

Normalize x using the fitted scaler for domain_id.

Parameters:

domain_id (str) – String key identifying the domain.
x (Tensor) – Input tensor of shape [N] or [N, D].

Returns:

Scaled tensor with the same shape as x.

Return type:

Tensor

Raises:

KeyError – If domain_id has not been fitted yet.

inverse_transform(domain_id, x)[source]

Reverse the scaling for domain_id.

Parameters:

domain_id (str) – String key identifying the domain.
x (Tensor) – Scaled tensor of shape [N] or [N, D].

Returns:

Tensor in the original scale, same shape as x.

Return type:

Tensor

Raises:

KeyError – If domain_id has not been fitted yet.

class torchscalers.mixed_domain.MixedDomainScaler(scalers=None)[source]

Bases: Module

Apply a different scaler per string domain ID.

Unlike PerDomainScaler, each domain can use a different Scaler subclass with its own constructor arguments, making it suitable for heterogeneous feature spaces where different node or edge types require fundamentally different normalisation strategies.

Scalers must be registered—either at construction time or via register()—before calling fit().

Each domain’s scaler is stored inside an torch.nn.ModuleDict (_scalers), so all per-domain statistics are part of the module’s state_dict() and move with .to(device).

Parameters:: scalers (dict[str, Scaler] | None) – Optional mapping of domain ID to pre-instantiated Scaler objects. Additional domains can be added later via register().

Examples

>>> from torchscalers import MixedDomainScaler, MaxAbsScaler, ZScoreScaler
>>> mds = MixedDomainScaler({
...     "nodes": ZScoreScaler(eps=1e-8),
...     "edges": MaxAbsScaler(eps=1e-8),
... })
>>> mds.fit("nodes", node_features)
>>> mds.fit("edges", edge_features)
>>> node_norm = mds.transform("nodes", node_features)

register(domain_id, scaler)[source]

Register a scaler for domain_id.

Can be called before or after fitting other domains. If domain_id already exists, the existing scaler is replaced.

Parameters:

domain_id (str) – String key identifying the domain.
scaler (Scaler) – Pre-instantiated Scaler to use for this domain.

Returns:

Returns the MixedDomainScaler instance to allow chaining.

Return type:

self

fit(domain_id, x)[source]

Fit the scaler for domain_id on x.

Parameters:

domain_id (str) – String key identifying the domain (e.g. "nodes").
x (Tensor) – Input tensor of shape [N] or [N, D].

Returns:

Returns the MixedDomainScaler instance to allow chaining.

Return type:

self

Raises:

KeyError – If domain_id has not been registered yet.

transform(domain_id, x)[source]

Normalize x using the fitted scaler for domain_id.

Parameters:

domain_id (str) – String key identifying the domain.
x (Tensor) – Input tensor of shape [N] or [N, D].

Returns:

Scaled tensor with the same shape as x.

Return type:

Tensor

Raises:

KeyError – If domain_id has not been registered yet.

inverse_transform(domain_id, x)[source]

Reverse the scaling for domain_id.

Parameters:

domain_id (str) – String key identifying the domain.
x (Tensor) – Scaled tensor of shape [N] or [N, D].

Returns:

Tensor in the original scale, same shape as x.

Return type:

Tensor

Raises:

KeyError – If domain_id has not been registered yet.