shellde 0.2.0__py3-none-any.whl

shellde/structure.py

@@ -0,0 +1,356 @@
+"""Structure-derived contacts to RESTRICT the explicit-pairwise epistasis block.
+
+The honest way to use structure at N=95 is not an inverse-folding feature (protein
+dependent, falsified as a universal win), but to cut the unestimable pairwise term
+count down to biophysically plausible interactions: only model epistasis between
+residues whose side chains are in contact. A few contact pairs x (q-1)^2 is estimable
+where the full C(L,2) expansion is not. Feeds ``GatedPairwiseBlock(space, pairs=...)``
+and the data-gate, so structure proposes the pairs and the data still decides whether
+to open the block.
+
+Minimal dependency-free PDB parser (CB, or CA for glycine / missing CB).
+"""
+from __future__ import annotations
+
+import csv
+import json
+import re
+from collections.abc import Sequence
+from pathlib import Path
+
+import numpy as np
+
+
+def _residue_atoms(pdb_path: str | Path, chain: str | None) -> dict[int, dict[str, np.ndarray]]:
+    """Map residue number -> {atom_name: xyz} for the chosen chain (first if None)."""
+    out: dict[int, dict[str, np.ndarray]] = {}
+    picked_chain: str | None = chain
+    for line in Path(pdb_path).read_text().splitlines():
+        if not line.startswith("ATOM"):
+            continue
+        altloc = line[16]
+        if altloc not in (" ", "A"):
+            continue
+        ch = line[21]
+        if picked_chain is None:
+            picked_chain = ch
+        if ch != picked_chain:
+            continue
+        atom = line[12:16].strip()
+        try:
+            resnum = int(line[22:26])
+            xyz = np.array([float(line[30:38]), float(line[38:46]), float(line[46:54])], dtype=float)
+        except ValueError:
+            continue
+        out.setdefault(resnum, {})[atom] = xyz
+    return out
+
+
+def _cbeta(atoms: dict[str, np.ndarray]) -> np.ndarray | None:
+    """Cbeta coordinate, falling back to Calpha (glycine / missing CB)."""
+    if "CB" in atoms:
+        return atoms["CB"]
+    return atoms.get("CA")
+
+
+def contacts_from_pdb(
+    pdb_path: str | Path,
+    positions: Sequence[int],
+    *,
+    cutoff: float = 8.0,
+    chain: str | None = None,
+) -> list[tuple[int, int]]:
+    """Cbeta-Cbeta contact pairs (distance <= cutoff Angstrom) among ``positions``.
+
+    Positions are absolute 1-based residue numbers (the DesignSpace positions). Residues
+    absent from the structure are skipped. Returns sorted unique (i, j) pairs with i < j.
+    """
+    res = _residue_atoms(pdb_path, chain)
+    coords: dict[int, np.ndarray] = {}
+    for p in positions:
+        atoms = res.get(int(p))
+        cb = _cbeta(atoms) if atoms else None
+        if cb is not None:
+            coords[int(p)] = cb
+    pos = sorted(coords)
+    pairs: list[tuple[int, int]] = []
+    for a in range(len(pos)):
+        for b in range(a + 1, len(pos)):
+            if float(np.linalg.norm(coords[pos[a]] - coords[pos[b]])) <= cutoff:
+                pairs.append((pos[a], pos[b]))
+    return pairs
+
+
+# Crystallization additives / solvents / non-catalytic ions to ignore when picking the
+# ligand from HETATM. Catalytic metals (MG, MN, ZN, FE, CA, CO, NI, CU) are intentionally
+# NOT blocklisted (they are first-shell for metalloenzymes). Override via ligand_resnames
+# for precision.
+_NON_LIGAND = frozenset({
+    "HOH", "WAT", "DOD",
+    "GOL", "EDO", "PEG", "PG4", "PG0", "1PE", "2PE", "P6G", "PGE", "MPD", "BU3",
+    "SO4", "PO4", "ACT", "FMT", "CIT", "FLC", "TLA", "MLA", "OXL", "TAR",
+    "DMS", "BME", "MES", "EPE", "TRS", "IMD", "NH4", "NO3", "CO3", "BCT", "PEO",
+    "NA", "CL", "K", "BR", "IOD", "CS", "RB", "LI",
+})
+
+
+def _is_hydrogen(atom_name: str, element: str = "") -> bool:
+    if element:
+        return element.upper() in ("H", "D")
+    return atom_name.lstrip("0123456789")[:1] == "H"
+
+
+def _heavy_coords(atoms: dict[str, np.ndarray]) -> np.ndarray:
+    """Stack a residue's heavy-atom (non-hydrogen) coordinates as an (N, 3) array."""
+    rows = [xyz for name, xyz in atoms.items() if not _is_hydrogen(name)]
+    return np.asarray(rows, dtype=float) if rows else np.empty((0, 3), dtype=float)
+
+
+def _min_pair_dist(a: np.ndarray, b: np.ndarray) -> float:
+    """Minimum pairwise Euclidean distance between two point sets (N,3) and (M,3)."""
+    d = np.sqrt(((a[:, None, :] - b[None, :, :]) ** 2).sum(axis=-1))
+    return float(d.min())
+
+
+def _ligand_heavy_atoms(
+    pdb_path: str | Path,
+    ligand_resnames: Sequence[str] | None,
+    blocklist: frozenset[str],
+) -> np.ndarray:
+    """Heavy-atom coordinates (M, 3) of the ligand(s) from HETATM records.
+
+    Waters and crystallization additives are dropped via ``blocklist`` unless
+    ``ligand_resnames`` restricts to explicit residue names (which then bypasses the
+    blocklist). Hydrogens are excluded. Ligand chain is not constrained.
+    """
+    keep = frozenset(r.strip().upper() for r in ligand_resnames) if ligand_resnames else None
+    rows: list[list[float]] = []
+    for line in Path(pdb_path).read_text().splitlines():
+        if not line.startswith("HETATM"):
+            continue
+        if line[16] not in (" ", "A"):
+            continue
+        resname = line[17:20].strip().upper()
+        if keep is not None:
+            if resname not in keep:
+                continue
+        elif resname in blocklist:
+            continue
+        element = line[76:78].strip() if len(line) >= 78 else ""
+        atom = line[12:16].strip()
+        if _is_hydrogen(atom, element):
+            continue
+        try:
+            rows.append([float(line[30:38]), float(line[38:46]), float(line[46:54])])
+        except ValueError:
+            continue
+    return np.asarray(rows, dtype=float) if rows else np.empty((0, 3), dtype=float)
+
+
+def shells_from_pdb(
+    pdb_path: str | Path,
+    *,
+    ligand_resnames: Sequence[str] | None = None,
+    chain: str | None = None,
+    contact_cutoff: float = 4.5,
+    blocklist: frozenset[str] | None = None,
+) -> dict[int, list[int]]:
+    """Contact-topology active-site shells from a HOLO structure.
+
+    1st shell: residues with any heavy atom within ``contact_cutoff`` Angstrom of any
+    ligand heavy atom. 2nd shell: residues NOT in the 1st shell with any heavy atom within
+    ``contact_cutoff`` of any 1st-shell residue heavy atom. This is the principled
+    (geometry-adaptive) definition; it replaces an arbitrary single radius and needs a
+    ligand pose (HETATM). It does NOT predict beneficial mutations; it proposes WHERE to
+    saturate. This function carries NO gate, and neither does what consumes it: the shell is
+    handed to the design space as-is (`resolve-site` -> `--positions`), so position selection is
+    evidence-driven, not data-gated. Only optional FEATURE blocks are gated, and there the CALLER
+    decides per flag and per command (`features/base.py`).
+
+    Requires a ligand in the structure. For apo structures, obtain a ligand pose first
+    (experimental cocrystal, co-fold, or homolog superposition) then pass the holo PDB.
+    Returns {1: [...], 2: [...]} of absolute residue numbers (sorted, 1-based).
+    """
+    block = _NON_LIGAND if blocklist is None else blocklist
+    lig = _ligand_heavy_atoms(pdb_path, ligand_resnames, block)
+    if lig.shape[0] == 0:
+        raise ValueError(
+            "no ligand heavy atoms found (apo structure or all HETATM blocklisted); "
+            "pass ligand_resnames or a holo structure with a ligand pose"
+        )
+    res = _residue_atoms(pdb_path, chain)
+    heavy = {r: _heavy_coords(a) for r, a in res.items()}
+    heavy = {r: h for r, h in heavy.items() if h.shape[0]}
+    first = sorted(r for r, h in heavy.items() if _min_pair_dist(h, lig) <= contact_cutoff)
+    fset = set(first)
+    fcoords = [heavy[r] for r in first]
+    second = sorted(
+        r for r, h in heavy.items()
+        if r not in fset and any(_min_pair_dist(h, fc) <= contact_cutoff for fc in fcoords)
+    )
+    return {1: first, 2: second}
+
+
+def load_inverse_folding_logprobs(path: str | Path) -> dict[int, dict[str, float]]:
+    """Load a per-position inverse-folding log-prob table {position: {aa: logp}} from JSON.
+
+    Produce it once with an inverse-folding model (e.g. ProteinMPNN: a single backbone
+    pass yields per-position amino-acid log-probabilities over the 20 AAs). Keys are
+    absolute 1-based residue numbers; feed the result to ``InverseFoldingBlock``.
+    """
+    raw = json.loads(Path(path).read_text())
+    return {int(p): {str(a): float(v) for a, v in d.items()} for p, d in raw.items()}
+
+
+_CANONICAL_AA = frozenset("ACDEFGHIKLMNPQRSTVWY")
+_POS_COLS = frozenset(("position", "pos", "site", "residue", "resnum", "resid"))
+_AA_COLS = frozenset(("aa", "mut", "mutant", "to", "alt", "mutaa", "toaa", "alternate"))
+_TOKEN_COLS = frozenset(("mutation", "mutant", "mut", "substitution", "variant", "token"))
+_DDG_COLS = frozenset((
+    "ddg", "deltadeltag", "delta_delta_g", "delta_delta_G",
+    "ddgkcalpermol", "ddgkcal", "ddgkcalmol", "delta_deltag",
+))
+_MUT_TOKEN_RE = re.compile(r"^[A-Z](?P<pos>[1-9][0-9]*)(?P<aa>[A-Z])$|^(?P<pos2>[1-9][0-9]*)(?P<aa2>[A-Z])$")
+
+
+def _norm_col(name: str) -> str:
+    return re.sub(r"[^a-z0-9]", "", name.lower())
+
+
+def _find_col(fieldnames: Sequence[str], aliases: frozenset[str]) -> str | None:
+    norm_aliases = {_norm_col(a) for a in aliases}
+    for name in fieldnames:
+        if _norm_col(name) in norm_aliases:
+            return name
+    return None
+
+
+def _parse_mut_token(value: object) -> tuple[int, str] | None:
+    text = str(value).strip().upper()
+    m = _MUT_TOKEN_RE.match(text)
+    if not m:
+        return None
+    pos = m.group("pos") or m.group("pos2")
+    aa = m.group("aa") or m.group("aa2")
+    return int(pos), aa
+
+
+def _validate_aa(aa: object, *, context: str) -> str:
+    text = str(aa).strip().upper()
+    if len(text) != 1 or text not in _CANONICAL_AA:
+        raise ValueError(f"invalid amino-acid code {aa!r} in {context}; expected one of {''.join(sorted(_CANONICAL_AA))}")
+    return text
+
+
+def _insert_ddg(out: dict[int, dict[str, float]], pos: int, aa: str, value: float, *, context: str) -> None:
+    if pos < 1:
+        raise ValueError(f"invalid residue position {pos!r} in {context}; positions are 1-based positive integers")
+    aa = _validate_aa(aa, context=context)
+    row = out.setdefault(int(pos), {})
+    if aa in row:
+        if row[aa] != value:
+            raise ValueError(f"conflicting duplicate ddG for position {pos}, aa {aa}: {row[aa]} vs {value} in {context}")
+        return
+    row[aa] = float(value)
+
+
+def _load_ddg_json(path: Path) -> dict[int, dict[str, float]]:
+    raw = json.loads(path.read_text())
+    if not isinstance(raw, dict):
+        raise ValueError("ddG JSON must be an object {position: {aa: ddG}}")
+    out: dict[int, dict[str, float]] = {}
+    for p, table in raw.items():
+        try:
+            pos = int(p)
+        except (TypeError, ValueError) as exc:
+            raise ValueError(f"invalid ddG JSON position {p!r}") from exc
+        if not isinstance(table, dict):
+            raise ValueError(f"ddG JSON position {p!r} must map to an object of aa->ddG")
+        for aa, value in table.items():
+            try:
+                ddg = float(value)
+            except (TypeError, ValueError) as exc:
+                raise ValueError(f"invalid ddG value {value!r} for position {p}, aa {aa}") from exc
+            _insert_ddg(out, pos, str(aa), ddg, context=f"JSON position {p}")
+    return out
+
+
+def _sniff_delimiter(path: Path, text: str) -> str:
+    if path.suffix.lower() in (".tsv", ".tab"):
+        return "\t"
+    if path.suffix.lower() == ".csv":
+        return ","
+    sample = text[:4096]
+    try:
+        return csv.Sniffer().sniff(sample, delimiters=",\t").delimiter
+    except csv.Error:
+        return "\t" if "\t" in sample and "," not in sample else ","
+
+
+def _load_ddg_delimited(path: Path) -> dict[int, dict[str, float]]:
+    text = path.read_text()
+    delimiter = _sniff_delimiter(path, text)
+    reader = csv.DictReader(text.splitlines(), delimiter=delimiter)
+    if not reader.fieldnames:
+        raise ValueError("ddG table must have a header row")
+    fieldnames = [f for f in reader.fieldnames if f is not None]
+    ddg_col = _find_col(fieldnames, _DDG_COLS)
+    if ddg_col is None:
+        raise ValueError("ddG table needs a ddG column (aliases: ddg, delta_delta_G, ddg_kcal_per_mol)")
+    pos_col = _find_col(fieldnames, _POS_COLS)
+    aa_col = _find_col(fieldnames, _AA_COLS)
+    token_col = _find_col(fieldnames, _TOKEN_COLS)
+
+    out: dict[int, dict[str, float]] = {}
+    for line_no, row in enumerate(reader, start=2):
+        context = f"{path.name}:{line_no}"
+        try:
+            ddg = float(row[ddg_col])
+        except (TypeError, ValueError) as exc:
+            raise ValueError(f"invalid ddG value {row.get(ddg_col)!r} in {context}") from exc
+
+        parsed: tuple[int, str] | None = None
+        if token_col and row.get(token_col) not in (None, ""):
+            parsed = _parse_mut_token(row[token_col])
+        if parsed is not None:
+            pos, aa = parsed
+        else:
+            if pos_col is None or aa_col is None:
+                raise ValueError(
+                    "ddG table needs either a mutation token column like A123V, or both "
+                    "position (position/pos/site/residue) and mutant-aa (aa/mut/mutant/to/alt) columns"
+                )
+            try:
+                pos = int(str(row[pos_col]).strip())
+            except (TypeError, ValueError) as exc:
+                raise ValueError(f"invalid residue position {row.get(pos_col)!r} in {context}") from exc
+            aa = _validate_aa(row[aa_col], context=context)
+        _insert_ddg(out, pos, aa, ddg, context=context)
+
+    if not out:
+        raise ValueError("ddG table contained no rows")
+    return out
+
+
+def load_ddg_table(path: str | Path) -> dict[int, dict[str, float]]:
+    """Load a per-position folding ddG table {position: {aa: ddG_kcal_per_mol}}.
+
+    Accepted formats:
+    - JSON object ``{position: {aa: ddG}}`` (backward compatible).
+    - CSV/TSV long table with a ddG column plus either:
+      (a) position + mutant-AA columns (aliases: position/pos/site/residue and aa/mut/mutant/to/alt), or
+      (b) a mutation token column containing values like ``A123V`` or ``123V``.
+
+    Convention: ddG is the predicted change in folding free energy on mutating the WT
+    residue at ``position`` to ``aa`` (positive = destabilizing, like ThermoMPNN / FoldX;
+    the WT residue is 0 by definition and need not be listed). Produce it once with a
+    free ddG predictor (ThermoMPNN, FoldX, RaSP) over the active-site region; feed the
+    result to ``funclib.design_library`` as its stability filter. Keys are absolute
+    1-based residue numbers. Shares the table shape of an inverse-folding log-prob
+    table but carries ddG semantics (lower is more stable, not a log-prob).
+    """
+    p = Path(path)
+    stripped = p.read_text()[:2048].lstrip()
+    if p.suffix.lower() == ".json" or stripped.startswith("{"):
+        return _load_ddg_json(p)
+    return _load_ddg_delimited(p)

shellde/surrogate.py

@@ -0,0 +1,323 @@
+"""Surrogates with CALIBRATED predictive uncertainty (the day-one contract).
+
+All surrogates expose the same contract: ``fit`` -> ``predict`` returning a
+``Prediction(mean, std)`` whose ``std`` is a calibrated 1-sigma predictive standard
+deviation, plus ``main_effects`` (an always-fit ridge arm) for the additive
+position-selection prior.
+
+Calibration is variance scaling: a model produces a RAW per-point uncertainty
+(ensemble/tree spread combined with a residual floor), and a single scale ``s`` is
+fit by k-fold so that held-out standardised residuals (y - mean) / (s * raw) have
+unit variance. This is simple, low-N robust, and turns an ad-hoc
+"spread + floor" into an actually-calibrated number that acquisition and the risk
+flags can trust.
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+import numpy as np
+from sklearn.ensemble import RandomForestRegressor
+from sklearn.isotonic import IsotonicRegression
+from sklearn.linear_model import LogisticRegression, Ridge
+
+from shellde.types import Prediction
+
+DEFAULT_ALPHA = 1.0
+N_MEMBERS = 15
+N_TREES = 100
+CAL_FOLDS = 5
+_FLOOR = 1e-9
+
+
+class _BaseSurrogate(ABC):
+    """Shared fit/calibrate/predict machinery; subclasses define the deployed model."""
+
+    def __init__(self, alpha: float = DEFAULT_ALPHA, random_state: int = 0) -> None:
+        self.alpha = alpha
+        self.random_state = random_state
+        self._arm: Ridge | None = None
+        self._scale: float = 1.0
+        self._resid_std: float = _FLOOR
+        self._fitted: bool = False
+
+    # --- subclass hooks ----------------------------------------------------
+    @abstractmethod
+    def _new(self) -> "_BaseSurrogate":
+        """A fresh, unfitted clone with identical hyperparameters (for calibration)."""
+
+    @abstractmethod
+    def _fit_raw(self, x: np.ndarray, y: np.ndarray, sw: np.ndarray | None) -> None:
+        """Fit the deployed model + set ``self._resid_std`` from in-sample residuals."""
+
+    @abstractmethod
+    def _mean(self, x: np.ndarray) -> np.ndarray: ...
+
+    @abstractmethod
+    def _raw_std(self, x: np.ndarray) -> np.ndarray:
+        """Uncalibrated per-point std (spread combined with the residual floor)."""
+
+    # --- public contract ---------------------------------------------------
+    def fit(
+        self, x: np.ndarray, y: np.ndarray, sample_weight: np.ndarray | None = None
+    ) -> "_BaseSurrogate":
+        x = np.asarray(x, dtype=float)
+        y = np.asarray(y, dtype=float).ravel()
+        if x.ndim != 2 or x.shape[0] != y.shape[0]:
+            raise ValueError(f"x {x.shape} incompatible with y {y.shape}")
+        if x.shape[0] < 2:
+            raise ValueError("need at least 2 training samples")
+        sw = None if sample_weight is None else np.asarray(sample_weight, dtype=float)
+        self._arm = Ridge(alpha=self.alpha).fit(x, y, sample_weight=sw)  # additive prior
+        self._scale = self._calibrate(x, y, sw)
+        self._fit_raw(x, y, sw)
+        self._fitted = True
+        return self
+
+    def _calibrate(self, x: np.ndarray, y: np.ndarray, sw: np.ndarray | None) -> float:
+        n = len(y)
+        if n < 4:
+            return 1.0
+        k = min(CAL_FOLDS, n // 2)
+        idx = np.random.default_rng(self.random_state).permutation(n)
+        folds = np.array_split(idx, k)
+        ratios: list[np.ndarray] = []
+        for i in range(k):
+            te = folds[i]
+            tr = np.concatenate([folds[j] for j in range(k) if j != i])
+            if len(tr) < 2 or len(te) == 0:
+                continue
+            m = self._new()
+            m._fit_raw(x[tr], y[tr], None if sw is None else sw[tr])
+            resid = y[te] - m._mean(x[te])
+            rs = np.maximum(m._raw_std(x[te]), _FLOOR)
+            ratios.append((resid / rs) ** 2)
+        if not ratios:
+            return 1.0
+        return float(np.sqrt(max(float(np.mean(np.concatenate(ratios))), _FLOOR)))
+
+    def _check(self) -> None:
+        if not self._fitted:
+            raise RuntimeError("surrogate not fitted; call fit() first")
+
+    def predict(self, x: np.ndarray) -> Prediction:
+        self._check()
+        x = np.asarray(x, dtype=float)
+        std = self._scale * np.maximum(self._raw_std(x), _FLOOR)
+        return Prediction(mean=self._mean(x), std=std)
+
+    def main_effects(self) -> np.ndarray | None:
+        self._check()
+        assert self._arm is not None
+        return np.asarray(self._arm.coef_, dtype=float)
+
+
+class RidgeSurrogate(_BaseSurrogate):
+    """Homoscedastic ridge; calibrated std equals the held-out RMSE (constant)."""
+
+    def _new(self) -> "RidgeSurrogate":
+        return RidgeSurrogate(self.alpha, self.random_state)
+
+    def _fit_raw(self, x: np.ndarray, y: np.ndarray, sw: np.ndarray | None) -> None:
+        self._model = Ridge(alpha=self.alpha).fit(x, y, sample_weight=sw)
+        self._resid_std = float(np.std(y - self._model.predict(x))) or _FLOOR
+
+    def _mean(self, x: np.ndarray) -> np.ndarray:
+        return np.asarray(self._model.predict(x), dtype=float)
+
+    def _raw_std(self, x: np.ndarray) -> np.ndarray:
+        return np.full(x.shape[0], max(self._resid_std, _FLOOR), dtype=float)
+
+
+class EnsembleSurrogate(_BaseSurrogate):
+    """Bootstrap-ridge ensemble; heteroscedastic std from member spread + floor."""
+
+    def __init__(
+        self, alpha: float = DEFAULT_ALPHA, n_members: int = N_MEMBERS, random_state: int = 0
+    ) -> None:
+        super().__init__(alpha, random_state)
+        self.n_members = n_members
+
+    def _new(self) -> "EnsembleSurrogate":
+        return EnsembleSurrogate(self.alpha, self.n_members, self.random_state)
+
+    def _fit_raw(self, x: np.ndarray, y: np.ndarray, sw: np.ndarray | None) -> None:
+        rng = np.random.default_rng(self.random_state)
+        n = x.shape[0]
+        self._members: list[Ridge] = []
+        for _ in range(self.n_members):
+            b = rng.integers(0, n, n)
+            swb = None if sw is None else sw[b]
+            self._members.append(Ridge(alpha=self.alpha).fit(x[b], y[b], sample_weight=swb))
+        self._resid_std = float(np.std(y - self._mean(x))) or _FLOOR
+
+    def _mean(self, x: np.ndarray) -> np.ndarray:
+        return np.mean([m.predict(x) for m in self._members], axis=0)
+
+    def _raw_std(self, x: np.ndarray) -> np.ndarray:
+        preds = np.stack([m.predict(x) for m in self._members], axis=0)
+        return np.sqrt(preds.std(axis=0) ** 2 + self._resid_std**2)
+
+
+class RFSurrogate(_BaseSurrogate):
+    """Random forest; heteroscedastic std from tree spread + floor (captures interactions)."""
+
+    def __init__(
+        self, alpha: float = DEFAULT_ALPHA, n_estimators: int = N_TREES, random_state: int = 0
+    ) -> None:
+        super().__init__(alpha, random_state)
+        self.n_estimators = n_estimators
+
+    def _new(self) -> "RFSurrogate":
+        return RFSurrogate(self.alpha, self.n_estimators, self.random_state)
+
+    def _fit_raw(self, x: np.ndarray, y: np.ndarray, sw: np.ndarray | None) -> None:
+        self._rf = RandomForestRegressor(
+            n_estimators=self.n_estimators, random_state=self.random_state
+        ).fit(x, y, sample_weight=sw)
+        self._resid_std = float(np.std(y - self._mean(x))) or _FLOOR
+
+    def _mean(self, x: np.ndarray) -> np.ndarray:
+        return np.asarray(self._rf.predict(x), dtype=float)
+
+    def _raw_std(self, x: np.ndarray) -> np.ndarray:
+        preds = np.stack([t.predict(x) for t in self._rf.estimators_], axis=0)
+        return np.sqrt(preds.std(axis=0) ** 2 + self._resid_std**2)
+
+
+class BayesLinearSurrogate(_BaseSurrogate):
+    """Closed-form Bayesian linear regression.
+
+    The posterior predictive variance (noise + x^T S x) IS the uncertainty, which made
+    explicit-pairwise epistasis estimation stronger than a bootstrap-ridge
+    ensemble. Feed it [one-hot + GatedPairwise] to get the explicit-epistasis path.
+    Note: at N=95, q=20 the pairwise block is still unestimable (361 params/pair), so
+    this is a completeness/strength port, not an N=95 winner.
+    """
+
+    def _new(self) -> "BayesLinearSurrogate":
+        return BayesLinearSurrogate(self.alpha, self.random_state)
+
+    def _fit_raw(self, x: np.ndarray, y: np.ndarray, sw: np.ndarray | None) -> None:
+        d = x.shape[1]
+        a_inv = np.linalg.inv(x.T @ x + self.alpha * np.eye(d))  # (XtX + lam I)^-1
+        self._coef = a_inv @ x.T @ y
+        resid = y - x @ self._coef
+        self._beta = 1.0 / max(float(np.var(resid)), _FLOOR)  # noise precision from residual
+        self._cov = a_inv / self._beta  # posterior covariance for precision beta
+        self._resid_std = float(np.std(resid)) or _FLOOR
+
+    def _mean(self, x: np.ndarray) -> np.ndarray:
+        return x @ self._coef
+
+    def _raw_std(self, x: np.ndarray) -> np.ndarray:
+        var = 1.0 / self._beta + np.sum((x @ self._cov) * x, axis=1)
+        return np.sqrt(np.maximum(var, 0.0))
+
+
+class RankingSurrogate(_BaseSurrogate):
+    """Scale-invariant pairwise-logistic ranking readout (FolDE's ranking-loss lesson).
+
+    Trains a linear model with a Bradley-Terry / BCE-over-pairs objective (label = which
+    of a pair is fitter), so naturalness units and activity units can share one loss and
+    the fit is invariant to monotone rescaling of y. The raw ranking score is then mapped
+    to activity units by a 1-D least-squares fit so the surrogate still returns a
+    calibrated mean+std. Pair this with NaturalnessBlock to get warm-start anchoring.
+    """
+
+    def __init__(self, alpha: float = DEFAULT_ALPHA, random_state: int = 0, max_pairs: int = 4000) -> None:
+        super().__init__(alpha, random_state)
+        self.max_pairs = max_pairs
+
+    def _new(self) -> "RankingSurrogate":
+        return RankingSurrogate(self.alpha, self.random_state, self.max_pairs)
+
+    def _fit_raw(self, x: np.ndarray, y: np.ndarray, sw: np.ndarray | None) -> None:
+        n = x.shape[0]
+        rng = np.random.default_rng(self.random_state)
+        # ordered index pairs with distinct y; sample if the full set is too large
+        if n * (n - 1) <= 2 * self.max_pairs:
+            ii, jj = np.meshgrid(np.arange(n), np.arange(n), indexing="ij")
+            mask = ii != jj
+            pi, pj = ii[mask], jj[mask]
+        else:
+            pi = rng.integers(0, n, self.max_pairs)
+            pj = rng.integers(0, n, self.max_pairs)
+            keep = pi != pj
+            pi, pj = pi[keep], pj[keep]
+        diff_y = y[pi] - y[pj]
+        good = np.abs(diff_y) > _FLOOR
+        pi, pj, diff_y = pi[good], pj[good], diff_y[good]
+        if pi.size < 2:  # degenerate (all y equal): rank-neutral fallback
+            self._w = np.zeros(x.shape[1], dtype=float)
+            self._a, self._b = float(np.mean(y)), 0.0
+            self._resid_std = float(np.std(y)) or _FLOOR
+            return
+        d = x[pi] - x[pj]
+        lab = (diff_y > 0).astype(int)
+        clf = LogisticRegression(fit_intercept=False, C=1.0 / max(self.alpha, _FLOOR), max_iter=1000)
+        clf.fit(d, lab)
+        self._w = np.asarray(clf.coef_[0], dtype=float)
+        s = x @ self._w
+        if float(np.std(s)) < _FLOOR:
+            self._a, self._b = float(np.mean(y)), 0.0
+        else:
+            self._b, self._a = (float(v) for v in np.polyfit(s, y, 1))
+        self._resid_std = float(np.std(y - (self._a + self._b * s))) or _FLOOR
+
+    def _mean(self, x: np.ndarray) -> np.ndarray:
+        return self._a + self._b * (x @ self._w)
+
+    def _raw_std(self, x: np.ndarray) -> np.ndarray:
+        return np.full(x.shape[0], max(self._resid_std, _FLOOR), dtype=float)
+
+
+class GlobalEpistasisSurrogate(_BaseSurrogate):
+    """Additive latent (ridge) passed through a learned MONOTONIC link (global epistasis).
+
+    Models nonspecific / global epistasis: an additive latent trait fed through a learned monotonic
+    nonlinearity (Otwinowski 2018; Sailer & Harms; MoCHI). Recovers calibrated magnitude where naive
+    additive prediction collapses at high mutation order (ShellDE D24 on avGFP: the monotonic link
+    lifts R2 from negative back to 0.78 / 0.63 at orders 5 / 6). The measured value is sharper
+    calibrated uncertainty (D30: 2x tighter intervals with both coverages at or above nominal, not
+    equal to each other, on synthetic saturating-link data), not a different ranking objective.
+
+    NOT rank-preserving in the sense of "same plate". The link never INVERTS a pair (measured: zero
+    strict inversions of the mean against the ridge order over 30 seeds x 124750 pool pairs), but
+    `IsotonicRegression(out_of_bounds="clip")` in `_fit_raw` is only WEAKLY monotonic, so its flat
+    segments collapse distinct candidates onto identical values (about 180 distinct predictions for
+    a 500-candidate pool). `_ScoreAcquisition.select` in `acquisition.py` breaks those ties by
+    `np.argsort` index order, so a tie block straddling the top-k cut (mean size 25.0, range 1 to
+    74) emits a DIFFERENT plate: over 30 seeds at n=95, d=10, k=20 the plate matched the ridge
+    plate in only 7 of 30 seeds, mean well overlap 0.785 (range 0.25 to 1.00), and the plate ORDER
+    matched in 0 of 30.
+
+    That number is acquisition-independent FOR THIS SURROGATE AND `RidgeSurrogate` ONLY: both
+    return a constant per-point std (`_raw_std` is `np.full(...)` in each, measured constant in 30
+    of 30 seeds), so `UCB` reduces to `Greedy` and the result is identical at the `recommend`
+    default beta=1.0 and the `campaign` / `round` default beta=0.0. Do NOT generalize it:
+    `EnsembleSurrogate`, which is the default `--model-class` on all three commands, is
+    heteroscedastic (relative std spread 0.2702 mean, range 0.1767 to 0.4759), and its `Greedy` and
+    `UCB(beta=1.0)` plates agree as a SET in only 20 of 30 seeds and never in order.
+
+    Synthetic saturating-link data on DENSE standard-normal features (d=10), not the one-hot
+    combinatorial encoding `FeatureMatrix.encode` builds for the CLI from `default_blocks`, so the
+    tie mechanism transfers but these magnitudes are not a measurement on the shipped design
+    matrix. `scripts/run_global_epistasis_rank_check.py`, raw in
+    `artifacts/global_epistasis_rank_check.json`. Opt-in; not the default.
+    """
+
+    def _new(self) -> "GlobalEpistasisSurrogate":
+        return GlobalEpistasisSurrogate(self.alpha, self.random_state)
+
+    def _fit_raw(self, x: np.ndarray, y: np.ndarray, sw: np.ndarray | None) -> None:
+        self._latent = Ridge(alpha=self.alpha).fit(x, y, sample_weight=sw)
+        z = self._latent.predict(x)
+        self._link = IsotonicRegression(out_of_bounds="clip").fit(z, y)
+        self._resid_std = float(np.std(y - self._link.predict(z))) or _FLOOR
+
+    def _mean(self, x: np.ndarray) -> np.ndarray:
+        return np.asarray(self._link.predict(self._latent.predict(x)), dtype=float)
+
+    def _raw_std(self, x: np.ndarray) -> np.ndarray:
+        return np.full(x.shape[0], max(self._resid_std, _FLOOR), dtype=float)