% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/TabPFN-fit.R
\name{tab_pfn}
\alias{tab_pfn}
\alias{tab_pfn.default}
\alias{tab_pfn.data.frame}
\alias{tab_pfn.matrix}
\alias{tab_pfn.formula}
\alias{tab_pfn.recipe}
\title{Fit a TabPFN model.}
\usage{
tab_pfn(x, ...)

\method{tab_pfn}{default}(x, ...)

\method{tab_pfn}{data.frame}(
  x,
  y,
  num_estimators = 8L,
  softmax_temperature = 0.9,
  balance_probabilities = FALSE,
  average_before_softmax = FALSE,
  training_set_limit = 10000,
  version = NULL,
  control = control_tab_pfn(),
  ...
)

\method{tab_pfn}{matrix}(
  x,
  y,
  num_estimators = 8L,
  softmax_temperature = 0.9,
  balance_probabilities = FALSE,
  average_before_softmax = FALSE,
  training_set_limit = 10000,
  version = NULL,
  control = control_tab_pfn(),
  ...
)

\method{tab_pfn}{formula}(
  formula,
  data,
  num_estimators = 8L,
  softmax_temperature = 0.9,
  balance_probabilities = FALSE,
  average_before_softmax = FALSE,
  training_set_limit = 10000,
  version = NULL,
  control = control_tab_pfn(),
  ...
)

\method{tab_pfn}{recipe}(
  x,
  data,
  num_estimators = 8L,
  softmax_temperature = 0.9,
  balance_probabilities = FALSE,
  average_before_softmax = FALSE,
  training_set_limit = 10000,
  version = NULL,
  control = control_tab_pfn(),
  ...
)
}
\arguments{
\item{x}{Depending on the context:
\itemize{
\item A \strong{data frame} of predictors.
\item A \strong{matrix} of predictors.
\item A \strong{recipe} specifying a set of preprocessing steps
created from \code{\link[recipes:recipe]{recipes::recipe()}}.
}}

\item{...}{Not currently used, but required for extensibility.}

\item{y}{When \code{x} is a \strong{data frame} or \strong{matrix}, \code{y} is the outcome
specified as:
\itemize{
\item A \strong{data frame} with 1 numeric column.
\item A \strong{matrix} with 1 numeric column.
\item A numeric \strong{vector} for regression or a \strong{factor} for classification.
}}

\item{num_estimators}{An integer for the ensemble size. Default is \code{8L}.}

\item{softmax_temperature}{An adjustment factor that is a divisor in the
exponents of the softmax function (see Details below). Defaults to 0.9.}

\item{balance_probabilities}{A logical to adjust the prior probabilities in
cases where there is a class imbalance. Default is \code{FALSE}. Classification
only.}

\item{average_before_softmax}{A logical. For cases where
\code{num_estimators > 1}, should the average be done before using the softmax
function or after? Default is \code{FALSE}.}

\item{training_set_limit}{An integer greater than 2L (and possibly \code{Inf})
that can be used to keep the training data within the limits of the
data constraints imposed by the Python library.}

\item{version}{A character string for the model version (e.g., \code{"v2"},
\code{"v2.5"}). When \code{NULL} (the default), the Python library's current default
version is used. When set, the model is initialized via
\code{create_default_for_version()} with the corresponding \code{ModelVersion} enum
value.}

\item{control}{A list of options produced by \code{\link[=control_tab_pfn]{control_tab_pfn()}}.}

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

\item{data}{When a \strong{recipe} or \strong{formula} is used, \code{data} is specified as:
\itemize{
\item A \strong{data frame} containing both the predictors and the outcome.
}}
}
\value{
A \code{tab_pfn} object with elements:
\itemize{
\item \code{fit}: the python object containing the model.
\item \code{levels}: a character string of class levels (or NULL for regression)
\item \code{training}: a vector with the training set dimensions.
\item \code{logging}: any R or python messages produced by the computations.
\item \code{blueprint}: am object produced by \code{\link[hardhat:mold]{hardhat::mold()}} used to process
new data during prediction.
}
}
\description{
\code{tab_pfn()} applies data to a pre-estimated deep learning model defined by
Hollmann \emph{et al} (2025). This model emulates Bayesian inference for
regression and classification models.
}
\details{
\subsection{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.
}

\subsection{License Requirements}{

Starting with version 2.5, using TabPFN requires accepting the model license
and obtaining a token from PriorLabs. Each model version (v2.5, v2.6, etc.)
has its own license that must be accepted individually.

To set up access:
\enumerate{
\item Visit \url{https://ux.priorlabs.ai} and create an
account.
\item Go to the \strong{License} tab and accept the license for each model version
you intend to use.
\item Obtain your token from your account page.
\item Set the \code{TABPFN_TOKEN} environment variable. The easiest way is to add it
to your \code{.Renviron} file:
}

\preformatted{
TABPFN_TOKEN=your_token_value
}

The \pkg{usethis} function \code{edit_r_environ()} can be very helpful here.

Users who already have \code{TABPFN_TOKEN} set can use TabPFN v2 without any
additional steps.
}

\subsection{Python Installation}{

You will need a working Python virtual environment with the correct packages
to use these modeling functions.

There are at least two ways to proceed.
\subsection{Ephemeral \code{uv} Install}{

The first approach, which we \emph{strongly suggest}, is to simply load this
package and attempt to run a model. This will prompt \pkg{reticulate} to
create an ephemeral environment and automatically install the required
packages. That process would look like this:

\preformatted{
  > library(tabpfn)
  >
  > predictors <- mtcars[, -1]
  > outcome <- mtcars[, 1]
  >
  > # XY interface
  > mod <- tab_pfn(predictors, outcome)
  Downloading uv...Done!
  Downloading cpython-3.12.12 (download) (15.9MiB)
   Downloading cpython-3.12.12 (download)
  Downloading setuptools (1.1MiB)
  Downloading scikit-learn (8.2MiB)
  Downloading numpy (4.9MiB)

  <downloading and installing more packages>

   Downloading llvmlite
   Downloading torch
  Installed 58 packages in 350ms
  > mod
  TabPFN Regression Model

  Training set
  i 32 data points
  i 10 predictors
}

The location of the environment can be found at
\code{tools::R_user_dir("reticulate", "cache")}.

See the documentation for \code{\link[reticulate:py_require]{reticulate::py_require()}} to learn more about this
method.
}

\subsection{Manually created \code{venv} Virtual Environment}{

Alternatively, you can use the functions in the \pkg{reticulate} package to
create a virtual environment and install the required Python packages there.
An example pattern is:

\preformatted{
  library(reticulate)

  venv_name <- "r-tabpfn"    # exact name can be different
  venv_seed_python <-
    virtualenv_starter(">=3.11,<3.14") %||% install_python()

  virtualenv_create(
    envname = venv_name,
    python = venv_seed_python,
    packages = c("numpy", "tabpfn")
  )
}

Once you have that virtual environment installed, you can declare it as your
preferred Python installation with \code{use_virtualenv()}. (You must do this
before reticulate has initialized Python, i.e., before attempting to use
\pkg{tabpfn}):

\preformatted{
  reticulate::use_virtualenv("r-tabpfn")
}
}

}

\subsection{Data}{

Be default, there are limits to the training data dimensions:
\itemize{
\item Version 2.0: number of training set samples (10,000) and, the number of
predictors (500). There is an unchangeable limit to the number of classes
(10).
\item Version 2.5: number of training set samples (50,000) and, the number of
predictors (2,000). There is an unchangeable limit to the number of classes
(10).
}

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

\subsection{Model Selection}{

By default, TabPFN uses the Python library's current default model version.
There are two ways to override this.
\subsection{Selecting a model version}{

Use the \code{version} argument to select a specific released model version. For
example:

\preformatted{
  # Use version 2.0
  mod <- tab_pfn(predictors, outcome, version = "v2")

  # Use version 2.5
  mod <- tab_pfn(predictors, outcome, version = "v2.5")
}
}

\subsection{Pointing to a local model file}{

If you have a model file on disk (e.g., downloaded for offline use), pass
its path via \code{control_tab_pfn(model_path = ...)}:

\preformatted{
  ctrl <- control_tab_pfn(model_path = "/path/to/model_file.ckpt")
  mod  <- tab_pfn(predictors, outcome, control = ctrl)
}

Note that \code{version} and \code{model_path} are mutually exclusive: if \code{version}
is set, it overwrites any \code{model_path} supplied through \code{control}.
}

}

\subsection{Calculations}{

For the \code{softmax_temperature} value, the softmax terms are:

\preformatted{
exp(value / softmax_temperature)
}

A value of \code{softmax_temperature = 1} results in a plain softmax value.
}
}
\examples{
predictors <- mtcars[, -1]
outcome <- mtcars[, 1]

\dontrun{
if (is_tab_pfn_installed() & interactive()) {
 # XY interface
 mod <- tab_pfn(predictors, outcome)

 # Formula interface
 mod2 <- tab_pfn(mpg ~ ., mtcars)

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

  mod3 <- tab_pfn(rec, mtcars)
  mod3
 }
}
}

}
\references{
Hollmann, Noah, Samuel Müller, Lennart Purucker, Arjun Krishnakumar, Max
Körfer, Shi Bin Hoo, Robin Tibor Schirrmeister, and Frank Hutter.
"Accurate predictions on small data with a tabular foundation model."
\emph{Nature} 637, no. 8045 (2025): 319-326.

Hollmann, Noah, Samuel Müller, Katharina Eggensperger, and Frank Hutter.
"Tabpfn: A transformer that solves small tabular classification problems in
a second." \emph{arXiv preprint} arXiv:2207.01848 (2022).

Müller, Samuel, Noah Hollmann, Sebastian Pineda Arango, Josif Grabocka, and
Frank Hutter. "Transformers can do Bayesian inference." \emph{arXiv preprint}
arXiv:2112.10510 (2021).
}
\seealso{
\code{\link[=control_tab_pfn]{control_tab_pfn()}}, \code{\link[=predict.tab_pfn]{predict.tab_pfn()}}
}
