Skip to contents

Fit a TabICL2 model.

Source: R/tab_icl2_fit.R
tab_icl2.Rd

tab_icl2() applies data to a pre-estimated deep learning model defined by Qu et al (2026). This model emulates Bayesian inference for regression and classification models.

Usage

tab_icl2(x, ...)

# Default S3 method
tab_icl2(x, ...)

# S3 method for class 'data.frame'
tab_icl2(
  x,
  y,
  config = tab_icl2_config(),
  control = tab_icl2_control(),
  model_version = NULL,
  ...
)

# S3 method for class 'matrix'
tab_icl2(
  x,
  y,
  config = tab_icl2_config(),
  control = tab_icl2_control(),
  model_version = NULL,
  ...
)

# S3 method for class 'formula'
tab_icl2(
  formula,
  data,
  config = tab_icl2_config(),
  control = tab_icl2_control(),
  model_version = NULL,
  ...
)

# S3 method for class 'recipe'
tab_icl2(
  x,
  data,
  config = tab_icl2_config(),
  control = tab_icl2_control(),
  model_version = NULL,
  ...
)

Arguments

x

Depending on the context:

  • A data frame of predictors.

  • A matrix of predictors.

  • A recipe specifying a set of preprocessing steps created from recipes::recipe().

...

Not currently used, but required for extensibility.

y

When x is a data frame or matrix, y is the outcome specified as:

  • A data frame with 1 numeric column.

  • A matrix with 1 numeric column.

  • A numeric vector for regression or a factor for classification.

config

A list of model architecture options produced by tab_icl2_config(). Ignored when a pretrained checkpoint is loaded via model_version.

control

A list of inference execution options produced by tab_icl2_control().

model_version

A character string identifying the checkpoint to load. Three forms are accepted:

Registry key

A name from the built-in registry (e.g. "tabicl_classifier_v2"). The file is downloaded once and cached.

HTTPS URL

Any https:// or http:// address pointing to a checkpoint file. The file is downloaded once and cached.

Local file URI

A file:///path/to/model.pt URI. The file must already exist on disk.

When NULL (the default) a randomly initialised model is built from config.

formula

A formula specifying the outcome terms on the left-hand side, and the predictor terms on the right-hand side.

data

When a recipe or formula is used, data is specified as:

  • A rsplit object from rsample package containing both the predictors and the outcome.

Value

A tab_icl2 object with elements:

  • fit: the object containing the model.

  • levels: a character string of class levels (or NULL for regression)

  • t_dim : the dimension of the training set inside the T-shape XY dataset

  • t_predictors : a tibble of training and validation set predictors

  • t_outcome : a tibble of validation set outcome

  • logging : unused

Details

Computing Requirements

This model can be used with or without a graphics processing unit (GPU). However, it is fairly limited when used with a CPU (and no GPU). There might be additional data size limitation warnings with CPU computations, and, understandably, the execution time is much longer. CPU computations can also consume a significant amount of system memory, depending on the size of your data.

GPUs using CUDA (Compute Unified Device Architecture) are most effective. Limited testing with others has shown that GPUs with Metal Performance Shaders (MPS) instructions (e.g., Apple GPUs) have limited utility for these specific computations and might be slower than the CPU for some data sets.

Data

Predictors do not require preprocessing; missing values and factor vectors are allowed.

Model Selection

Selecting a model version

Use the model_version argument to load a specific pretrained checkpoint. Three forms are accepted:


  # Built-in registry key (downloaded and cached automatically)
  mod <- tab_icl2(predictors, outcome,
                  model_version = "tabicl_classifier_v2")

  # Any HTTPS URL (downloaded and cached automatically)
  mod <- tab_icl2(predictors, outcome,
                  model_version = "https://example.com/my_model.pt")

  # Local file via file:// URI
  mod <- tab_icl2(predictors, outcome,
                  model_version = "file:///path/to/model.pt")

Calculations

For the softmax_temperature value, the softmax terms are:


exp(value / softmax_temperature)

A value of softmax_temperature = 1 results in a plain softmax value.

References

Jingang Qu, David Holzmüller, Gaël Varoquaux, Marine Le Morvan. "TabICLv2: A better, faster, scalable, and open tabular foundation model." arXiv preprint arXiv:2602.11139 (2026).

Jingang Qu, David Holzmüller, Gaël Varoquaux, Marine Le Morvan. "TabICL: A Tabular Foundation Model for In-Context Learning on Large Data." arXiv preprint arXiv:2502.05564 (2025).

See also

tab_icl2_config(), tab_icl2_control(), predict.tab_icl_v2()

Examples

predictors <- mtcars[, -1]
outcome <- mtcars[, 1]
mtcars_split <- rsample::initial_split(mtcars)

if (FALSE) { # \dontrun{
if (torch_is_installed() && interactive()) {
 # XY interface
 mod <- tab_icl2(predictors, outcome)
 mod

 # Formula interface
 mod2 <- tab_icl2(mpg ~ ., mtcars_split)
 mod2

 # Recipes interface
 if (rlang::is_installed("recipes")) {
  rec <-
   recipes::recipe(mpg ~ ., mtcars) %>%
   recipes::step_log(disp)

  mod3 <- tab_icl2(rec, mtcars_split)
  mod3
 }
}
} # }