Partial dependence plot for any predict()-compatible model

For each bin of var, the function fixes that feature at the bin midpoint (numeric) or bin label (categorical), runs predict() across a sample of the full dataset, and averages the predictions. The result shows the marginal effect of var on model output, stripped of all correlations with other features.

Usage

pdp(data, ...)

# Default S3 method
pdp(
  data,
  var,
  obs,
  model,
  exposure = "exposure",
  bins = 10L,
  sample_size = 10000L,
  type_agg = c("equal_exposure", "equal_range"),
  model_name = "model",
  ret = c("plot", "data"),
  pre_process_fun = function(df) df,
  feat_eng_fun = function(df) df,
  post_process_fun = function(preds, df_raw) preds,
  seed = 2024L,
  verbose = FALSE,
  ...
)

Arguments

data: A data.frame or data.table.
...: Arguments passed to methods.
var: [character(1)] Feature column to vary on the x-axis.
obs: [character(1)] Observed target column name.
model: A fitted model object. Standard R models (lm, glm, xgb, ranger, tidymodels workflows, etc.) and H2O models are supported automatically - no extra arguments needed.
exposure: [character(1)] Exposure weight column. If absent, every row is given weight 1. Default "exposure".
bins: [integer(1)] Number of bins for numeric var. Default 10.
sample_size: [integer(1)] Rows to sample for PDP computation. Reducing this speeds up prediction at the cost of accuracy. Default 10,000. The full dataset is always used for the one-way actuals.
type_agg: [character(1)] Binning strategy: "equal_exposure" (default) or "equal_range".
model_name: [character(1)] Label shown in the plot legend. Default "model".
ret: [character(1)] "plot" (default) returns a plotly object; "data" returns the aggregated data.table.
pre_process_fun: function(df) -> df applied to the data before feature engineering. Default is the identity function.
feat_eng_fun: function(df) -> df (or matrix) applied after pre-processing to produce the model input. Default is the identity function.
post_process_fun: function(preds, df_raw) -> numeric applied to raw model predictions. Default is the identity function.
seed: [integer(1)] Seed for the PDP row sample, applied via withr::with_seed() so the global RNG stream is left undisturbed. Default 2024L.
verbose: [logical(1)] Announce the variable being computed? Default FALSE.

Value

A plotly object, or a data.table when ret = "data", or NULL with a warning when the variable cannot be plotted.

Details

Alongside the PDP line the chart also shows:

Observed mean per bin (actual target, exposure-weighted)
Model average prediction per bin (in-sample, not PDP)
Global average observed and predicted reference lines
Yellow exposure bars (left axis) - identical style to one_way()

Examples