ivarpro: Individual Variable Priority: Case-Specific Local Gradients

In varPro: Model-Independent Variable Selection via the Rule-Based Variable Priority

Individual Variable Priority: Case-Specific Local Gradients

Description

Estimates how a prediction target changes with each predictor near individual training observations. Forest rules define the local comparisons, and local slopes provide signed, case-specific importance scores. Supports regression, classification, and survival analyses.

Usage

ivarpro(object,
        adaptive = TRUE,
        cut = NULL,
        cut.max = 1,
        ncut = 51,
        nmin = 20, nmax = 150,
        y.external = NULL,
        noise.na = TRUE,
        max.rules.tree = NULL,
        max.tree = NULL,
        use.loo = TRUE,
        use.abs = FALSE,
        path.store.membership = TRUE,
        save.data = TRUE,
        save.model = TRUE,
        scale = c("local", "global", "none"))

Arguments

object	A varpro object, or a supervised rfsrc grow object with a single outcome and numeric predictors. Use a varpro object for categorical predictors and multivariate regression.
adaptive	Automatically limit the largest candidate neighborhood according to the sample size? Used when cut is not supplied.
cut	Optional vector of nonnegative neighborhood widths for continuous predictors, measured in standard deviations of the released-region predictor values. Supplied values are sorted and duplicates removed; adaptive, cut.max, and ncut are then ignored. Binary 0/1 predictors use a comparison of the two levels.
cut.max	Upper bound on candidate neighborhood width when cut is not supplied. Smaller values restrict estimation to more local observations.
ncut	Number of candidate widths when cut is not supplied.
nmin	Minimum number of usable observations for a local estimate.
nmax	Maximum number of observations used for a local estimate. The effective maximum is also limited according to the training sample size and is at least nmin.
y.external	Optional numeric vector or matrix containing the target values to explain. Rows must correspond, in order, to the processed training observations in object. A matrix supplies a separate target in each column; column names identify the targets. The default uses the rule-generating forest's out-of-bag predictions.
noise.na	Represent unavailable local estimates by NA? With TRUE, available rule estimates are averaged. With FALSE, unavailable rule estimates contribute zero, and cases with no applicable rules receive zero.
max.rules.tree	Maximum number of rules examined per tree. Defaults to the setting in a varpro object, or 150 for direct rfsrc input.
max.tree	Maximum number of trees used to obtain rules. Defaults to the setting in a varpro object, or 150 for direct rfsrc input.
use.loo	Select the continuous-predictor neighborhood by leave-one-out prediction error from the local regressions? With FALSE, use the largest valid candidate neighborhood, subject to nmin and nmax.
use.abs	Average absolute rule-level gradients? The default FALSE retains their signs.
path.store.membership	Retain rule and near-miss membership indices for downstream diagnostics? Setting FALSE reduces storage while preserving the returned gradients and ordinary plots.
save.data	Store processed predictors and prediction targets for plotting?
save.model	Store the supplied model for downstream use?
scale	Predictor scaling for the local slopes: "local" uses the selected neighborhood's spread, "global" uses the predictor's training-sample standard deviation, and "none" returns slopes per unit of the predictor. See Details.

Details

From forest rules to individual importance

A variable's influence can change across observations. iVarPro summarizes this variation through local slopes of a prediction target, using forest rules to identify relevant observations.

For a rule region R, releasing predictor s removes its restrictions and retains the restrictions on the other predictors. This gives the enlarged region R^{(s)}. The additional observations form the near-miss set C_s = R^{(s)} \setminus R. The local regression uses observations from both R and C_s, pooling them within the released region.

For a continuous predictor, estimation uses a neighborhood around its mean among the rule's out-of-bag members. A local regression of the target on that predictor supplies a slope. For a binary 0/1 predictor, the slope is the difference in mean target values between levels 1 and 0. Each case receives the average gradient from rules in whose original region it is an out-of-bag member and for which that predictor is released.

Reading the scores

A positive score indicates that larger predictor values locally accompany larger target values; a negative score indicates the opposite direction. Larger magnitudes represent stronger local changes on the chosen scale. Setting use.abs = TRUE summarizes strength by averaging magnitudes before opposing rule slopes can cancel.

Scores are reported for the processed predictors in object$xvar.names. A hot-encoded factor can therefore have several indicator columns. An unavailable score means that the case has no usable local estimate for that predictor, for example because it lacks applicable rules or sufficient local variation.

Prediction targets

By default, regression explains out-of-bag predicted responses, and classification explains out-of-bag class probabilities. Binary classification returns scores for the first probability column; attr(x, "target") identifies the target in the returned object. Multiclass classification returns a named list with one gradient table per class.

The target follows the forest stored in the model. A survival forest supplies mortality predictions. When VarPro uses a multivariate regression forest for RMST targets, each predicted target has its own gradient table. More generally, multivariate VarPro regression returns one table per predicted response.

Use y.external to explain another numeric target, such as predictions from a different model or a particular class probability. A supplied matrix retains all of its target columns. Target values must be aligned with the observations retained by the original analysis.

Scaling and locality

With scale = "local", the slope is multiplied by the selected predictor values' spread around the rule-region center. With scale = "global", the multiplier is the predictor's standard deviation across the training observations. Both express the gradient in target units. With scale = "none", the slope is in target units per predictor unit; for a binary predictor, it is the change from level 0 to level 1.

Neighborhood size controls how locally the slope is estimated. The defaults choose among candidate neighborhoods using local leave-one-out prediction error. Reducing cut.max restricts the available neighborhoods; increasing nmin requires more observations for each estimate. For binary predictors, both levels are represented in a sample of the released-region observations, subject to the sample-size controls.

Displaying local importance

shap.ivarpro(x) gives a beeswarm-style summary of the local gradients. Position shows the gradient and color shows the predictor value. plot(x, var = "x1") displays one predictor's gradients against its values. Use col.var to color by another variable and examine how the local relationship varies across groups.

For a list of target-specific tables, supply target by name or index to either plotting function. Without it, the first target is used with a warning. Stored data are used automatically; with save.data = FALSE, supply the corresponding processed data through dat to shap.ivarpro or data to plot.

New observations

Use predict(x, newdata = test) to obtain gradients for new cases from the stored rule estimates. Supply predictors in their original form; the training hot-encoding is reused. Omitting newdata recovers out-of-bag training scores. See predict.ivarpro for an example.

Value

An object of class ivarpro. A single target produces a numeric data frame with one row per processed training observation and one column per predictor in object$xvar.names. Row names retain the processed training-row identifiers. Multiple targets produce a named list of these data frames. print(x) summarizes a list; print(x, full = TRUE) displays all of its tables.

The target attribute identifies the target or targets. When requested, the data attribute contains processed predictors and the target values, and the model attribute contains the supplied model. Target columns in the stored data are named y or y.<target>, with suffixes added to avoid name collisions; their names are recorded in attr(attr(x, "data"), "response.names").

The ivarpro.path attribute retains neighborhood settings and diagnostics for the selected rule estimates. Membership indices are included when path.store.membership = TRUE. Ordinary use and plotting require only the gradient tables and, for plots, their data.

Author(s)

Min Lu and Hemant Ishwaran

References

Lu, M. and Ishwaran, H. (2025). Individual variable priority: a model-independent local gradient method for variable importance. Artificial Intelligence Review, 58:407.

See Also

varpro, plot.ivarpro, shap.ivarpro, predict.ivarpro

Examples

## Survival: local changes in predicted mortality.
library(survival)
data(peakVO2, package = "randomForestSRC")
peak <- na.omit(peakVO2)

## Keep all predictors available for the local plots.
set.seed(137)
vp <- varpro(Surv(ttodead, died) ~ ., peak,
             split.weight = FALSE, ntree = 100,
             parallel = FALSE)
ivp <- ivarpro(vp)
print(head(ivp))
shap.ivarpro(ivp)

## Exercise time colors the local relationship with peak oxygen uptake.
plot(ivp, var = "peak.vo2", col.var = "interval")

## Specify a fixed maximum neighborhood width.
ivp.local <- ivarpro(vp, adaptive = FALSE, cut.max = 0.5)
plot(ivp.local, var = "peak.vo2", col.var = "interval")

## Interaction example: Model 3 of Lu and Ishwaran (2025).
## The signal is 6*x1*x2.
## Its slopes are 6*x2 for x1 and 6*x1 for x2.
set.seed(137)
n <- 500
X <- matrix(runif(n * 10), nrow = n)
colnames(X) <- paste0("x", seq_len(ncol(X)))
d <- data.frame(y = 6 * X[, 1] * X[, 2] + rnorm(n), X)
vp <- varpro(y ~ ., d, split.weight = FALSE, ntree = 100,
             parallel = FALSE)

set.seed(137)
iv.local <- ivarpro(vp)
set.seed(137)
iv.global <- ivarpro(vp, scale = "global")
set.seed(137)
iv.slope <- ivarpro(vp, scale = "none")

## Compare local magnitudes under the three scaling choices.
scale.summary <- data.frame(
  variable = colnames(iv.local),
  local = colMeans(abs(iv.local), na.rm = TRUE),
  global = colMeans(abs(iv.global), na.rm = TRUE),
  slope = colMeans(abs(iv.slope), na.rm = TRUE))
print(scale.summary)

## Map both slopes over the (x1, x2) plane, as in the paper's
## gradient displays. Each point is a case; color gives its slope.
## The top row shows the true slopes and the bottom row iVarPro estimates.
## scale = "none" puts the estimates in the same units as the derivatives.
slopes <- cbind("True slope for x1" = 6 * d$x2,
                "True slope for x2" = 6 * d$x1,
                "iVarPro slope for x1" = iv.slope$x1,
                "iVarPro slope for x2" = iv.slope$x2)

slope.map <- function(x1, x2, slopes) {
  ## Use one color scale for all four panels. Positive slopes run
  ## from white through orange to red; negative slopes are blue.
  values <- slopes[is.finite(slopes)]
  limit <- max(1, ceiling(max(abs(values))))
  pal <- c(grDevices::colorRampPalette(c("navy", "white"))(101)[-101],
           grDevices::colorRampPalette(c("white", "orange", "red"))(101))
  slope.col <- function(z) pal[1L + round(100 * (z / limit + 1))]

  op <- par(no.readonly = TRUE)
  on.exit(par(op), add = TRUE)
  layout(matrix(c(1, 2, 3, 4, 5, 5), ncol = 2, byrow = TRUE),
         heights = c(1, 1, 0.3))
  par(mar = c(3.5, 3.5, 2, 1), mgp = c(2, 0.6, 0))
  for (j in seq_len(ncol(slopes))) {
    ok <- is.finite(slopes[, j])
    plot(x1, x2, type = "n", xlim = c(0, 1), ylim = c(0, 1),
         xlab = "x1", ylab = "x2", main = colnames(slopes)[j], asp = 1)
    points(x1[ok], x2[ok], pch = 16, cex = 0.7,
           col = slope.col(slopes[ok, j]))
    points(x1[!ok], x2[!ok], pch = 4, cex = 0.6, col = "grey60")
  }
  par(mar = c(0, 0, 0, 0))
  plot.new()
  at <- seq(-limit, limit, length.out = 7)
  legend("center", legend = format(signif(at, 2), trim = TRUE),
         fill = slope.col(at), ncol = length(at), bty = "n", cex = 0.8,
         title = "Slope (grey crosses: unavailable)")
}
slope.map(d$x1, d$x2, slopes)

## With slopes on the vertical axis, color by the other predictor.
plot(iv.slope, var = "x1", col.var = "x2")
plot(iv.slope, var = "x2", col.var = "x1")

## Explain two supplied targets using the same forest rules.
## Name the columns so targets can be selected explicitly in plots.
targets <- cbind(interaction = 6 * d$x1 * d$x2,
                 linear = 2 * d$x1 - d$x2)
iv.targets <- ivarpro(vp, y.external = targets, scale = "none")
print(iv.targets)
print(head(iv.targets[["linear"]]))
plot(iv.targets, var = "x1", target = "interaction", col.var = "x2")
shap.ivarpro(iv.targets, target = "linear")

varPro documentation built on Sept. 22, 2026, 5:09 p.m.