transition-foundation-model / tfm /data /normalization.py
maxffarrell's picture
Release experimental Transition Foundation Model v0.1 with reproducible source and validation
1baf215 verified
Raw History Blame Contribute Delete
2.83 kB
"""Training-only observation statistics, with explicit auditable system provenance."""
import json
from dataclasses import dataclass
from pathlib import Path
import numpy as np
from .schema import FIELD_SPECS, NUM_FIELDS
@dataclass
class Normalization:
mean: np.ndarray
scale: np.ndarray
training_system_ids: list[str]
def __post_init__(self):
self.mean, self.scale = np.asarray(self.mean, dtype=float), np.asarray(self.scale, dtype=float)
if self.mean.shape != (NUM_FIELDS,) or self.scale.shape != (NUM_FIELDS,):
raise ValueError("Normalization must match canonical vocabulary")
if not np.isfinite(self.mean).all() or not np.isfinite(self.scale).all() or np.any(self.scale <= 0):
raise ValueError("Normalization must have finite means and positive scales")
@classmethod
def fit(cls, episodes):
episodes = list(episodes)
if not episodes:
raise ValueError("Normalization requires training episodes")
if any(ep.split not in (None, "train") for ep in episodes):
raise ValueError("Normalization fit accepts only training episodes")
count, total, squares = np.zeros(NUM_FIELDS), np.zeros(NUM_FIELDS), np.zeros(NUM_FIELDS)
for episode in episodes:
mask = episode.observation_mask & np.isfinite(episode.values)
observed = np.where(mask, episode.values, 0.0)
count += mask.sum(0)
total += observed.sum(0)
squares += (observed**2).sum(0)
mean = total / np.maximum(count, 1)
scale = np.sqrt(np.maximum(squares / np.maximum(count, 1) - mean**2, 0))
scale[scale < 1e-6] = 1
return cls(mean, scale, sorted({ep.system_id for ep in episodes}))
def transform(self, values, mask=None):
transformed = (np.asarray(values) - self.mean) / self.scale
return np.where(mask, transformed, 0) if mask is not None else transformed
def inverse(self, values):
return np.asarray(values) * self.scale + self.mean
def save(self, path):
data = {
"version": 1,
"field_names": [f.name for f in FIELD_SPECS],
"mean": self.mean.tolist(),
"scale": self.scale.tolist(),
"training_system_ids": self.training_system_ids,
"bounds": {f.name: [f.minimum, f.maximum] for f in FIELD_SPECS},
}
Path(path).write_text(json.dumps(data, indent=2, sort_keys=True) + "\n")
@classmethod
def load(cls, path):
data = json.loads(Path(path).read_text())
if data.get("version") != 1 or data["field_names"] != [f.name for f in FIELD_SPECS]:
raise ValueError("Incompatible normalization version/vocabulary")
return cls(data["mean"], data["scale"], data["training_system_ids"])