evoforest-tab 0.1.0__py3-none-any.whl

evoforest_tab/__init__.py

@@ -0,0 +1,28 @@
+"""evoforest_tab: EvoForest-Tab -- an evolved universal tabular feature map + closed-form ridge head.
+
+An interpretable, training-free, local in-context learner competitive with tabular foundation
+models. See README. Main entry points:
+
+    from evoforest_tab import EvoForestTabClassifier, EvoForestTabRegressor
+"""
+from .estimator import TabMapClassifier, TabMapRegressor
+from ._genome import load_genome, build_phi, seed_variant, DEFAULT_GENOME
+from ._channels import build_channels
+from .combine import StackedTabularEnsemble
+from ._module import EvoForestTabModule
+from .inductive import (
+    EvoForestTabInductiveClassifier, EvoForestTabInductiveRegressor, EvoForestTabTransformer,
+    TabMapInductiveClassifier, TabMapInductiveRegressor, TabMapTransformer,
+)
+
+# brand-consistent names matching the paper (the TabMap* names remain as aliases)
+EvoForestTabClassifier = TabMapClassifier
+EvoForestTabRegressor = TabMapRegressor
+
+__all__ = ["EvoForestTabClassifier", "EvoForestTabRegressor",
+           "TabMapClassifier", "TabMapRegressor", "build_channels",
+           "build_phi", "load_genome", "seed_variant", "DEFAULT_GENOME",
+           "StackedTabularEnsemble", "EvoForestTabModule",
+           "EvoForestTabInductiveClassifier", "EvoForestTabInductiveRegressor", "EvoForestTabTransformer",
+           "TabMapInductiveClassifier", "TabMapInductiveRegressor", "TabMapTransformer"]
+__version__ = "0.1.0"

evoforest_tab/_channels.py

@@ -0,0 +1,122 @@
+"""Channel construction: raw table rows -> the input channels the feature map reads.
+
+Faithful to the development pipeline. All channels are UNSUPERVISED and TRANSDUCTIVE (computed over the
+pooled support+query rows, label-free) so the map is leakage-safe in the in-context (support->query)
+setting. Categoricals are ordinal-encoded; missing values are nan-safe; columns are padded/capped to Dmax.
+"""
+import math
+
+import numpy as np
+import torch
+
+DMAX_DEFAULT = 100
+
+
+def _nan_col_zscore(X: torch.Tensor) -> torch.Tensor:
+    """Per-column z-score (nan-safe); nan -> 0 after standardizing."""
+    nan = torch.isnan(X)
+    Xf = torch.where(nan, torch.zeros_like(X), X)
+    cnt = (~nan).sum(0).clamp(min=1).to(X.dtype)
+    mean = Xf.sum(0) / cnt
+    var = (torch.where(nan, torch.zeros_like(X), (X - mean) ** 2)).sum(0) / cnt
+    z = (X - mean) / (var.sqrt() + 1e-6)
+    return torch.where(nan, torch.zeros_like(z), z)
+
+
+def _col_rankgauss(X: torch.Tensor) -> torch.Tensor:
+    """Per-column rank -> ~N(0,1) (nan ranked last, then zeroed). Transductive, label-free."""
+    N = X.shape[0]
+    filled = torch.where(torch.isnan(X), torch.full_like(X, float("inf")), X)
+    ranks = filled.argsort(0).argsort(0).to(X.dtype)
+    u = (ranks + 0.5) / N
+    z = math.sqrt(2.0) * torch.erfinv((2 * u - 1).clamp(-1 + 1e-6, 1 - 1e-6))
+    return torch.where(torch.isnan(X), torch.zeros_like(z), z)
+
+
+def _col_freq(Xm: np.ndarray) -> np.ndarray:
+    """Per-column count/frequency encoding: each cell -> fraction of rows sharing its value."""
+    n, D = Xm.shape
+    Fr = np.zeros_like(Xm, dtype=np.float64)
+    for j in range(D):
+        _, inv, counts = np.unique(Xm[:, j], return_inverse=True, return_counts=True)
+        Fr[:, j] = counts[inv] / n
+    return Fr
+
+
+def _pad(X: torch.Tensor, Dmax: int) -> torch.Tensor:
+    if X.shape[1] >= Dmax:
+        return X[:, :Dmax]
+    return torch.cat([X, torch.zeros(X.shape[0], Dmax - X.shape[1], dtype=X.dtype)], dim=1)
+
+
+def _to_ordinal(X, cat_features):
+    """Coerce a 2-D array (numpy object/float or pandas DataFrame) to a float matrix with categoricals
+    ordinal-encoded (nan preserved), returning (Xm float64, cat_mask bool)."""
+    try:
+        import pandas as pd
+        is_df = isinstance(X, pd.DataFrame)
+    except ImportError:
+        is_df = False
+    if is_df:
+        cols, cat = [], []
+        for ci, c in enumerate(X.columns):
+            s = X[c]
+            auto_cat = str(s.dtype) in ("category", "object", "bool")
+            user_cat = cat_features is not None and (ci in cat_features or c in cat_features)
+            if auto_cat or user_cat:
+                codes = s.astype("category").cat.codes.to_numpy().astype(np.float64)
+                codes[codes < 0] = np.nan
+                cols.append(codes); cat.append(True)
+            else:
+                cols.append(s.to_numpy(dtype=np.float64)); cat.append(False)
+        return np.column_stack(cols), np.array(cat, dtype=bool)
+    Xm = np.asarray(X, dtype=object)
+    n, D = Xm.shape
+    out = np.zeros((n, D), dtype=np.float64)
+    cat = np.zeros(D, dtype=bool)
+    for j in range(D):
+        col = Xm[:, j]
+        user_cat = cat_features is not None and j in cat_features
+        is_numeric = np.issubdtype(np.asarray(col).dtype, np.number)
+        try:
+            fcol = col.astype(np.float64)
+            numeric_ok = True
+        except (ValueError, TypeError):
+            numeric_ok = False
+        if user_cat or not numeric_ok or (not is_numeric):
+            uniq = {v: i for i, v in enumerate(sorted(set(map(str, col))))}
+            out[:, j] = np.array([uniq[str(v)] for v in col], dtype=np.float64)
+            cat[j] = True
+        else:
+            out[:, j] = fcol
+    return out, cat
+
+
+def build_channels(X, cat_features=None, Dmax: int = DMAX_DEFAULT, device="cpu"):
+    """Build the input-channel dict from raw rows X (n, d). Returns tensors padded to Dmax.
+
+    X: numpy array or pandas DataFrame (the POOLED support+query rows).
+    cat_features: indices (or names) of categorical columns; if None, auto-detect by dtype/cardinality.
+    """
+    Xm, cat = _to_ordinal(X, cat_features)
+    # median-impute, drop constant columns (matches the dev pipeline)
+    med = np.nanmedian(Xm, axis=0)
+    inds = np.where(np.isnan(Xm))
+    Xm[inds] = np.take(med, inds[1])
+    keep = Xm.std(0) > 1e-9
+    Xm = Xm[:, keep]; cat = cat[keep]
+    if Xm.shape[1] == 0:
+        raise ValueError("no non-constant columns after preprocessing")
+    # cap to Dmax by top variance
+    if Xm.shape[1] > Dmax:
+        top = np.argsort(-Xm.std(0))[:Dmax]
+        Xm = Xm[:, top]; cat = cat[top]
+    n, D = Xm.shape
+    Xt = torch.from_numpy(Xm).float().to(device)
+    x = _pad(_nan_col_zscore(Xt), Dmax)
+    xrank = _pad(_col_rankgauss(Xt), Dmax)
+    x_freq = _pad(_nan_col_zscore(torch.from_numpy(_col_freq(Xm)).float().to(device)), Dmax)
+    fmask = torch.zeros(n, Dmax, device=device); fmask[:, :min(D, Dmax)] = 1.0
+    is_cat = torch.zeros(n, Dmax, device=device)
+    is_cat[:, :min(D, Dmax)] = torch.from_numpy(cat[:min(D, Dmax)].astype(np.float32)).to(device)
+    return {"x": x, "xrank": xrank, "fmask": fmask, "is_cat": is_cat, "x_freq": x_freq, "Dmax": Dmax}

evoforest_tab/_genome.py

@@ -0,0 +1,64 @@
+"""Evaluate the evolved genome (a list of feature-lambdas) on the input channels to produce the
+feature matrix Phi. The genome is the deployment artifact; each lambda is a small, inspectable
+expression over the channels with fixed seeded random projections."""
+import math
+import os
+import re
+
+import numpy as np
+import torch
+import torch.nn.functional as F
+import yaml
+
+_G = {"torch": torch, "F": F, "np": np, "math": math}
+_HERE = os.path.dirname(os.path.abspath(__file__))
+DEFAULT_GENOME = os.path.join(_HERE, "champion.yaml")
+
+
+def load_genome(path: str = DEFAULT_GENOME) -> dict:
+    return yaml.safe_load(open(path))
+
+
+def seed_variant(genome: dict, offset: int) -> dict:
+    """Offset every manual_seed(N) -> manual_seed(N+offset): a decorrelated random-feature draw of the
+    SAME architecture (used for the variance-reducing ensemble)."""
+    out = [re.sub(r"manual_seed\((\d+)\)", lambda m: f"manual_seed({int(m.group(1)) + offset})", lam)
+           for lam in genome["output"]]
+    g = dict(genome); g["output"] = out
+    return g
+
+
+def build_phi(genome: dict, channels: dict) -> torch.Tensor:
+    """Apply the genome's output lambdas to the channel dict and stack into a normalized (n, K) matrix."""
+    gg = {k: eval(v, _G) for k, v in (genome.get("@globals", {}) or {}).items()}
+    n = channels["x"].shape[0]
+    signals = []
+    for lam in genome["output"]:
+        fn = eval(lam, _G)
+        na = fn.__code__.co_argcount
+        an = fn.__code__.co_varnames[:na]
+        args = [channels if a == "input" else gg if a == "globals" else None for a in an]
+        signals.append(fn(*args))
+    cols = []
+    for sig in signals:
+        if not torch.is_tensor(sig):
+            sig = torch.as_tensor(sig)
+        sig = sig.float()
+        if sig.dim() >= 2 and sig.shape[0] == n and sig.shape[1] > 1:
+            sub = [sig[:, c] for c in range(sig.shape[1])]
+        else:
+            sig = sig.squeeze()
+            if sig.dim() != 1 or sig.shape[0] != n:
+                continue
+            sub = [sig]
+        for col in sub:
+            col = torch.where(torch.isfinite(col), col, torch.zeros_like(col))
+            if col.std() < 1e-12:
+                continue
+            cols.append(col)
+    if not cols:
+        raise ValueError("genome produced no usable feature columns")
+    Phi = torch.stack(cols, dim=1)
+    mu = Phi.mean(0, keepdim=True)
+    sigma = Phi.std(0, keepdim=True).clamp(min=1e-12)
+    return (Phi - mu) / sigma

evoforest_tab/_module.py

@@ -0,0 +1,152 @@
+"""Compile the evolved genome (champion.yaml) into a self-contained ``torch.nn.Module``.
+
+The genome is the *architecture spec* produced by EvoForest search. In the reference path each family's
+seeded random projection is re-drawn on every forward via ``torch.randn(..., generator=manual_seed(N))``
+inside an ``eval``'d lambda. That is fine for a frozen feature map but (a) cannot be fine-tuned, (b) re-draws
+on every call, and (c) is not a saveable artifact.
+
+``EvoForestTabModule`` fixes all three: it materializes every seeded ``randn``/``rand`` draw **once** as a
+frozen ``nn.Parameter`` (``requires_grad=False`` by default), so the module is a self-contained, saveable,
+HuggingFace-publishable checkpoint whose ``forward`` is byte-identical to the reference evaluation -- and the
+random features become fine-tunable simply by calling :meth:`unfreeze_random_features`. The deterministic
+families (rank/stats/frequency) carry no parameters and are reproduced exactly.
+"""
+from __future__ import annotations
+
+import math
+
+import numpy as np
+import torch
+import torch.nn.functional as F
+from torch import nn
+
+from ._genome import load_genome, DEFAULT_GENOME
+
+
+class _SeededWeightBank(nn.Module):
+    """Materialize seeded ``torch.randn``/``torch.rand`` draws as frozen Parameters, keyed by (op, seed, shape)."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.weights = nn.ParameterDict()
+
+    @staticmethod
+    def _key(op: str, shape, seed: int) -> str:
+        return f"{op}__seed{int(seed)}__" + "x".join(str(int(s)) for s in shape)
+
+    def get(self, op: str, shape, seed: int, device=None) -> torch.Tensor:
+        key = self._key(op, shape, seed)
+        if key not in self.weights:
+            gen = torch.Generator().manual_seed(int(seed))            # CPU draw == reference on CPU
+            draw = (torch.randn if op == "randn" else torch.rand)(*shape, generator=gen)
+            self.weights[key] = nn.Parameter(draw, requires_grad=False)  # frozen by default
+        w = self.weights[key]
+        return w.to(device) if device is not None else w
+
+
+class _TorchProxy:
+    """A stand-in for the ``torch`` namespace inside the genome lambdas: seeded ``randn``/``rand`` are routed
+    to the materialized weight bank; every other attribute delegates to real ``torch``."""
+
+    def __init__(self, bank: _SeededWeightBank) -> None:
+        object.__setattr__(self, "_bank", bank)
+
+    def __getattr__(self, name):
+        return getattr(torch, name)
+
+    def randn(self, *shape, generator=None, device=None, dtype=None):
+        if generator is None:
+            return torch.randn(*shape, device=device, dtype=dtype)
+        return self._bank.get("randn", shape, generator.initial_seed(), device)
+
+    def rand(self, *shape, generator=None, device=None, dtype=None):
+        if generator is None:
+            return torch.rand(*shape, device=device, dtype=dtype)
+        return self._bank.get("rand", shape, generator.initial_seed(), device)
+
+
+class EvoForestTabModule(nn.Module):
+    """Evolved EvoForest-Tab feature map phi as a compiled, fine-tunable, saveable ``nn.Module``.
+
+    Parameters
+    ----------
+    genome : dict | None
+        The parsed genome (defaults to the released champion).
+    dmax : int
+        Padded channel width the module is built for (random-projection shapes depend only on this).
+
+    Notes
+    -----
+    ``forward(channels)`` takes the channel dict from :func:`evoforest_tab.build_channels` and returns the
+    normalized ``(n, K)`` feature matrix, byte-identical to :func:`evoforest_tab.build_phi`. Random-feature
+    weights are frozen by default; call :meth:`unfreeze_random_features` to fine-tune them (e.g. at BSC), then
+    ``state_dict()`` is a publishable derivative checkpoint.
+    """
+
+    def __init__(self, genome: dict | None = None, dmax: int = 100) -> None:
+        super().__init__()
+        genome = genome if genome is not None else load_genome(DEFAULT_GENOME)
+        self.output_src = list(genome["output"])
+        self.dmax = dmax
+        self.bank = _SeededWeightBank()
+        self._proxy = _TorchProxy(self.bank)
+        env = {"torch": self._proxy, "F": F, "np": np, "math": math}
+        self._fns = [eval(src, env) for src in self.output_src]                # proxy-bound lambdas
+        with torch.no_grad():                                                  # eager-materialize the bank
+            self._materialize()
+
+    # ------------------------------------------------------------------ build / fine-tune controls
+    def _materialize(self) -> None:
+        dummy = self._dummy_channels()
+        for fn in self._fns:
+            try:
+                fn(dummy)                       # fires the seeded randn/rand -> banks the weights
+            except Exception:                   # noqa: BLE001 - dummy may degenerate post-draw; weights are banked
+                pass
+
+    def _dummy_channels(self) -> dict:
+        z = torch.randn(4, self.dmax)
+        return {"x": z, "xrank": z.clone(), "x_freq": z.clone(),
+                "fmask": torch.ones(4, self.dmax), "is_cat": torch.zeros(4, self.dmax), "Dmax": self.dmax}
+
+    def unfreeze_random_features(self) -> "EvoForestTabModule":
+        for p in self.bank.weights.values():
+            p.requires_grad_(True)
+        return self
+
+    def freeze_random_features(self) -> "EvoForestTabModule":
+        for p in self.bank.weights.values():
+            p.requires_grad_(False)
+        return self
+
+    @property
+    def n_random_parameters(self) -> int:
+        return sum(p.numel() for p in self.bank.weights.values())
+
+    # ------------------------------------------------------------------ forward (mirrors build_phi exactly)
+    def forward(self, channels: dict) -> torch.Tensor:
+        n = channels["x"].shape[0]
+        cols = []
+        for fn in self._fns:
+            sig = fn(channels)
+            if not torch.is_tensor(sig):
+                sig = torch.as_tensor(sig)
+            sig = sig.float()
+            if sig.dim() >= 2 and sig.shape[0] == n and sig.shape[1] > 1:
+                sub = [sig[:, c] for c in range(sig.shape[1])]
+            else:
+                sig = sig.squeeze()
+                if sig.dim() != 1 or sig.shape[0] != n:
+                    continue
+                sub = [sig]
+            for col in sub:
+                col = torch.where(torch.isfinite(col), col, torch.zeros_like(col))
+                if col.std() < 1e-12:
+                    continue
+                cols.append(col)
+        if not cols:
+            raise ValueError("genome produced no usable feature columns")
+        phi = torch.stack(cols, dim=1)
+        mu = phi.mean(0, keepdim=True)
+        sigma = phi.std(0, keepdim=True).clamp(min=1e-12)
+        return (phi - mu) / sigma

evoforest_tab/_ridge.py

@@ -0,0 +1,45 @@
+"""Closed-form ridge head with Bayesian evidence-maximized regularization (MacKay/Tipping).
+
+The head is fit on the support features and applied to the query features in a single SVD solve --
+no gradient descent, no per-dataset hyperparameter grid. lambda is set by evidence maximization,
+which is markedly more stable than a leave-one-out grid in the few-shot (K>>n) regime.
+"""
+import torch
+
+LAM_FLOOR = 1e-2
+
+
+def evidence_lambda(U, S, Y, n_iter: int = 60) -> float:
+    """Bayesian-ridge lambda = alpha/beta by evidence maximization, reusing the support SVD (U,S),
+    with alpha,beta shared across Y's columns and a floor for the K>n interpolation regime."""
+    s2 = S ** 2
+    UtY = U.transpose(0, 1) @ Y
+    n, M = Y.shape
+    ytot = (Y ** 2).sum(); proj = (UtY ** 2).sum()
+    lam = torch.tensor(1.0, dtype=S.dtype, device=S.device)
+    for _ in range(n_iter):
+        h = s2 / (s2 + lam)
+        d = S / (s2 + lam)
+        wsq = ((d.unsqueeze(1) * UtY) ** 2).sum()
+        rss = (ytot - proj) + (((1 - h).unsqueeze(1) * UtY) ** 2).sum()
+        gamma = h.sum()
+        alpha = (M * gamma) / (wsq + 1e-12)
+        beta = (M * n - M * gamma) / (rss + 1e-12)
+        lam_new = (alpha / (beta + 1e-12)).clamp(min=LAM_FLOOR, max=1e8)
+        if (lam_new - lam).abs() < 1e-3 * lam:
+            lam = lam_new
+            break
+        lam = lam_new
+    return float(lam)
+
+
+def ridge_scores(Phi_s, Y, Phi_q, lam=None):
+    """Standardize by support stats, solve ridge in closed form, return query scores (nq, M)."""
+    mu = Phi_s.mean(0, keepdim=True); sd = Phi_s.std(0, keepdim=True).clamp(min=1e-8)
+    Phi_s = (Phi_s - mu) / sd; Phi_q = (Phi_q - mu) / sd
+    U, S, Vt = torch.linalg.svd(Phi_s, full_matrices=False)
+    UY = U.transpose(0, 1) @ Y
+    if lam is None:
+        lam = evidence_lambda(U, S, Y)
+    W = Vt.transpose(0, 1) @ ((S / (S ** 2 + lam)).unsqueeze(1) * UY)
+    return Phi_q @ W

evoforest_tab/champion.yaml

@@ -0,0 +1,77 @@
+output:
+- 'lambda input: (lambda x, fm, c: torch.stack([(x * fm).sum(1) / c, ((x * x * fm).sum(1)
+  / c - ((x * fm).sum(1) / c) ** 2).clamp(min=0).sqrt(), x.masked_fill(fm == 0, float(''-inf'')).amax(1),
+  x.masked_fill(fm == 0, float(''inf'')).amin(1), c / x.shape[1]], dim=1))(input[''x''],
+  input[''fmask''], input[''fmask''].sum(1).clamp(min=1))  #name: output_0 qi_mean=None
+  qi_std=None qi_max=None qd_mean=None qd_std=None qd_max=None age=69'
+- 'lambda input: (lambda x, fm: (lambda A: torch.exp(-(((x.unsqueeze(1) - A.unsqueeze(0))
+  ** 2) * fm.unsqueeze(1)).sum(2) / fm.sum(1, keepdim=True).clamp(min=1)))(torch.randn(8,
+  x.shape[1], generator=torch.Generator(device=x.device).manual_seed(209), device=x.device)))(input[''x''],
+  input[''fmask''])  #name: output_1 qi_mean=None qi_std=None qi_max=None qd_mean=None
+  qd_std=None qd_max=None age=69'
+- 'lambda input: (lambda x, s: torch.cat([torch.relu(x @ torch.randn(x.shape[1], 8,
+  generator=torch.Generator(device=x.device).manual_seed(321), device=x.device) /
+  s), (x @ torch.randn(x.shape[1], 8, generator=torch.Generator(device=x.device).manual_seed(322),
+  device=x.device) / s) ** 2], dim=1))(input[''xrank''], input[''fmask''].sum(1, keepdim=True).clamp(min=1).sqrt())  #name:
+  output_2 qi_mean=None qi_std=None qi_max=None qd_mean=None qd_std=None qd_max=None
+  age=66'
+- 'lambda input: (lambda x, s: torch.tanh(x @ torch.randn(x.shape[1], 16, generator=torch.Generator(device=x.device).manual_seed(501),
+  device=x.device) / s))(input[''xrank''], input[''fmask''].sum(1, keepdim=True).clamp(min=1).sqrt())  #name:
+  output_3 qi_mean=None qi_std=None qi_max=None qd_mean=None qd_std=None qd_max=None
+  age=65'
+- 'lambda input: (lambda x, s: torch.tanh((torch.sign(x) * torch.log1p(x.abs())) @
+  torch.randn(x.shape[1], 16, generator=torch.Generator(device=x.device).manual_seed(701),
+  device=x.device) / s))(input[''x''], input[''fmask''].sum(1, keepdim=True).clamp(min=1).sqrt())  #name:
+  output_4 qi_mean=None qi_std=None qi_max=None qd_mean=None qd_std=None qd_max=None
+  age=62'
+- 'lambda input: (lambda x, s: torch.tanh((torch.sign(x) * x.abs().sqrt()) @ torch.randn(x.shape[1],
+  16, generator=torch.Generator(device=x.device).manual_seed(801), device=x.device)
+  / s))(input[''x''], input[''fmask''].sum(1, keepdim=True).clamp(min=1).sqrt())  #name:
+  output_5 qi_mean=None qi_std=None qi_max=None qd_mean=None qd_std=None qd_max=None
+  age=60'
+- 'lambda input: (lambda x, s: torch.sigmoid(8.0 * (x @ torch.randn(x.shape[1], 16,
+  generator=torch.Generator(device=x.device).manual_seed(951), device=x.device) /
+  s)))(input[''xrank''], input[''fmask''].sum(1, keepdim=True).clamp(min=1).sqrt())  #name:
+  output_6 qi_mean=None qi_std=None qi_max=None qd_mean=None qd_std=None qd_max=None
+  age=55'
+- 'lambda input: (lambda x, ic, ct: torch.stack([(x*ic).sum(1)/ic.sum(1).clamp(min=1),
+  (x*ct).sum(1)/ct.sum(1).clamp(min=1), (x*x*ic).sum(1)/ic.sum(1).clamp(min=1), (x*x*ct).sum(1)/ct.sum(1).clamp(min=1)],
+  dim=1))(input[''x''], input[''is_cat''], input[''fmask'']-input[''is_cat''])  #name:
+  output_7 qi_mean=None qi_std=None qi_max=None qd_mean=None qd_std=None qd_max=None
+  age=50'
+- 'lambda input: (lambda x, ic: torch.tanh((x*ic) @ torch.randn(x.shape[1], 16, generator=torch.Generator(device=x.device).manual_seed(1221),
+  device=x.device) / ic.sum(1,keepdim=True).clamp(min=1).sqrt()))(input[''xrank''],
+  input[''is_cat''])  #name: output_8 qi_mean=None qi_std=None qi_max=None qd_mean=None
+  qd_std=None qd_max=None age=48'
+- 'lambda input: (lambda x, s: torch.tanh(x @ torch.randn(x.shape[1], 16, generator=torch.Generator(device=x.device).manual_seed(1501),
+  device=x.device) / s))(input[''x_freq''], input[''fmask''].sum(1, keepdim=True).clamp(min=1).sqrt())  #name:
+  output_9 qi_mean=None qi_std=None qi_max=None qd_mean=None qd_std=None qd_max=None
+  age=43'
+- 'lambda input: torch.tanh((input[''xrank'']*input[''x_freq'']) @ torch.randn(input[''x''].shape[1],
+  16, generator=torch.Generator(device=input[''x''].device).manual_seed(1711), device=input[''x''].device)
+  / input[''fmask''].sum(1, keepdim=True).clamp(min=1).sqrt())  #name: output_10 qi_mean=None
+  qi_std=None qi_max=None qd_mean=None qd_std=None qd_max=None age=37'
+- 'lambda input: torch.tanh(((torch.sign(input[''x''])*input[''x''].abs().sqrt())*input[''xrank''])
+  @ torch.randn(input[''x''].shape[1], 16, generator=torch.Generator(device=input[''x''].device).manual_seed(1901),
+  device=input[''x''].device) / input[''fmask''].sum(1, keepdim=True).clamp(min=1).sqrt())  #name:
+  output_11 qi_mean=None qi_std=None qi_max=None qd_mean=None qd_std=None qd_max=None
+  age=35'
+- 'lambda input: (lambda W,b: torch.cos(input[''xrank''] @ W / input[''fmask''].sum(1,
+  keepdim=True).clamp(min=1).sqrt() + b))(torch.randn(input[''x''].shape[1], 16, generator=torch.Generator(device=input[''x''].device).manual_seed(207),
+  device=input[''x''].device), torch.rand(16, generator=torch.Generator(device=input[''x''].device).manual_seed(208),
+  device=input[''x''].device)*6.2831853)  #name: output_12 qi_mean=None qi_std=None
+  qi_max=None qd_mean=None qd_std=None qd_max=None age=30'
+- 'lambda input: torch.tanh(input[''x''] @ torch.randn(input[''x''].shape[1], 16,
+  generator=torch.Generator(device=input[''x''].device).manual_seed(401), device=input[''x''].device)
+  / input[''fmask''].sum(1, keepdim=True).clamp(min=1).sqrt())  #name: output_13 qi_mean=None
+  qi_std=None qi_max=None qd_mean=None qd_std=None qd_max=None age=30'
+- 'lambda input: (lambda W,b: torch.cos(input[''x''] @ W / input[''fmask''].sum(1,
+  keepdim=True).clamp(min=1).sqrt() + b))(torch.randn(input[''x''].shape[1], 24, generator=torch.Generator(device=input[''x''].device).manual_seed(201),
+  device=input[''x''].device), torch.rand(24, generator=torch.Generator(device=input[''x''].device).manual_seed(202),
+  device=input[''x''].device)*6.2831853)  #name: output_14 qi_mean=None qi_std=None
+  qi_max=None qd_mean=None qd_std=None qd_max=None age=28'
+- 'lambda input: (lambda x, fm: (lambda C: (torch.exp(-((x.unsqueeze(2) - C) ** 2))
+  * fm.unsqueeze(2)).sum(1) / fm.sum(1, keepdim=True).clamp(min=1))(torch.linspace(-2.0,
+  2.0, 8, device=x.device).reshape(1, 1, 8)))(input[''xrank''], input[''fmask''])  #name:
+  output_15 qi_mean=None qi_std=None qi_max=None qd_mean=None qd_std=None qd_max=None
+  age=12'

evoforest_tab/combine.py

@@ -0,0 +1,165 @@
+"""Combine TabMap with a tabular foundation model (e.g. TabPFN) into a single predictor.
+
+Implements the paper's complementarity result: an evolved closed-form map and a pretrained transformer
+capture different structure (one tends to win classification, the other regression), so combining them
+beats either alone. Three methods, in increasing adaptivity:
+
+  - ``blend``  : fixed 50/50 average of the base models' outputs (naive; only helps when matched).
+  - ``compwt`` : weight each base by its support-cross-validated competence (label-free, no meta-learner).
+  - ``meta``   : a learned ridge head over the base models' out-of-fold support predictions (most robust).
+
+All combination is leakage-safe and *in-context*: weights/head are fit on the SUPPORT set via out-of-fold
+predictions (no query labels). Base models are any in-context estimators with the scikit-learn surface
+(``fit(X, y)`` + ``predict``/``predict_proba``), e.g. ``TabMapClassifier`` and TabPFN's client.
+
+Example
+-------
+>>> from evoforest_tab import TabMapClassifier, StackedTabularEnsemble
+>>> from tabpfn_client import TabPFNClassifier
+>>> ens = StackedTabularEnsemble([TabMapClassifier(), TabPFNClassifier()], task="classification",
+...                              method="meta").fit(X_support, y_support)
+>>> proba = ens.predict_proba(X_query)
+"""
+import numpy as np
+
+try:
+    from sklearn.base import clone
+except ImportError:
+    def clone(e):  # minimal fallback
+        return e.__class__(**(e.get_params() if hasattr(e, "get_params") else {}))
+
+
+def _ridge_fit_predict(Xtr, Ytr, Xte, lam=1.0):
+    """Tiny closed-form ridge meta-head (numpy) with an intercept. Inputs are model outputs (probas /
+    predictions, already on a comparable bounded scale), so we \emph{center} rather than divide by the
+    per-column std---dividing by a near-zero std on a degenerate (near-constant) base output otherwise
+    explodes the fit on imbalanced datasets."""
+    mu = Xtr.mean(0, keepdims=True); ybar = Ytr.mean(0, keepdims=True)
+    Xc, Xqc = Xtr - mu, Xte - mu
+    A = Xc.T @ Xc + lam * np.eye(Xc.shape[1])
+    W = np.linalg.solve(A, Xc.T @ (Ytr - ybar))
+    return Xqc @ W + ybar
+
+
+class StackedTabularEnsemble:
+    """Stack/blend in-context tabular base models (e.g. TabMap + TabPFN).
+
+    Parameters
+    ----------
+    base_models : list of estimators (in-context; sklearn surface). For classification each must expose
+        ``predict_proba``; for regression, ``predict``.
+    task : {"classification", "regression"}.
+    method : {"meta", "compwt", "blend"} (default "meta").
+    n_splits : folds for the support out-of-fold predictions (default 2).
+    """
+
+    def __init__(self, base_models, task="classification", method="meta", n_splits=2, ridge_lambda=1.0,
+                 random_state=0):
+        self.base_models = list(base_models)
+        self.task = task
+        self.method = method
+        self.n_splits = n_splits
+        self.ridge_lambda = ridge_lambda
+        self.random_state = random_state
+
+    # ---- helpers --------------------------------------------------------
+    def _is_clf(self):
+        return self.task == "classification"
+
+    def _base_out(self, model, Xq):
+        if self._is_clf():
+            p = np.asarray(model.predict_proba(Xq))
+            P = np.zeros((p.shape[0], self.n_classes_))
+            cls = getattr(model, "classes_", np.arange(p.shape[1]))
+            for j, c in enumerate(cls):
+                idx = self._cls_index.get(c, j if j < self.n_classes_ else None)
+                if idx is not None:
+                    P[:, idx] = p[:, j]
+            return P
+        return np.asarray(model.predict(Xq)).reshape(-1)
+
+    def _competence(self, oof, y):
+        if self._is_clf():
+            acc = (oof.argmax(1) == y).mean()
+            maj = np.bincount(y, minlength=self.n_classes_).argmax()
+            base = (y == maj).mean()
+            return max((acc - base) / (1 - base + 1e-8), 0.0)
+        ss_res = ((y - oof) ** 2).sum(); ss_tot = ((y - y.mean()) ** 2).sum() + 1e-8
+        return max(1.0 - ss_res / ss_tot, 0.0)
+
+    # ---- fit/predict ----------------------------------------------------
+    def fit(self, X, y):
+        X = np.asarray(X) if not hasattr(X, "iloc") else X
+        y = np.asarray(y)
+        n = len(y)
+        if self._is_clf():
+            self.classes_, y_idx = np.unique(y, return_inverse=True)
+            self.n_classes_ = len(self.classes_)
+            self._cls_index = {c: i for i, c in enumerate(self.classes_)}
+            y_work = y_idx
+        else:
+            y_work = y.astype(float)
+        self._X, self._y = X, y_work
+        # out-of-fold support predictions for each base model
+        rng = np.random.RandomState(self.random_state)
+        folds = np.array_split(rng.permutation(n), self.n_splits)
+        oofs = []
+        for model in self.base_models:
+            oof = (np.zeros((n, self.n_classes_)) if self._is_clf() else np.zeros(n))
+            for te in folds:
+                tr = np.setdiff1d(np.arange(n), te)
+                if self._is_clf() and len(np.unique(y_work[tr])) < 2:
+                    continue
+                m = clone(model)
+                Xtr = X.iloc[tr] if hasattr(X, "iloc") else X[tr]
+                Xte = X.iloc[te] if hasattr(X, "iloc") else X[te]
+                m.fit(Xtr, (self.classes_[y_work[tr]] if self._is_clf() else y_work[tr]))
+                oof[te] = self._base_out(m, Xte)
+            oofs.append(oof)
+        self._oofs = oofs
+        # competence weights (normalized); fall back to uniform (= 50/50) if no model is competent,
+        # so a degenerate support (e.g. heavy imbalance -> all competences clamp to 0) never yields a
+        # zero prediction.
+        comps = [self._competence(o, y_work) for o in oofs]
+        s = sum(comps)
+        self._weights = [c / s for c in comps] if s > 1e-6 else [1.0 / len(comps)] * len(comps)
+        if self.method == "meta":
+            H = np.concatenate(oofs, 1) if self._is_clf() else np.stack(oofs, 1)
+            if self._is_clf():
+                Y = np.eye(self.n_classes_)[y_work]
+                self._head = ("clf", H.mean(0), H.std(0), Y)  # store; refit at predict via _ridge
+            self._Htr = H
+            self._Ytr = (np.eye(self.n_classes_)[y_work] if self._is_clf()
+                         else (y_work - y_work.mean())[:, None])
+            self._ymean = (0.0 if self._is_clf() else y_work.mean())
+        return self
+
+    def _query_outs(self, Xq):
+        outs = []
+        for model in self.base_models:
+            m = clone(model)
+            m.fit(self._X, (self.classes_[self._y] if self._is_clf() else self._y))
+            outs.append(self._base_out(m, Xq))
+        return outs
+
+    def _combine(self, outs):
+        if self.method == "blend":
+            w = [1.0 / len(outs)] * len(outs)
+            return sum(wi * o for wi, o in zip(w, outs))
+        if self.method == "compwt":
+            return sum(wi * o for wi, o in zip(self._weights, outs))
+        # meta: learned ridge head over concatenated/stacked base outputs
+        Hq = np.concatenate(outs, 1) if self._is_clf() else np.stack(outs, 1)
+        pred = _ridge_fit_predict(self._Htr, self._Ytr, Hq, self.ridge_lambda)
+        return pred if self._is_clf() else pred[:, 0] + self._ymean
+
+    def predict_proba(self, Xq):
+        assert self._is_clf(), "predict_proba is classification-only"
+        P = self._combine(self._query_outs(Xq))
+        P = np.clip(P, 1e-9, None); return P / P.sum(1, keepdims=True)
+
+    def predict(self, Xq):
+        outs = self._query_outs(Xq)
+        if self._is_clf():
+            return self.classes_[self._combine(outs).argmax(1)]
+        return self._combine(outs)

evoforest_tab/estimator.py

@@ -0,0 +1,108 @@
+"""scikit-learn-style estimators for the evolved universal tabular feature map + closed-form ridge head.
+
+An in-context learner: ``fit`` stores the labeled support rows; ``predict`` builds the (transductive,
+label-free) channels over the pooled support+query rows, maps them through the evolved feature map,
+and solves a Bayesian ridge in closed form -- no gradient descent, no per-dataset tuning. An optional
+K-member ensemble averages decorrelated random-feature draws (variance reduction toward the kernel
+limit). Free, local, CPU-friendly, and interpretable.
+
+Example
+-------
+>>> from evoforest_tab import TabMapClassifier
+>>> clf = TabMapClassifier(n_estimators=6).fit(X_support, y_support)
+>>> proba = clf.predict_proba(X_query)
+"""
+import numpy as np
+import torch
+
+from ._channels import DMAX_DEFAULT, build_channels
+from ._genome import DEFAULT_GENOME, build_phi, load_genome, seed_variant
+from ._ridge import ridge_scores
+
+try:
+    from sklearn.base import BaseEstimator, ClassifierMixin, RegressorMixin
+except ImportError:  # sklearn optional
+    class BaseEstimator:  # type: ignore
+        def get_params(self, deep=True):
+            return {}
+    class ClassifierMixin:  # type: ignore
+        pass
+    class RegressorMixin:  # type: ignore
+        pass
+
+
+class _TabMapBase(BaseEstimator):
+    def __init__(self, n_estimators: int = 6, genome_path: str = DEFAULT_GENOME,
+                 cat_features=None, Dmax: int = DMAX_DEFAULT, device: str = "cpu"):
+        self.n_estimators = n_estimators
+        self.genome_path = genome_path
+        self.cat_features = cat_features
+        self.Dmax = Dmax
+        self.device = device
+
+    def _genomes(self):
+        base = load_genome(self.genome_path)
+        return [base] + [seed_variant(base, 1000 * k) for k in range(1, self.n_estimators)]
+
+    def _fit(self, X, y):
+        self._X = np.asarray(X) if not hasattr(X, "iloc") else X
+        self._y = np.asarray(y)
+        self._n_support = len(self._y)
+        return self
+
+    def _phi_split(self, X_query):
+        """Pool support+query, build channels + Phi per genome variant, yield (Phi_s, Phi_q)."""
+        if hasattr(self._X, "iloc"):
+            import pandas as pd
+            X_all = pd.concat([self._X, X_query if hasattr(X_query, "iloc") else pd.DataFrame(
+                np.asarray(X_query), columns=self._X.columns)], axis=0, ignore_index=True)
+        else:
+            X_all = np.vstack([np.asarray(self._X), np.asarray(X_query)])
+        channels = build_channels(X_all, cat_features=self.cat_features, Dmax=self.Dmax, device=self.device)
+        ns = self._n_support
+        for g in self._genomes():
+            Phi = build_phi(g, channels)
+            yield Phi[:ns], Phi[ns:]
+
+
+class TabMapClassifier(_TabMapBase, ClassifierMixin):
+    def fit(self, X, y):
+        self._fit(X, y)
+        self.classes_, y_idx = np.unique(self._y, return_inverse=True)
+        self._y_idx = y_idx
+        return self
+
+    def predict_proba(self, X_query):
+        nc = len(self.classes_)
+        ys = torch.from_numpy(self._y_idx).long()
+        Y = torch.zeros(self._n_support, nc, device=self.device)
+        Y[torch.arange(self._n_support), ys] = 1.0
+        probs = None
+        k = 0
+        for Phi_s, Phi_q in self._phi_split(X_query):
+            scores = ridge_scores(Phi_s, Y, Phi_q)
+            p = torch.softmax(scores, dim=1)
+            probs = p if probs is None else probs + p
+            k += 1
+        return (probs / k).cpu().numpy()
+
+    def predict(self, X_query):
+        return self.classes_[self.predict_proba(X_query).argmax(1)]
+
+
+class TabMapRegressor(_TabMapBase, RegressorMixin):
+    def fit(self, X, y):
+        self._fit(X, y.astype(float) if hasattr(y, "astype") else y)
+        return self
+
+    def predict(self, X_query):
+        yt = torch.from_numpy(np.asarray(self._y, dtype=np.float64)).float().to(self.device)
+        mean = yt.mean()
+        Y = (yt - mean).unsqueeze(1)
+        preds = None
+        k = 0
+        for Phi_s, Phi_q in self._phi_split(X_query):
+            scores = ridge_scores(Phi_s, Y, Phi_q).squeeze(1) + mean
+            preds = scores if preds is None else preds + scores
+            k += 1
+        return (preds / k).cpu().numpy()

evoforest_tab/inductive.py

@@ -0,0 +1,274 @@
+"""Inductive EvoForest-Tab: a standard fit->transform/predict feature map (fits channel statistics on
+TRAINING data, applies the *fixed* maps to new rows), as opposed to the transductive/in-context tabmap
+estimators whose predict() pools support+query. The inductive version satisfies the ordinary
+scikit-learn contract (and therefore `check_estimator`), so it can serve as the basis for the
+scikit-learn-contrib estimator, the skrub `TabMapEncoder` (a TransformerMixin), and a pytorch-frame /
+AutoGluon featurizer. It reuses the SAME evolved genome (the 16 families) -- only the channels are now
+computed inductively.
+
+Channels (all fit on train, applied to new data):
+  x       = per-column standardize           (StandardScaler)
+  xrank   = per-column rank-gauss             (QuantileTransformer, output_distribution='normal')
+  x_freq  = per-column count/frequency encode (value->train-frequency map; unseen -> 0), standardized
+  is_cat  = categorical mask                  (from cat_features / fit-time dtype)
+  fmask   = feature-presence mask
+Padded/capped to Dmax columns (top-variance selection fit on train).
+"""
+import math
+
+import numpy as np
+import torch
+import torch.nn.functional as F
+from sklearn.base import BaseEstimator, ClassifierMixin, RegressorMixin, TransformerMixin
+from sklearn.linear_model import RidgeCV, RidgeClassifierCV
+import numpy as _np
+from sklearn.preprocessing import QuantileTransformer, StandardScaler
+from sklearn.utils.validation import check_is_fitted
+
+# reuse the evolved genome (the 16 families) from this package
+from ._genome import load_genome, seed_variant, DEFAULT_GENOME
+
+_G = {"torch": torch, "F": F, "np": np, "math": math}
+DMAX = 100
+
+
+def _raw_phi(genome, channels):
+    """Evaluate the genome lambdas on the channel dict and stack ALL feature columns, WITHOUT the
+    per-batch drop/standardize that the transductive build_phi applies (which would make the output
+    width and scale batch-dependent). Inductive selection + standardization is applied by the caller
+    using statistics stored at fit time."""
+    gg = {k: eval(v, _G) for k, v in (genome.get("@globals", {}) or {}).items()}
+    n = channels["x"].shape[0]
+    cols = []
+    for lam in genome["output"]:
+        fn = eval(lam, _G); na = fn.__code__.co_argcount; an = fn.__code__.co_varnames[:na]
+        sig = fn(*[channels if a == "input" else gg if a == "globals" else None for a in an])
+        if not torch.is_tensor(sig):
+            sig = torch.as_tensor(sig)
+        sig = sig.float()
+        if sig.dim() >= 2 and sig.shape[0] == n and sig.shape[1] > 1:
+            sub = [sig[:, c] for c in range(sig.shape[1])]
+        else:
+            sig = sig.squeeze()
+            sub = [sig] if (sig.dim() == 1 and sig.shape[0] == n) else []
+        for col in sub:
+            cols.append(torch.where(torch.isfinite(col), col, torch.zeros_like(col)))
+    return torch.stack(cols, dim=1).cpu().numpy()  # (n, K_raw), un-normalized, fixed order
+
+
+def _check_no_inf(Xm):
+    """NaN is allowed (we median-impute, and declare allow_nan=True), but +/-inf is rejected so the
+    estimator passes sklearn's check_estimators_nan_inf for allow_nan estimators."""
+    if np.isinf(Xm).any():
+        raise ValueError("Input contains infinity or a value too large for dtype('float64').")
+    return Xm
+
+
+def _as_float_matrix(X, cat_cols):
+    """Coerce to float ndarray, ordinal-encoding categorical columns; returns (Xm, cat_mask, cat_maps).
+    cat_maps lets transform() reproduce the *training* category->code mapping (unseen -> nan)."""
+    import pandas as pd
+    import scipy.sparse as sp
+    if sp.issparse(X):
+        raise TypeError("EvoForest-Tab does not support sparse input. Densify it first "
+                        "(e.g. X.toarray()) or set a sparse-aware preprocessor upstream.")
+    if isinstance(X, pd.DataFrame):
+        cols = list(X.columns)
+        cat = [(str(X[c].dtype) in ("category", "object", "bool")) or
+               (cat_cols is not None and (i in cat_cols or c in cat_cols)) for i, c in enumerate(cols)]
+        arrs, maps = [], {}
+        for i, c in enumerate(cols):
+            if cat[i]:
+                cats = list(pd.Categorical(X[c]).categories)
+                maps[i] = {v: k for k, v in enumerate(cats)}
+                arrs.append(X[c].map(maps[i]).to_numpy(dtype=np.float64))
+            else:
+                arrs.append(X[c].to_numpy(dtype=np.float64))
+        return _check_no_inf(np.column_stack(arrs)), np.array(cat), maps
+    Xm = np.asarray(X, dtype=np.float64)
+    cat = np.zeros(Xm.shape[1], bool)
+    if cat_cols is not None:
+        for i in cat_cols:
+            cat[i] = True
+    return _check_no_inf(Xm), cat, {}
+
+
+class TabMapTransformer(TransformerMixin, BaseEstimator):
+    """Inductive EvoForest-Tab feature map: fit channel maps on train, transform any rows -> phi (n, K).
+
+    Parameters: ``genome_path`` (the evolved genome), ``cat_features`` (indices/names; else auto by dtype),
+    ``Dmax`` (feature width cap), ``n_quantiles``.
+    """
+
+    def __init__(self, genome_path=DEFAULT_GENOME, cat_features=None, Dmax=DMAX, n_quantiles=256):
+        self.genome_path = genome_path
+        self.cat_features = cat_features
+        self.Dmax = Dmax
+        self.n_quantiles = n_quantiles
+
+    def __sklearn_tags__(self):
+        tags = super().__sklearn_tags__()
+        tags.input_tags.allow_nan = True          # we median-impute NaN (but reject inf)
+        tags.transformer_tags.preserves_dtype = []  # output is always float32/64, not input dtype
+        return tags
+
+    def _validate(self, X, *, reset):
+        """Numeric inputs go through sklearn's check_array (enforces 2D, rejects complex/1D, allows NaN,
+        sets/checks n_features_in_) so the estimator passes check_estimator. A pandas DataFrame carrying
+        categorical/object columns takes the bespoke path (check_array would reject object dtype)."""
+        import pandas as pd
+        from sklearn.utils.validation import check_array
+        is_df = isinstance(X, pd.DataFrame)
+        has_cat = is_df and any(str(d) in ("object", "category", "bool") for d in X.dtypes)
+        if has_cat or (is_df and self.cat_features is not None):
+            Xv, n = X, X.shape[1]
+        else:
+            Xv = check_array(X, dtype=np.float64, ensure_2d=True, ensure_all_finite="allow-nan",
+                             ensure_min_samples=2 if reset else 1, estimator=self)
+            n = Xv.shape[1]
+        if reset:
+            self.n_features_in_ = n
+        elif n != self.n_features_in_:
+            raise ValueError(f"X has {n} features, but {type(self).__name__} "
+                             f"is expecting {self.n_features_in_} features as input.")
+        return Xv
+
+    def fit(self, X, y=None):
+        X = self._validate(X, reset=True)
+        Xm, cat, self.cat_maps_ = _as_float_matrix(X, self.cat_features)
+        # median-impute (store train medians), drop constant cols, cap to Dmax by variance
+        self.medians_ = np.nanmedian(Xm, axis=0)
+        Xi = np.where(np.isnan(Xm), self.medians_, Xm)
+        keep = Xi.std(0) > 1e-9
+        idx = np.where(keep)[0]
+        if len(idx) > self.Dmax:
+            idx = idx[np.argsort(-Xi[:, idx].std(0))[:self.Dmax]]
+        self.keep_idx_ = idx
+        self.cat_kept_ = cat[idx]
+        Xk = Xi[:, idx]
+        # fit the per-column channel maps
+        self.scaler_x_ = StandardScaler().fit(Xk)
+        self.qt_ = QuantileTransformer(output_distribution="normal",
+                                       n_quantiles=min(self.n_quantiles, len(Xk)), subsample=10 ** 9).fit(Xk)
+        self.freq_maps_ = [{v: c / len(Xk) for v, c in zip(*np.unique(Xk[:, j], return_counts=True))}
+                           for j in range(Xk.shape[1])]
+        F = self._freq(Xk)
+        self.scaler_f_ = StandardScaler().fit(F)
+        self.genome_ = load_genome(self.genome_path)
+        # fix the phi columns + standardization on TRAIN (so transform output is inductive: same width
+        # and scale for any batch, including a single row)
+        raw = _raw_phi(self.genome_, self._channels(X))
+        sd = raw.std(0)
+        self.phi_keep_ = np.where(sd > 1e-9)[0]
+        self.phi_mu_ = raw[:, self.phi_keep_].mean(0)
+        self.phi_sd_ = sd[self.phi_keep_].clip(min=1e-9)
+        self.n_output_features_ = len(self.phi_keep_)
+        return self
+
+    def _freq(self, Xk):
+        F = np.zeros_like(Xk)
+        for j in range(Xk.shape[1]):
+            m = self.freq_maps_[j]
+            F[:, j] = [m.get(v, 0.0) for v in Xk[:, j]]
+        return F
+
+    def _channels(self, X):
+        Xm, _, _ = _as_float_matrix(X, self.cat_features)
+        # reproduce train category codes for DataFrame inputs is handled in _as_float_matrix via dtype;
+        # here we just impute + select the kept columns with train medians.
+        Xi = np.where(np.isnan(Xm), self.medians_[: Xm.shape[1]], Xm)
+        Xk = Xi[:, self.keep_idx_]
+        n, D = Xk.shape
+        Dmax = self.Dmax
+        def pad(a):
+            return np.pad(a, ((0, 0), (0, max(0, Dmax - a.shape[1]))))[:, :Dmax]
+        x = pad(self.scaler_x_.transform(Xk))
+        xrank = pad(self.qt_.transform(Xk))
+        xfreq = pad(self.scaler_f_.transform(self._freq(Xk)))
+        fmask = np.zeros((n, Dmax)); fmask[:, :min(D, Dmax)] = 1.0
+        iscat = np.zeros((n, Dmax)); iscat[:, :min(D, Dmax)] = self.cat_kept_[:min(D, Dmax)].astype(float)
+        t = lambda a: torch.from_numpy(np.nan_to_num(a)).float()
+        return {"x": t(x), "xrank": t(xrank), "x_freq": t(xfreq), "fmask": t(fmask), "is_cat": t(iscat), "Dmax": Dmax}
+
+    def transform(self, X):
+        check_is_fitted(self, "phi_keep_")
+        X = self._validate(X, reset=False)
+        raw = _raw_phi(self.genome_, self._channels(X))[:, self.phi_keep_]
+        return (raw - self.phi_mu_) / self.phi_sd_
+
+    def get_feature_names_out(self, input_features=None):
+        check_is_fitted(self, "n_output_features_")
+        return np.array([f"evoforest_{i}" for i in range(self.n_output_features_)])
+
+
+class TabMapInductiveClassifier(ClassifierMixin, BaseEstimator):
+    """Inductive classifier: EvoForest-Tab feature map -> ridge head. Standard fit->predict (passes the
+    ordinary sklearn contract). Use the transductive ``tabmap.TabMapClassifier`` for the support->query
+    in-context setting; use this for a drop-in sklearn estimator."""
+
+    def __init__(self, genome_path=DEFAULT_GENOME, cat_features=None, Dmax=DMAX, alpha=1.0):
+        self.genome_path = genome_path
+        self.cat_features = cat_features
+        self.Dmax = Dmax
+        self.alpha = alpha
+
+    def __sklearn_tags__(self):
+        tags = super().__sklearn_tags__()
+        tags.input_tags.allow_nan = True
+        return tags
+
+    def fit(self, X, y):
+        if y is None:
+            raise ValueError(f"{type(self).__name__} requires y to be passed, but the target y is None.")
+        y = np.asarray(y)                          # de-wrap _NotAnArray before np.unique
+        self._tf = TabMapTransformer(self.genome_path, self.cat_features, self.Dmax).fit(X)
+        self.classes_ = np.unique(y)
+        self.n_features_in_ = self._tf.n_features_in_
+        self._head = RidgeClassifierCV(alphas=_np.logspace(-2, 4, 13)).fit(self._tf.transform(X), y)
+        return self
+
+    def predict(self, X):
+        check_is_fitted(self, "_head")
+        return self._head.predict(self._tf.transform(X))
+
+    def predict_proba(self, X):
+        """Calibration-free probabilities from the ridge decision function (sigmoid for binary, softmax
+        for multiclass) -- RidgeClassifierCV exposes only decision_function."""
+        check_is_fitted(self, "_head")
+        d = self._head.decision_function(self._tf.transform(X))
+        if d.ndim == 1:                                # binary
+            p = 1.0 / (1.0 + np.exp(-d))
+            return np.column_stack([1.0 - p, p])
+        e = np.exp(d - d.max(1, keepdims=True))
+        return e / e.sum(1, keepdims=True)
+
+
+class TabMapInductiveRegressor(RegressorMixin, BaseEstimator):
+    def __init__(self, genome_path=DEFAULT_GENOME, cat_features=None, Dmax=DMAX, alpha=1.0):
+        self.genome_path = genome_path
+        self.cat_features = cat_features
+        self.Dmax = Dmax
+        self.alpha = alpha
+
+    def __sklearn_tags__(self):
+        tags = super().__sklearn_tags__()
+        tags.input_tags.allow_nan = True
+        return tags
+
+    def fit(self, X, y):
+        from sklearn.utils.validation import column_or_1d
+        y = column_or_1d(y, warn=True)            # warn + ravel on (n,1) y -> check_supervised_y_2d
+        self._tf = TabMapTransformer(self.genome_path, self.cat_features, self.Dmax).fit(X)
+        self.n_features_in_ = self._tf.n_features_in_
+        self._head = RidgeCV(alphas=_np.logspace(-2, 4, 13)).fit(self._tf.transform(X), y)
+        return self
+
+    def predict(self, X):
+        check_is_fitted(self, "_head")
+        return self._head.predict(self._tf.transform(X))
+
+
+# brand-consistent names matching the paper (TabMap* retained as aliases)
+EvoForestTabTransformer = TabMapTransformer
+EvoForestTabInductiveClassifier = TabMapInductiveClassifier
+EvoForestTabInductiveRegressor = TabMapInductiveRegressor

evoforest_tab-0.1.0.dist-info/METADATA

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: evoforest-tab
+Version: 0.1.0
+Summary: Evolved universal tabular feature map + closed-form ridge: an interpretable, training-free, local in-context learner for tabular data.
+License: MIT
+Keywords: tabular,in-context-learning,feature-map,tabpfn,ridge,automl
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=1.13
+Requires-Dist: numpy>=1.21
+Requires-Dist: pyyaml>=5.4
+Provides-Extra: sklearn
+Requires-Dist: scikit-learn>=1.0; extra == "sklearn"
+Provides-Extra: examples
+Requires-Dist: scikit-learn>=1.0; extra == "examples"
+Requires-Dist: pandas>=1.3; extra == "examples"
+Dynamic: license-file
+
+# tabmap — EvoForest-Tab: an evolved universal tabular feature map
+
+`tabmap` is the reference implementation of **EvoForest-Tab** (the EvoForest computation-search framework specialized to tabular data).
+
+`tabmap` is an interpretable, training-free, **local** in-context learner for tabular data: an
+evolved universal feature map `φ: row → ℝᴷ` (16 transform families over rank-gauss, count-encoding,
+and categorical-mask channels) paired with a per-dataset **closed-form Bayesian-ridge head**. Given a
+labeled *support* set and an unlabeled *query* set, it predicts in a single SVD solve — no gradient
+descent, no per-dataset tuning, no GPU. It is competitive with gradient boosting and with the
+published **TabPFN-v2** tabular foundation model, while remaining free to run and fully inspectable.
+
+This repository accompanies the paper *"Evolving a Universal Tabular Feature Map: Interpretable,
+Closed-Form In-Context Learning Competitive with Tabular Foundation Models"* and is **stand-alone**:
+the deployment pipeline (feature map + ridge) depends only on `torch`, `numpy`, and `pyyaml`.
+
+## Install
+```bash
+pip install -e .            # editable; or: pip install .
+# deps: torch, numpy, pyyaml  (+ scikit-learn for the estimator base classes & examples)
+```
+
+## Usage (scikit-learn style)
+```python
+from evoforest_tab import TabMapClassifier, TabMapRegressor
+
+clf = TabMapClassifier(n_estimators=6).fit(X_support, y_support)   # X: ndarray or DataFrame
+proba = clf.predict_proba(X_query)                                  # in-context: query needed to fit φ channels
+pred  = clf.predict(X_query)
+
+reg = TabMapRegressor(n_estimators=6).fit(X_support, y_support)
+yhat = reg.predict(X_query)
+```
+Notes:
+- It is an **in-context** learner: `predict` builds the (label-free, transductive) channels over the
+  pooled support+query rows, so the query rows are needed at prediction time (as with TabPFN).
+- `n_estimators` is the random-feature ensemble size (averaged decorrelated seed-variants of `φ`);
+  `n_estimators=1` is the single map, `6` is the paper default (variance reduction toward the kernel limit).
+- `cat_features=[...]` marks categorical columns (indices or DataFrame names); omitted → auto-detected.
+- No class-count ceiling (unlike TabPFN-v2's ≤10 classes); runs on CPU in milliseconds.
+
+## What's inside
+```
+tabmap/
+  _channels.py   raw rows  -> input channels (col-z, rank-gauss, count-encoding, categorical mask), nan-safe
+  _genome.py     evaluate the evolved genome (champion.yaml) -> feature matrix Phi; seed-variants for the ensemble
+  _ridge.py      closed-form Bayesian-ridge head (evidence-maximized lambda), single SVD solve
+  estimator.py   TabMapClassifier / TabMapRegressor (sklearn API) + K-seed ensemble
+  champion.yaml  the evolved 16-family genome (the deployment artifact)
+examples/quickstart.py
+reproduce/        scripts + cached TabPFN-v2 predictions to reproduce the paper's experiments
+tests/
+```
+
+## Reproducing the paper
+See [`reproduce/README.md`](reproduce/README.md). The cached TabPFN-v2 cloud predictions are included
+so the head-to-head and routing experiments reproduce **without** any API key.
+
+## Contributing this method upstream
+`tabmap` is designed to drop into the tabular ML ecosystem. Best integration targets (most aligned first):
+
+| Repo | Why it fits | Integration |
+|---|---|---|
+| **PriorLabs/tabpfn-extensions** | community extensions around TabPFN; our method is a free/local **complementary** in-context learner and a natural **cost-aware router** companion (route hard datasets to TabPFN, the rest to `tabmap`) | add as an extension module + a routing utility (`sklearn`-compatible) |
+| **scikit-learn-contrib** | `TabMapClassifier`/`TabMapRegressor` already follow the estimator API | publish as a standalone `scikit-learn-contrib` project |
+| **skrub** (ex dirty-cat) | tabular feature engineering / encoders; our channels (rank-gauss, count-encoding) + `φ` are a drop-in `TransformerMixin` featurizer | contribute `TabMapEncoder` (transform-only) |
+| **pyg-team/pytorch-frame** | deep tabular; `φ` is a fixed featurizer usable as an input stem | add as an `encoder`/`stype` transform |
+| **autogluon / TabArena** | leaderboard model implementations | submit `tabmap` as a model for the TabArena living benchmark |
+
+The estimator's sklearn-compatible surface (`fit`/`predict`/`predict_proba`, `get_params`) is the
+contribution-ready API; the transform-only `build_channels`+`build_phi` path serves the encoder use-cases.
+
+
+## Combining with a foundation model (e.g. TabPFN)
+`StackedTabularEnsemble` combines TabMap with any in-context base model (such as TabPFN's client) into a
+single, stronger predictor -- the paper's complementarity result (our map tends to win classification,
+TabPFN regression; combining beats either alone). Three methods: `blend` (50/50), `compwt`
+(label-free, weight each model by its support-cross-validated competence), `meta` (a learned ridge head
+over the models' out-of-fold support predictions; most robust). All are leakage-safe and in-context
+(weights/head fit on support, no query labels).
+
+```python
+from evoforest_tab import TabMapClassifier, StackedTabularEnsemble
+from tabpfn_client import TabPFNClassifier            # or any sklearn-surface in-context model
+
+ens = StackedTabularEnsemble(
+        [TabMapClassifier(n_estimators=6), TabPFNClassifier()],
+        task="classification", method="meta",          # "meta" | "compwt" | "blend"
+      ).fit(X_support, y_support)
+proba = ens.predict_proba(X_query)
+```
+The learned head (`meta`) is robust whether the two models are evenly matched or one dominates; the
+label-free `compwt` is a close, deployable second with no meta-learner. See `examples/combine_tabpfn.py`.
+
+## Citation
+If you use this library, please cite the accompanying paper *"Evolving a Universal Tabular Feature Map:
+Interpretable, Closed-Form In-Context Learning Competitive with Tabular Foundation Models."* (anonymized
+for review; see `../tabular_paper/`).
+
+## License
+MIT (see `LICENSE`).

evoforest_tab-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+evoforest_tab/__init__.py,sha256=hc7UzSxYLKk_L3PYiGlPXlrZJ05-ABKaJIJs_xd3hR4,1413
+evoforest_tab/_channels.py,sha256=f_kp4gHARc7R1q-4WX3lRMBsfav1cFbIS2lz15WRxLc,5181
+evoforest_tab/_genome.py,sha256=GlgktMKeZsDI5sxz7IrI3wzjViOVCnuv12vR4XqpDtM,2454
+evoforest_tab/_module.py,sha256=x90Yg2z5RYnwsFQcH17GkIVwOpUu0P2remP5P594E2o,6750
+evoforest_tab/_ridge.py,sha256=5kWanlIIc72zM7OnzVwyedgYkf5jAWUOg0mL9bhnWJk,1902
+evoforest_tab/champion.yaml,sha256=lXCukeBH_EEKQZium6pgkptlkvg7HevJxvkXWDutDeo,6353
+evoforest_tab/combine.py,sha256=gqjHn50rLlcowiPsJ0T_bfXELfCvF7G21BUT8strM-c,7683
+evoforest_tab/estimator.py,sha256=uDoLhklSbZml1P0I9qcqiqtk1i7ORnWUT0OKcHXcSs8,4214
+evoforest_tab/inductive.py,sha256=-GbZc9yFJ9PhtVKxczRKoBi09f4VqrArOUqUPCnhRdE,13173
+evoforest_tab-0.1.0.dist-info/licenses/LICENSE,sha256=mPdFwLq00cOE_zAvx0jTNZ2Jy2Bl0D1RMu9JmYTXpyQ,1075
+evoforest_tab-0.1.0.dist-info/METADATA,sha256=RELHHMnOhLC7aaZTD-OQLTX4GTwanql-IRL4ultoK4c,6709
+evoforest_tab-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+evoforest_tab-0.1.0.dist-info/top_level.txt,sha256=RNTgLpP5y1b6xVDmwFLAxtrGm1AIBcaT_umBfEA67x4,14
+evoforest_tab-0.1.0.dist-info/RECORD,,

evoforest_tab-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

evoforest_tab-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 the tabmap authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

evoforest_tab-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+evoforest_tab