Package {tidypredict}

Title:	Run Predictions Inside the Database
Version:	1.2.0
Description:	It parses a fitted 'R' model object, and returns a formula in 'Tidy Eval' code that calculates the predictions. It works with several databases back-ends because it leverages 'dplyr' and 'dbplyr' for the final 'SQL' translation of the algorithm. Dozens of model classes are supported; see the "Supported models" article at https://tidypredict.tidymodels.org/articles/models.html for the current list.
License:	MIT + file LICENSE
URL:	https://tidypredict.tidymodels.org, https://github.com/tidymodels/tidypredict
BugReports:	https://github.com/tidymodels/tidypredict/issues
Depends:	R (≥ 4.1)
Imports:	cli, dplyr (≥ 0.7), generics, jsonlite, knitr, lifecycle, purrr, rlang (≥ 1.1.1), tibble, tidyr, utils
Suggests:	agua, aorsf, baguette, bonsai, C50, covr, Cubist (≥ 0.5.1), data.table, dbarts, DBI, dbplyr, discrim, earth (≥ 5.1.2), glmnet, h2o, kernlab, klaR, LiblineaR, lightgbm, MASS, mboost, mda, methods, mixOmics, mlbench, modeldata, naivebayes, nnet, nycflights13, parsnip, partykit, plsmod, quantreg, randomForest, ranger (≥ 0.14.1), RhpcBLASctl, rmarkdown, rpart (≥ 4.1.0), RSQLite, rules, sda, sparsediscrim, survival, testthat (≥ 3.2.0), withr, xgboost, xrf, yaml
VignetteBuilder:	knitr
Config/Needs/website:	tidyverse/tidytemplate
Config/roxygen2/version:	8.0.0
Config/testthat/edition:	3
Config/usethis/last-upkeep:	2026-08-19
Encoding:	UTF-8
NeedsCompilation:	no
Packaged:	2026-09-03 20:44:09 UTC; emilhvitfeldt
Author:	Emil Hvitfeldt [aut, cre], Edgar Ruiz [aut], Max Kuhn [aut], Posit Software, PBC [cph, fnd]
Maintainer:	Emil Hvitfeldt <emil.hvitfeldt@posit.co>
Repository:	CRAN
Date/Publication:	2026-09-04 05:10:02 UTC

tidypredict: Run Predictions Inside the Database

Description

It parses a fitted 'R' model object, and returns a formula in 'Tidy Eval' code that calculates the predictions. It works with several databases back-ends because it leverages 'dplyr' and 'dbplyr' for the final 'SQL' translation of the algorithm. Dozens of model classes are supported; see the "Supported models" article at https://tidypredict.tidymodels.org/articles/models.html for the current list.

Author(s)

Maintainer: Emil Hvitfeldt emil.hvitfeldt@posit.co (ORCID)

Authors:

• Emil Hvitfeldt emil.hvitfeldt@posit.co (ORCID)

• Edgar Ruiz edgar@posit.co

• Max Kuhn max@posit.co (ORCID)

Other contributors:

• Posit Software, PBC (ROR) [copyright holder, funder]

See Also

Useful links:

• https://tidypredict.tidymodels.org

• https://github.com/tidymodels/tidypredict

• Report bugs at https://github.com/tidymodels/tidypredict/issues

Build case_when expression from nodes with predictions and paths

Description

Shared helper for building tree expressions used by ranger and randomForest classification extractors.

Usage

.build_case_when_tree(nodes)

Arguments

Build linear predictor expression from coefficient names and values

Description

Shared helper for building linear predictor strings from coefficients. Used by orbital package for glmnet models.

Usage

.build_linear_pred(coef_names, coef_values)

Arguments

Build nested case_when expression from tree info

Description

Shared helper for building nested tree expressions. This is the nested equivalent of .build_case_when_tree().

Usage

.build_nested_case_when_tree(tree_info)

Arguments

Extract comprehensive tree info for C5.0 models

Description

Returns tree structure in format needed by nested case_when generator. For use in orbital package.

Usage

.c50_tree_info_full(model)

Arguments

Extract class probability trees for bagger models

Description

Returns one list of per-tree expressions for each outcome level. For use in orbital package.

Usage

.extract_bagger_classprob(model)

Arguments

Extract regression trees for bagger models

Description

For use in orbital package.

Usage

.extract_bagger_trees(model)

Arguments

Extract the outcome scaling of a bart model

Description

For use in orbital package. The trees of .extract_bart_trees() predict on the scale that dbarts::bart() centers and scales the outcome to. Their sum, divided by n_draws and multiplied by y_scale, plus y_center, gives the fitted value.

Usage

.extract_bart_scaling(model)

Arguments

Extract the trees of a bart model

Description

For use in orbital package.

Usage

.extract_bart_trees(model)

Arguments

Extract comprehensive tree info for partykit models

Description

Returns tree structure in format needed by nested case_when generator. For use in orbital package.

Usage

.partykit_tree_info_full(model)

Arguments

Extract comprehensive tree info for rpart models

Description

Returns tree structure in format needed by nested case_when generator. For use in orbital package.

Usage

.rpart_tree_info_full(model)

Arguments

Checks that the formula can be parsed

Description

Uses an S3 method to check that a given formula can be parsed based on its class. It currently scans for contrasts that are not supported and in-line functions. (e.g: lm(wt ~ as.factor(am))). Since this function is meant for function interaction, as opposed to human interaction, a successful check is silent.

Usage

acceptable_formula(model)

Arguments

Value

NULL (invisibly) when the model's formula can be parsed, or an error when it cannot.

Examples

model <- lm(mpg ~ wt, mtcars)
acceptable_formula(model)

Prepares parsed model object

Description

Prepares parsed model object

Usage

as_parsed_model(x)

Arguments

Value

The parsed model with its parsed_model and ⁠pm_*⁠ classes set.

Examples

pm <- parse_model(lm(mpg ~ wt, data = mtcars))
as_parsed_model(pm)

Build a nested case_when expression for a single node

Description

Build a nested case_when expression for a single node

Usage

build_nested_node(node_id, tree_info, missing = "default")

Arguments

Build a split condition expression for nested trees (left branch)

Description

Build a split condition expression for nested trees (left branch)

Usage

build_nested_split_condition(split)

Arguments

Deprecated model extractors

Description

These functions have been replaced by generics with documented return shapes. See tidypredict_extractors.

Usage

.extract_xgb_trees(model)

.extract_lgb_trees(model)

.extract_catboost_trees(model)

.extract_rf_trees(model)

.extract_ranger_trees(model)

.extract_rf_classprob(model)

.extract_ranger_classprob(model)

.extract_rpart_classprob(model)

.extract_partykit_classprob(model)

.extract_earth_multiclass(model)

.extract_glmnet_multiclass(model, penalty = NULL)

Arguments

Value

The same values these functions have always returned. Note that tidypredict_class_exprs() returns language objects where .extract_earth_multiclass() and .extract_glmnet_multiclass() return strings.

Generate trees

Description

Each tree is generated as a flat tree with each node being a seperate part of the case when. This means that the following tree:

Usage

generate_case_when_trees(parsedmodel, default = TRUE)

Details

        +-----+
   +----|x > 0|----+
   |    +-----+    |
   v               v

+——+ +——–+ +–|y < 20|–+ +–|z <= 10 |–+ | +——+ | | +——–+ | v v v v a b c d

will be turned into the following case_when() statement.

case_when(
  x >  0 & y <  20 ~ "a",
  x >  0 & y >= 20 ~ "b",
  x <= 0 & z <= 10 ~ "c",
  x <= 0 & z >  10 ~ "d"
)

instead of a nested case_when()s' like this

case_when(
  x >  0 ~ case_when(
             y <  20 ~ "a",
             y >= 10 ~ "b"
           ),
  x <= 0 ~ case_when(
             z <= 10 ~ "c",
             z >  10 ~ "d"
           )
)

The functions in this file generates these tree. generate_case_when_tree() generates a single tree with generate_case_when_trees() being a convinience wrapper for multiple trees.

generate_tree_node() generates the expressions for each a single ndoe in the tree, where generate_tree_nodes() is a convinience wrapper for calculating all notes.

Generate nested case_when for a tree

Description

Generate nested case_when for a tree

Usage

generate_nested_case_when_tree(tree_info, missing = c("default", "na", "left"))

Arguments

Construct a single node of a tree

Description

Construct a single node of a tree

Usage

generate_tree_node(node, calc_mode = "")

Arguments

Knit print method for test predictions results

Description

Knit print method for test predictions results

Usage

## S3 method for class 'tidypredict_test'
knit_print(x, ...)

Converts an R model object into a parsed model

Description

Parses a fitted R model's structure and extracts the components needed to create a dplyr formula for prediction. The parsed model can be serialized (e.g., saved to YAML) and later used to generate predictions without the original model object.

Usage

parse_model(model)

Arguments

Value

A parsed model object with class parsed_model and a model-specific subclass (e.g., pm_xgb, pm_tree, pm_regression). The object contains:

• ⁠$general⁠: List with model metadata including model (model type), type (used for S3 dispatch), version (parsed model format version), and model-specific parameters.

• Model-specific fields containing coefficients, tree structures, etc.

Parsed model versions

The ⁠$general$version⁠ field indicates the parsed model format:

• Version 1: Original format. Linear models store coefficients in a data frame. Tree models use flat case_when() expressions where all leaf conditions are at the same level.

• Version 2: Improved coefficient storage for linear models (lm, earth). Tree models still use flat case_when().

• Version 3: Current format. Tree models (rpart, ranger, randomForest, xgboost, lightgbm, catboost, partykit) use nested case_when() expressions that mirror the tree structure. This produces more efficient SQL and R code because conditions are evaluated hierarchically rather than checking all leaf paths.

When loading a parsed model saved with an older version, tidypredict automatically uses the appropriate formula builder for backwards compatibility.

Model types

Each parsed model has a type that determines the S3 class used for dispatch:

• pm_regression: Linear models (lm, glm, earth, glmnet)

• pm_tree: Single trees and forests (rpart, partykit, ranger, randomForest, cubist)

• pm_xgb: XGBoost gradient boosting models

• pm_lgb: LightGBM gradient boosting models

• pm_catboost: CatBoost gradient boosting models

• pm_bart: BART models

• pm_naive_bayes: Naive Bayes models

• pm_nnet: Neural network models

• pm_multiclass_regression: Multiclass regression models

• pm_nullmodel_classification: Null model classification

This list is not exhaustive; new model types are added as support grows.

Examples

library(dplyr)
df <- mutate(mtcars, cyl = paste0("cyl", cyl))
model <- lm(mpg ~ wt + cyl * disp, offset = am, data = df)
parse_model(model)

Turn a path object into an expression

Description

Turn a path object into an expression

Usage

path_formula(x)

Arguments

Turn a path object into a combined expression

Description

Turn a path object into a combined expression

Usage

path_formulas(path)

Arguments

print method for test predictions results

Description

print method for test predictions results

Usage

## S3 method for class 'tidypredict_test'
print(x, ...)

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

generics

tidy()

Set categorical feature mappings for CatBoost model

Description

CatBoost stores categorical features as hash values internally. This function establishes the mapping between hash values and category names by examining a data frame with the same factor columns used during training.

Usage

set_catboost_categories(parsed_model, model, data)

Arguments

Details

This function is only needed when using raw CatBoost models (trained with catboost.train()). When using parsnip/bonsai, categorical features are handled automatically and this function is not required.

Value

The parsed model with category mappings added

Examples

# For raw CatBoost models with categorical features:
pm <- parse_model(catboost_model)
pm <- set_catboost_categories(pm, catboost_model, training_data)
tidypredict_fit(pm)

# For parsnip/bonsai models, this is not needed:
# tidypredict_fit(parsnip_model_fit)  # works automatically

Tidy the parsed model results

Description

Tidy the parsed model results

Usage

## S3 method for class 'pm_regression'
tidy(x, ...)

Arguments

Value

A tibble with one row per term, containing the term name and its estimate.

Examples

pm <- parse_model(lm(mpg ~ wt, data = mtcars))
tidy(pm)

Combine per-tree expressions into a model's prediction

Description

tidypredict_trees() returns one expression per tree. Turning those back into the model's prediction is not simply summing or averaging them, and the rule differs by backend: mboost::blackboost() needs an offset and a shrinkage factor, CatBoost needs a scale and a bias, aorsf needs a guard that returns NA for an incomplete row, and boosters then apply their objective's inverse link on top.

This generic holds that rule, so a caller that has split the trees apart can put them back together without knowing which backend it is holding.

Usage

tidypredict_combine_trees(x, trees, ...)

Arguments

Details

The point of separating trees from this function is that a caller can compute each tree into its own column, for a database to evaluate in parallel, and then pass symbols referring to those columns rather than the expressions themselves. The combination is the same either way.

A caller may also pass fewer elements than the model has trees, where each one is a subtotal of several trees added together. This is what a caller does to keep any single generated expression short enough for a database parser. Every method supports it: those that average take the divisor from the model rather than from length(trees), and the rest sum. The one thing a caller must not do is reorder or drop trees, since a method is free to treat position as meaningful.

Every ensemble satisfies tidypredict_combine_trees(x, tidypredict_trees(x)) computing the same values as tidypredict_fit(x), and that identity is what the tests for these methods assert.

Not every ensemble has a method. C50::C5.0() boosting combines its trees by a confidence-weighted vote that yields a class label, so there is no arithmetic to apply to per-tree numbers and no method is provided.

Value

A single language object.

See Also

tidypredict_extractors for the generics that produce trees, including a table of which model classes implement them, and tidypredict_metadata for what the combined value means.

Examples

model <- randomForest::randomForest(mpg ~ ., data = mtcars, ntree = 3)

trees <- tidypredict_trees(model)
tidypredict_combine_trees(model, trees)

# Or referring to columns the trees were written to first.
tidypredict_combine_trees(model, rlang::syms(c("t1", "t2", "t3")))

Extract model internals as expressions

Description

These generics expose the pieces tidypredict_fit() is assembled from, rather than the finished formula. They exist so that packages generating their own code from a fitted model, such as orbital, can reuse tidypredict's parsing instead of reimplementing it per model class.

Each generic has a single fixed return shape, described below. A model class implements whichever generics make sense for it: a random forest has trees and a tree count, a glmnet multinomial model has neither.

Usage

tidypredict_trees(x, ...)

tidypredict_class_trees(x, ...)

tidypredict_class_exprs(x, ...)

tidypredict_n_trees(x, ...)

Arguments

Details

Two shapes that look similar are worth keeping apart. tidypredict_class_trees() returns many trees per level that a caller has to sum or average, and needs tidypredict_n_trees() to do it. tidypredict_class_exprs() returns one finished expression per level. Both are named by outcome level so that callers never have to assume the order matches levels() of the outcome.

Value

tidypredict_trees() returns an unnamed list with one element per tree, each a language object.

tidypredict_class_trees() returns a list named by outcome level, in model order. Each element is itself an unnamed list of per-tree language objects for that level, so the result is tidypredict_trees() nested one level deeper. What the leaves hold depends on the model: randomForest gives 0/1 votes, ranger gives class probabilities.

tidypredict_class_exprs() returns a list named by outcome level, in model order, with one language object per level. Unlike tidypredict_class_trees() there is no per-tree structure and nothing to combine: each expression computes that level's value on its own.

tidypredict_n_trees() returns a single integer, the number of trees in the ensemble. For multiclass boosters this counts every tree, including the per-class copies, so it is not the same as the number of boosting rounds.

Wherever an expression is described above, a bare numeric value may appear in its place when the model has nothing to branch on. Callers must handle both. This happens for a single-leaf tree, a stump, and also for a degenerate expression such as a glmnet class whose coefficients are all zero. Note that the constant can appear alongside language objects in the same result, so the element type is not uniform within one list.

Which models implement which generic

. means the generic is not implemented for that class and will error.

                 trees  class_trees  class_exprs  n_trees  combine
blackboost         x         .            .          x        x
C5.0               .         .            .          .        x
catboost.Model     x         .            .          x        x
cforest            x         .            .          x        x
earth              .         .            x          .        .
lgb.Booster        x         .            .          x        x
multnet            .         .            x          .        .
ObliqueForest      x         .            .          x        x
party              .         .            x          .        .
randomForest       x         x            .          x        x
ranger             x         x            .          x        x
rpart              .         .            x          .        .
xgb.Booster        x         .            .          x        x

C50::C5.0() is the one row with a tidypredict_combine_trees() method and no tidypredict_trees(). That method exists only to refuse, with an explanation, rather than to let the caller reach the .default error and guess why.

Implementing these for a new model class

The table above shows the grouping to follow. tidypredict_trees(), tidypredict_n_trees() and tidypredict_combine_trees() are a set: implement all three or none. Per-tree expressions are not usable without a count to size them and a rule to recombine them, and shipping the first without the third invites a caller to sum the trees, which is wrong for every backend that carries an offset, a scale or a link.

A useful check on a new method is that tidypredict_combine_trees(x, tidypredict_trees(x)) computes the same values as tidypredict_fit(x). That identity is what the tests for the existing methods assert, and it catches a combination rule that was assumed rather than read out of the model.

If a model's trees genuinely cannot be recombined arithmetically, give it a tidypredict_combine_trees() method that refuses and no tidypredict_trees() method, as C50::C5.0() does. Splitting trees apart that cannot be put back together only enables a wrong answer.

See Also

tidypredict_combine_trees() for turning per-tree expressions back into a prediction, and tidypredict_metadata for what the resulting values mean.

Examples

model <- randomForest::randomForest(mpg ~ ., data = mtcars, ntree = 5)

tidypredict_n_trees(model)

trees <- tidypredict_trees(model)
length(trees)
trees[[1]]

Returns a Tidy Eval formula to calculate fitted values

Description

It parses a model or uses an already parsed model to return a Tidy Eval formula that can then be used inside a dplyr command.

Usage

tidypredict_fit(model)

Arguments

Value

A Tidy Eval formula that calculates the fitted values. Models that produce one formula per class or per outcome return a list of formulas.

Examples

model <- lm(mpg ~ wt + cyl * disp, offset = am, data = mtcars)
tidypredict_fit(model)

Returns a Tidy Eval formula to calculate prediction interval.

Description

It parses a model or uses an already parsed model to return a Tidy Eval formula that can then be used inside a dplyr command.

Usage

tidypredict_interval(model, interval = 0.95)

Arguments

Details

The result still has to be added to and subtracted from the fit to obtain the upper and lower bound respectively.

Value

A Tidy Eval formula that calculates the half width of the prediction interval. It must be added to and subtracted from the fit to obtain the upper and lower bounds.

Examples

model <- lm(mpg ~ wt + cyl * disp, offset = am, data = mtcars)
tidypredict_interval(model)

Describe what a model's fitted expressions compute

Description

tidypredict_fit() returns expressions, but not what those expressions mean. A single expression could be a numeric prediction, a probability, or an uncalibrated decision value, and the three call for different handling downstream. These generics answer that question, so that a package generating code from the result does not have to keep its own list of which backend produces which shape.

The metadata is asked of the model, not of the fitted expressions, deliberately. Attributes on the result do not survive the subsetting, lapply() and unlist() that callers apply to a multiclass result, which is the case that most needs describing.

Usage

tidypredict_output_type(x, ...)

tidypredict_outcome_levels(x, ...)

tidypredict_normalized(x, ...)

Arguments

Details

None of this is recoverable from the shape of the result, which is the whole reason for recording it. Two concrete cases:

A binary "prob" model and a "decision" model both return exactly one expression. LiblineaR produces either, depending only on its type argument. Treating a decision value as a probability and cutting it at 0.5 gives silently wrong classes for every row whose value falls between 0 and 0.5.

A multiclass "prob" model and a quantreg::rq() fit with several tau both return a named list of expressions of the same length and structure. In the first the values sum to one across the list; in the second they are unrelated numeric predictions.

Value

tidypredict_output_type() returns a single string, one of:

"numeric"

A numeric prediction. tidypredict_fit() returns one expression, or a named list of them for a multivariate outcome or for a quantile regression with several tau.

"prob"

A probability. Either one expression giving the probability of the second outcome level, for a binary model, or a list with one expression per level.

"decision"

An uncalibrated decision value whose sign selects the class. Not a probability, and not comparable to one: the cut is at 0, not 0.5.

"class"

A hard class prediction, with no probability available. Usually the class label as a string, but xgboost's binary:hinge objective gives a 0/1 indicator instead. What makes it "class" rather than "numeric" is that only the class values can occur, so using it as a numeric prediction is a mistake even when its type is numeric.

tidypredict_outcome_levels() returns a character vector of outcome levels in model order, or NULL.

NULL means two different things, and tidypredict_output_type() distinguishes them. For a "numeric" model it means there are no levels. For a "prob" or "class" model it means the fitted model did not retain the outcome levels, so any names on the result are positional placeholders and the caller has to supply the real levels from elsewhere. LightGBM and CatBoost multiclass models are in this position: they store integer labels and their expressions come back named class_0, class_1 and so on.

tidypredict_normalized() returns TRUE if the per-level values already sum to one across levels, FALSE if the caller has to normalize them, and NA when there are no per-level values to sum, which includes every single-expression model.

At present no backend returns FALSE: every multiclass probability list goes through one shared softmax, so the values are always normalized already. The generic exists so that a caller can rely on that rather than having to know it, and so a future backend that does not normalize can say so instead of silently breaking the assumption.

See Also

tidypredict_extractors for the generics that expose a model's per-tree and per-level expressions, and tidypredict_combine_trees() for recombining them.

Examples

model <- lm(mpg ~ wt, data = mtcars)
tidypredict_output_type(model)
tidypredict_outcome_levels(model)
tidypredict_normalized(model)

Save and re-load a parsed model

Description

tidypredict_save() writes a parsed model to a YAML file, and tidypredict_load() reads one back. Together they persist a model's prediction formula without needing the original model object, or the package that fitted it, to be available later.

Use these rather than calling yaml::write_yaml() directly. yaml defaults to 7 significant digits, which is not enough to represent a split threshold exactly: a re-loaded tree model can then send rows down a different branch than the model it was saved from.

Usage

tidypredict_save(x, file)

tidypredict_load(file)

Arguments

Value

tidypredict_save() returns x, invisibly, so it can be used in a pipe. tidypredict_load() returns a parsed model object.

Examples

model <- lm(mpg ~ wt + cyl, data = mtcars)

path <- tempfile(fileext = ".yml")
tidypredict_save(model, path)

loaded <- tidypredict_load(path)
tidypredict_fit(loaded)

Returns a SQL query with formula to calculate fitted values

Description

Returns a SQL query with formula to calculate fitted values

Usage

tidypredict_sql(model, con)

Arguments

Value

A SQL query, as returned by dbplyr::translate_sql(). Models that produce one formula per class or per outcome return a list of queries.

Examples

model <- lm(mpg ~ wt + am + cyl, data = mtcars)
tidypredict_sql(model, dbplyr::simulate_dbi())

Returns a SQL query with formula to calculate predicted interval

Description

Returns a SQL query with formula to calculate predicted interval

Usage

tidypredict_sql_interval(model, con, interval = 0.95)

Arguments

Value

A SQL query, as returned by dbplyr::translate_sql(), giving the half width of the prediction interval.

Examples

model <- lm(mpg ~ wt + am + cyl, data = mtcars)
tidypredict_sql_interval(model, dbplyr::simulate_dbi())

Tests base predict function against tidypredict

Description

Compares the results of predict() and tidypredict_to_column() functions.

Usage

tidypredict_test(
  model,
  df = model$model,
  threshold = 1e-12,
  include_intervals = FALSE,
  max_rows = NULL,
  xg_df = NULL
)

Arguments

Value

A list of test results comparing predict() and tidypredict_to_column(), including the maximum difference and whether it stays within threshold.

Examples

model <- lm(mpg ~ wt + cyl * disp, offset = am, data = mtcars)
tidypredict_test(model)

Adds the prediction columns to a piped command set.

Description

Adds a new column with the results from tidypredict_fit() to a piped command set. If add_interval is set to TRUE, it will add two additional columns- one for the lower and another for the upper prediction interval bounds.

Usage

tidypredict_to_column(
  df,
  model,
  add_interval = FALSE,
  interval = 0.95,
  vars = c("fit", "upper", "lower")
)

Arguments

Value

The input data frame with one new column (the fit) added, or three new columns (fit, upper and lower bounds) when add_interval is TRUE.

Examples

model <- lm(mpg ~ wt, data = mtcars)
tidypredict_to_column(mtcars, model)