Normalisers

Stateful normalisation and standardisation classes used during model training and inference. InputNormaliser applies min-max scaling to input features; InputStandardiser applies Z-score standardisation (zero mean, unit variance) to input features; OutputStandardiser applies Z-score standardisation to output labels. All classes are fit on training data only — never on validation or test data.

The make_input_transform factory maps a normalise_inputs_strategy value from BaseTrainConfig to the matching transform: "minmax" constructs an InputNormaliser, "zscore" an InputStandardiser. Min-max scaling suits GP models, whose kernels measure distances between inputs; Z-score standardisation is generally preferred for deep neural networks, but degrades one-hot sequence inputs and is therefore not enabled by default for CNNModel.

class alf_core.model.normaliser.InputNormaliser

Bases: object

Normalises input features to the [0, 1] range via min-max scaling.

Fit on training features, then apply transform at both train and predict time. Each feature dimension is scaled independently.

Supports both 2-D inputs (n_samples, n_features) and higher-dimensional inputs such as the CNN’s 3-D one-hot tensors (n_samples, alphabet_size, seq_len). Statistics are always computed over the batch dimension (dim=0).

Edge case: if a feature has zero range (constant column), the range is set to 1.0 so the feature is only min-shifted (i.e., (X - min) == 0 for training). This prevents unseen non-zero test values from being amplified by division by a tiny epsilon. For one-hot inputs, ensure the training set covers all amino acids at all positions, or clip outputs after transform.

Note

Min-max scaling is well suited for GP models, where the kernel computes distances between input points and benefits from inputs spanning the unit cube [0, 1]. For deep neural networks (e.g. CNNModel), Z-score standardisation (zero mean, unit variance) is generally preferred as it zero-centres inputs and avoids the gradient bias that arises from non-zero-centred activations.

fit(X)

Compute per-feature min and range from training features.

Parameters:

X (']) – Training feature tensor, shape (n_samples, …). Statistics are computed over the batch dimension (dim=0), so each feature position gets its own min/max.

Return type:

None

inverse_transform(X)

Map normalised features in [0, 1] back to the original scale.

Parameters:

X (']) – Normalised feature tensor, shape (n_samples, …), matching the dimensionality of the data passed to fit().

Return type:

']

Returns:

Feature tensor in the original scale, same shape as input.

Raises:

RuntimeError – If called before fit().

property is_fitted: bool

Check if fit() has been called and min/range are available.

transform(X)

Scale features to [0, 1].

Parameters:

X (']) – Feature tensor, shape (n_samples, …), matching the dimensionality of the data passed to fit().

Return type:

']

Returns:

Normalised feature tensor, same shape as input, values in [0, 1].

Raises:

RuntimeError – If called before fit().

class alf_core.model.normaliser.InputStandardiser

Bases: object

Standardises input features to zero mean and unit variance (Z-score).

Fit on training features, then apply transform at both train and predict time. Each feature dimension is standardised independently.

Supports both 2-D inputs (n_samples, n_features) and higher-dimensional inputs such as the CNN’s 3-D one-hot tensors (n_samples, alphabet_size, seq_len). Statistics are always computed over the batch dimension (dim=0).

Edge case: if a feature has near-zero standard deviation (constant column), its scale is set to 1.0 (rather than a tiny epsilon), and a warning is logged. The column is therefore only mean-centred, so unseen non-constant values at predict time (e.g. a one-hot position never varied in training) stay bounded instead of being amplified by division by a near-zero std.

Note

Z-score standardisation is generally preferred for deep neural networks (e.g. CNNModel) as it zero-centres inputs and avoids the gradient bias that arises from non-zero-centred activations. For GP models, the min-max InputNormaliser is usually preferred, since the kernel computes distances between input points and benefits from inputs spanning the unit cube [0, 1].

fit(X)

Compute per-feature mean and std from training features.

Parameters:

X (']) – Training feature tensor, shape (n_samples, …). Statistics are computed over the batch dimension (dim=0), so each feature position gets its own mean/std.

Return type:

None

inverse_transform(X)

Map standardised features back to the original scale.

Parameters:

X (']) – Standardised feature tensor, shape (n_samples, …), matching the dimensionality of the data passed to fit().

Return type:

']

Returns:

Feature tensor in the original scale, same shape as input.

Raises:

RuntimeError – If called before fit().

property is_fitted: bool

Check if fit() has been called and mean/std are available.

transform(X)

Standardise features to zero mean, unit variance.

Parameters:

X (']) – Feature tensor, shape (n_samples, …), matching the dimensionality of the data passed to fit().

Return type:

']

Returns:

Standardised feature tensor, same shape as input.

Raises:

RuntimeError – If called before fit().

class alf_core.model.normaliser.OutputStandardiser

Bases: object

Standardises output labels to zero mean and unit variance.

Fit on training labels, then use transform/inverse_transform to convert between original and standardised space. The model always returns predictions in the original label scale via inverse_transform.

Handles the variance inverse transform correctly:

var_orig = var_standardised * std²

Edge case: if the training labels have near-zero standard deviation (constant targets), std is clamped to _MIN_STD to avoid division by zero.

fit(Y)

Compute mean and std from training labels.

Parameters:

Y (Float[ndarray, 'n_samples']) – 1-D array of training labels, shape (n_samples,).

Return type:

None

inverse_transform(mean, var=None)

Transform predictions back to the original label scale.

Applies the correct variance scaling: var_orig = var_standardised * std².

Parameters:

• mean (Float[ndarray, 'n_samples']) – Predicted means in standardised space, shape (n_samples,).

• var (Float[ndarray, 'n_samples'] | None) – Predicted variances in standardised space, shape (n_samples,), or None.

Return type:

tuple[Float[ndarray, 'n_samples'], Float[ndarray, 'n_samples'] | None]

Returns:

Tuple of (mean_original, var_original). var_original is None if var is None.

Raises:

RuntimeError – If called before fit().

property is_fitted: bool

Check if fit() has been called and mean/std are available.

transform(Y)

Standardise labels to zero mean, unit variance.

Parameters:

Y (Float[ndarray, 'n_samples']) – Array of labels to transform, shape (n_samples,).

Return type:

Float[ndarray, 'n_samples']

Returns:

Standardised labels, shape (n_samples,).

Raises:

RuntimeError – If called before fit().

alf_core.model.normaliser.make_input_transform(strategy)

Construct an unfitted input transform for the given strategy.

Parameters:

strategy (Literal['minmax', 'zscore']) – minmax for InputNormaliser (scaling to [0, 1]) or zscore for InputStandardiser (zero mean, unit variance).

Return type:

InputNormaliser | InputStandardiser

Returns:

An unfitted InputNormaliser or InputStandardiser.

Raises:

ValueError – If strategy is not one of minmax or zscore.