TabICL 2.2 imputation

Impute numeric and categorical targets with pretrained TabICL models through vimpute(). Python is initialized lazily when a model is trained. Install reticulate and python -m pip install 'tabicl[finetune]==2.2.0' 'pandas>=2.1.2' in its Python environment (Python >= 3.10). Checkpoints are downloaded on first use unless model_path and allow_auto_download = FALSE are supplied in learner_params. Each target and iteration fits a separate estimator using only observed target values. By default predictors are passed as a typed pandas data frame: numeric missings remain NaN and factors retain their training-time categorical schema. Python fits and reuses the preprocessing for both training and prediction.

tabiclImpute(
  data,
  considered_variables = names(data),
  finetune = FALSE,
  learner_params = list(),
  imp_var = TRUE,
  ...
)

Arguments

data

A data.frame or data.table.

considered_variables

Columns used for imputation and prediction, as in vimpute(). Other columns are returned unchanged.

finetune

Whether to train the pretrained model on the observed data.

learner_params

Named TabICL learner parameters. Common parameters are device, n_estimators, random_state, model_path, allow_auto_download, python, epochs, learning_rate, and patience. input_type defaults to "dataframe"; "matrix" retains the legacy numeric coding of factors. Unknown factor levels become categorical missings with the default backend, rather than fractional numeric codes. epochs defaults to 5 and sets the maximum fine-tuning epochs; early stopping may finish sooner. For example, use learner_params = list(tabicl2 = list(finetune = TRUE, epochs = 20L)) with vimpute(), or learner_params = list(epochs = 20L) with tabiclImpute(). estimator_params and finetune_params are named lists of additional upstream constructor arguments. n_estimators maps to n_estimators_inference for fine-tuning. tabicl_module optionally supplies an API-compatible backend for testing.

imp_var

Add imputation indicator columns.

...

Additional arguments to vimpute(), including seed, nseq, sequential, predictors, uncert, pmm, edit_rules, and edit_control. The wrapper defaults to one pass and deterministic predictions (uncert = "none", pmm = FALSE).

Value

The imputed data set, as returned by vimpute().

Details

vimpute(method = "tabicl2") uses the same learners. They support PMM and the other uncertainty mechanisms of vimpute(). Fine-tuning adapts pretrained weights on each target's observed data; it may substantially increase runtime. Python model objects must be recreated in each R process.

Examples

if (FALSE) { # \dontrun{
tabiclImpute(sleep, finetune = TRUE,
  learner_params = list(device = "cpu", epochs = 5L))
vimpute(sleep, method = "tabicl2",
  learner_params = list(tabicl2 = list(finetune = FALSE)))
} # }