omniloader.transforms.normalize

Feature normalization transforms.

All normalizers apply an affine map (x - offset) / (scale + eps) only where the validity mask is True — padding and placeholder positions keep their original value. The stats-based variants take precomputed statistics (see compute_stats()); InstanceNormalize derives them per sample. All run in both training and evaluation.

Classes

Normalize	Standardize to zero mean and unit variance from (mean, std) stats.
MinMaxNormalize	Scale to [0, 1] from (min, max) stats (divisor is max - min).
RobustNormalize	Standardize by median and IQR from (median, iqr) stats (outlier-robust).
InstanceNormalize	Standardize each sample by its own valid statistics (no external stats).
PerDatasetNormalize	Standardize each sample by its source dataset's own (mean, std) stats.

Module Contents

class omniloader.transforms.normalize.Normalize(stats: collections.abc.Mapping[str, Any], eps: float = 1e-06)

Bases: _StatsNormalizer

Standardize to zero mean and unit variance from (mean, std) stats.

class omniloader.transforms.normalize.MinMaxNormalize(stats: collections.abc.Mapping[str, Any], eps: float = 1e-06)

Bases: _StatsNormalizer

Scale to [0, 1] from (min, max) stats (divisor is max - min).

class omniloader.transforms.normalize.RobustNormalize(stats: collections.abc.Mapping[str, Any], eps: float = 1e-06)

Bases: _StatsNormalizer

Standardize by median and IQR from (median, iqr) stats (outlier-robust).

class omniloader.transforms.normalize.InstanceNormalize(keys: collections.abc.Sequence[str] | None = None, eps: float = 1e-06, schema: omniloader.schema.spec.UnifiedSchema | None = None)

Bases: omniloader.transforms.base.Transform

Standardize each sample by its own valid statistics (no external stats).

For a sequence value the mean/std are taken over the valid time steps (per feature); for a vector value, over the feature axis.

Parameters:

• keys – Feature keys to normalize. When None, every feature in the schema is used (requires schema).

• eps – Small constant added to the std.

• schema – Schema used to resolve keys when it is None.

apply(sample: omniloader.transforms.base.Sample, generator: torch.Generator | None) → omniloader.transforms.base.Sample

Standardize each key using statistics from its own valid positions.

class omniloader.transforms.normalize.PerDatasetNormalize(stats: collections.abc.Mapping[str, collections.abc.Mapping[str, Any]], fallback: str = 'instance', union_stats: collections.abc.Mapping[str, Any] | None = None, dataset_key: str = 'dataset', eps: float = 1e-06)

Bases: omniloader.transforms.base.Transform

Standardize each sample by its source dataset’s own (mean, std) stats.

The remedy for cross-corpus domain shift when training jointly on several datasets that share a feature extractor: each dataset is standardized by its own statistics (see compute_dataset_stats()), selected at run time from the dataset metadata key every unified sample carries. Because per-dataset stats are undefined for a source not seen at training time, a fallback governs unknown ids — crucial for deploying on new sources:

• "instance" — standardize the sample by its own valid statistics (no external stats needed; identical at train and inference);

• "union" — apply the pooled union_stats (a neutral default);

• "identity" — leave the sample unchanged.

Never guess another dataset’s stats for an unknown source — that would inject that corpus’s shift. Runs in both training and evaluation.

Parameters:

• stats – Mapping of dataset name to a per-key stats mapping (each an (mean, std) pair or a mapping with "mean"/"std").

• fallback – Policy for a sample whose dataset id is not in stats.

• union_stats – Pooled per-key stats, required when fallback="union".

• dataset_key – Metadata key holding each sample’s source-dataset name.

• eps – Small constant added to the divisor.

Raises:

ValueError – If fallback is unknown, or "union" without union_stats.

apply(sample: omniloader.transforms.base.Sample, generator: torch.Generator | None) → omniloader.transforms.base.Sample

Normalize sample by its dataset’s stats, or the fallback if unknown.