orbital: Turn tidymodels objects into orbital objects

In orbital: Predict with 'tidymodels' Workflows in Databases

Turn tidymodels objects into orbital objects

Description

Fitted workflows, parsnip objects, and recipes objects can be turned into an orbital object that contain all the information needed to perform predictions.

Usage

orbital(x, ..., prefix = ".pred", type = NULL, separate_trees = FALSE)

Arguments

x	A fitted workflow, parsnip, or recipes object.
...	Not currently used.
prefix	A single string, specifies the prediction naming scheme. If x produces a prediction, tidymodels standards dictate that the predictions will start with .pred. This is not a valid name for some data bases.
type	A vector of strings, specifies the prediction type. Regression models allow for "numeric" and classification models allow for "class" and "prob". Multiple values are allowed to produce hard and soft predictions for classification models. Defaults to NULL which defaults to "numeric" for regression models and "class" for classification models.
separate_trees	A single logical. For tree ensemble models (xgboost, lightgbm, catboost, ranger, randomForest, aorsf, partykit), should each tree be output as a separate expression? This can improve performance when predicting in databases by allowing parallel evaluation of trees. Defaults to FALSE. See vignette("separate-trees") for details.

Details

An orbital object contains all the information that is needed to perform predictions. This makes the objects substantially smaller than the original objects. The main downside with this object is that all the input checking has been removed, and it is thus up to the user to make sure the data is correct.

The printing of orbital objects reduce the number of significant digits for easy viewing, the can be changes by using the digits argument of print() like so print(orbital_object, digits = 10). The printing likewise truncates each equation to fit on one line. This can be turned off using the truncate argument like so print(orbital_object, truncate = FALSE).

Full list of supported models and recipes steps can be found here: vignette("supported-models").

These objects will not be useful by themselves. They can be used to predict() with, or to generate code using functions such as orbital_sql() or orbital_dt().

Value

An orbital object.

Numeric precision

An orbital object holds its equations as text, so every number a model carries is written out as a decimal with 17 significant digits and read back when the object is used. On most builds of R that round-trip is exact.

It is not exact on builds where capabilities("long.double") is FALSE, which includes some macOS builds. R accumulates the digits of a number it is reading into a long double, and without one to accumulate into it can land one unit in the last place away from the number that was written. Equations built on such a build are still written correctly; it is reading them back that loses the last bit.

For nearly every model this is orders of magnitude below the model's own uncertainty and can be ignored. It matters for trees that split on a value computed from several columns rather than on a raw column, such as the oblique forests of rand_forest() with the "aorsf" engine. Those splits sit at combinations realized by training rows, so the comparison at a split is an exact tie for many rows, and the smallest possible difference is enough to send a row down the other branch. Its prediction then moves by the distance between two leaves rather than by a rounding error, and predictions can differ from predict() on the original fit for a meaningful share of rows.

Examples

library(workflows)
library(recipes)
library(parsnip)

rec_spec <- recipe(mpg ~ ., data = mtcars) |>
  step_normalize(all_numeric_predictors())

lm_spec <- linear_reg()

wf_spec <- workflow(rec_spec, lm_spec)

wf_fit <- fit(wf_spec, mtcars)

orbital(wf_fit)

# Also works on parsnip object by itself
fit(lm_spec, mpg ~ disp, data = mtcars) |>
  orbital()

# And prepped recipes
prep(rec_spec) |>
  orbital()

orbital documentation built on Sept. 5, 2026, 1:07 a.m.