Fit the TabPFN-v2 in-context discriminator (freeze the training context)

Freezes the training context for TabPFN-v2 in-context classification. The training matrix is mapped to the per-sample robust CLR over the frozen feature universe (colnames(X_train)); if the context exceeds hp$max_context rows it is reduced to a deterministic, seeded, class-stratified subsample. A TabPFN-v2 (ungated ModelVersion.V2) classifier is constructed and fit() on that frozen rCLR context (which, for TabPFN, simply loads the context into the model – no gradient training). The transformer training context is cached once in float32 on CPU and reused on every scoring device. The cache is included in the state fingerprint. Inference uses float32, math attention, fixed training preprocessing and a fixed memory-saving policy on CPU and CUDA. These settings are recorded in inference_settings. The frozen R-side state needed to reproduce scores (the rCLR context, labels, feature universe, class order, device/config, hp) is stored on the model; the live python classifier is also kept for scoring but is included in the deterministic Python state fingerprint. TabPFN-v2 is applied to the full rCLR feature universe; cohorts with $>500$ features, including approximately 2540-2565-feature high-plex miRNA panels, exceed TabPFN's nominal 500-feature ceiling, so its documented ignore_pretraining_limits override is enabled. Under the pinned ModelVersion.V2 preprocessor path (tabpfn 8.0.7) the per-estimator feature-subsampling threshold is 1,000,000 (the 500-feature random-subspace reduction is the separate V2.5 preset, which is not used here), so TabPFN-v2 ingests the full feature set directly and is run outside its nominal $\le 500$-feature pretraining regime. No per-estimator feature subsampling is introduced (the ensemble subsample indices are all empty), so scoring stays deterministic and exactly row-equivariant. The override also lifts the CPU $>1000$-sample guard (a compute guard, not a numeric change). This matches how the sibling in-context foundation models TabICL and TabDPT are run on the full representation and keeps the comparison apples-to-apples with the rCLR baseline; a leakage-safe in-regime top-500 feature reduction is evaluated as a companion sensitivity analysis (the prespecified out-of-regime control).

Usage

fit_tabpfn(X_train, y_train, meta_train = NULL, hp = list())

Arguments

X_train: Numeric matrix (samples $\times$ features) of non-negative abundances with unique, non-empty feature names (colnames).
y_train: Numeric / integer 0/1 labels (1 = case), length nrow(X_train), with at least one case and one control.
meta_train: Optional per-sample metadata. Accepted for interface uniformity and otherwise ignored.
hp: Optional list of hyperparameters. Allowed fields: device ("cpu" (default), "cuda", or "auto"; "cuda" / "auto" fall back to CPU when no GPU is available), n_estimators (TabPFN ensemble size, positive integer, default 8L), max_context (row cap on the frozen context, integer $\ge 2$, default 4096L; larger contexts are seeded class-stratified subsampled), min_features (feature-overlap floor at scoring, positive integer, default 3L), seed (integer; default 42L), and score_batch (benchmark-only batched scoring flag, logical, default FALSE).

Value

Object of class tabpfn_model: a list with context_rclr (frozen rCLR context matrix), context_y, feature_universe, classes, case_col, n_context, device (resolved), model_version ("v2"), ignore_pretraining_limits (TRUE), hp, and the live python classifier clf (included by content in the state fingerprint).

References

Hollmann N, et al. (2025) Accurate predictions on small data with a tabular foundation model. Nature 637:319-326.

Examples

if (FALSE) { # \dontrun{
set.seed(1)
n <- 120; p <- 20; k <- 6
L <- matrix(stats::rnorm(n * p, 4, 0.5), nrow = n,
            dimnames = list(NULL, paste0("miR-", seq_len(p))))
y <- rep(c(0, 1), each = n / 2)
L[y == 1, seq_len(k)] <- L[y == 1, seq_len(k)] + 1.2
X <- exp(L)
model <- fit_tabpfn(X, y)
score_tabpfn(model, X[1, , drop = FALSE])
} # }