TabPFNRegressor output_type Explained: mean, median, mode, quantiles, and full Compared

TabPFNRegressor's output_type parameter controls whether the predict() method returns a simple point estimate (mean, median, or mode), a list of quantile arrays for uncertainty quantification, or a complete dictionary containing raw logits and the full predictive distribution.

The output_type parameter in PriorLabs/TabPFN defines how the TabPFNRegressor converts internal model logits into human-readable predictions. Located in src/tabpfn/regressor.py, this parameter offers five distinct options that trade off computational simplicity against information richness. Understanding these options allows you to extract everything from quick point estimates to full probabilistic distributions for uncertainty quantification.

What Each output_type Returns

The output_type parameter is defined as a Literal type in src/tabpfn/regressor.py (lines 33-42) and supports "mean", "median", "mode", "quantiles", "main", and "full". Each option materializes the model's internal bar-distribution differently.

mean, median, and mode

These three options return a one-dimensional np.ndarray containing a scalar prediction per sample.

• "mean": Returns the expected value (average) of the predicted distribution. This is the default behavior and corresponds to standard regression predictions.
• "median": Returns the 50th percentile (median) of the distribution, offering robustness against asymmetric or skewed predictive densities.
• "mode": Returns the most probable value (peak density) of the distribution, useful when the predictive distribution is multimodal.

According to the source code implementation around lines 80-108, these point estimates are computed by the _logits_to_output helper function, which translates discrete bar probabilities into continuous target-space values.

quantiles

When output_type="quantiles", the method returns a list of np.ndarray objects rather than a single array. By default, the quantiles are [0.1, 0.2, ..., 0.9], though you can specify custom quantiles via the quantiles parameter in predict().

Each array in the list corresponds to one quantile level and has the same shape (n_samples,). This option is essential for constructing prediction intervals and assessing aleatoric uncertainty without assuming a Gaussian error distribution.

full and main

These dictionary-returning options provide comprehensive access to the model's internal state:

• "main": Returns a MainOutputDict containing keys "mean", "median", "mode", and "quantiles". This bundles all point estimates and quantile arrays into a single structure.
• "full": Returns a FullOutputDict that includes everything in "main" plus:
  • "criterion": The FullSupportBarDistribution object describing the raw-space target distribution.
  • "logits": The raw torch.Tensor logits before conversion to the target space.

As implemented in src/tabpfn/regressor.py (lines 1050-1070), selecting "full" or "main" triggers separate calls to _logits_to_output for each sub-output type, then aggregates them into the final dictionary.

Internal Implementation: From Logits to Predictions

Inside TabPFNRegressor.predict(), the conversion from model outputs to user-facing predictions happens through the _logits_to_output helper. The relevant logic (lines 1050-1070) handles the branching based on output_type:

if output_type in ["full", "main"]:
    mean_out = logit_to_output(output_type="mean")
    median_out = logit_to_output(output_type="median")
    mode_out = logit_to_output(output_type="mode")
    quantiles_out = logit_to_output(output_type="quantiles")
    main_outputs = MainOutputDict(
        mean=mean_out, median=median_out, mode=mode_out, quantiles=quantiles_out
    )
    if output_type == "full":
        return FullOutputDict(
            **main_outputs,
            criterion=self.raw_space_bardist_,
            logits=logits
        )
    return main_outputs

For single-output types ("mean", "median", "mode"), the function returns immediately after the first conversion. For "quantiles", it returns the list of arrays directly. The "full" option is the only one that exposes the underlying criterion (the bar distribution object) and the raw logits tensor, enabling custom post-processing or research analysis.

Handling Constant Targets

The source code includes an optimization for constant targets (lines 1198-1220). When y contains a single unique value, _handle_constant_target creates synthetic outputs that respect the requested output_type without running the full forward pass:

if output_type in _OUTPUT_TYPES_BASIC:
    return constant_prediction
if output_type == "quantiles":
    return [np.copy(constant_prediction) for _ in quantiles]

# main & full return full dicts with dummy logits/criterion

This ensures API consistency even when the model bypasses actual inference.

Practical Code Examples

The following example demonstrates all output_type variations using the same fitted model:

import numpy as np
from tabpfn import TabPFNRegressor
from sklearn.datasets import make_regression

# Train a regressor

X, y = make_regression(n_samples=100, n_features=10, random_state=0)
model = TabPFNRegressor()
model.fit(X, y)

# 1. Point estimates

pred_mean = model.predict(X, output_type="mean")
pred_median = model.predict(X, output_type="median")
pred_mode = model.predict(X, output_type="mode")

# 2. Uncertainty quantification via quantiles

quantiles = model.predict(
    X, 
    output_type="quantiles", 
    quantiles=[0.05, 0.5, 0.95]
)
q05, q50, q95 = quantiles

# 3. Full diagnostic output

full_out = model.predict(X, output_type="full")
print(full_out["mean"][:5])           # Same as pred_mean

print(full_out["logits"].shape)       # Raw model outputs (n_samples, n_bins)

print(full_out["criterion"].borders)  # Distribution bin edges

All calls use the same underlying forward pass; only the final aggregation step changes based on output_type.

Summary

• "mean", "median", and "mode" return single np.ndarray point estimates representing the average, 50th percentile, and most likely value respectively.
• "quantiles" returns a list of arrays allowing custom uncertainty intervals without parametric assumptions.
• "main" bundles mean, median, mode, and quantiles into a single dictionary.
• "full" provides the complete internal state including raw logits and the FullSupportBarDistribution criterion for advanced analysis.
• The implementation in src/tabpfn/regressor.py handles constant targets specially (lines 1198-1220) while routing all other cases through _logits_to_output (lines 1050-1070).

Frequently Asked Questions

What is the default output_type in TabPFNRegressor?

The default is "mean", which returns the expected value of the predictive distribution as a NumPy array. This maintains compatibility with standard scikit-learn regressors that expect point predictions.

When should I use full instead of main?

Use "full" when you need access to the raw model logits or the bar-distribution criterion for custom post-processing, debugging, or research. The "main" option suffices for most production use cases requiring only statistical aggregates.

Can I specify custom quantiles with output_type="quantiles"?

Yes. Pass a list of floats (e.g., quantiles=[0.1, 0.5, 0.9]) to the quantiles parameter in predict(). The default is [0.1, 0.2, ..., 0.9]. Each value in your list generates a corresponding array in the returned list.

Does output_type affect inference speed?

No. The forward pass computes the full logit distribution regardless of output_type. The parameter only controls how much of that information gets converted and returned. However, returning "full" involves slightly higher memory overhead due to the inclusion of logits and criterion objects.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}