plot.ivarpro: Plot Individual Variable Priority

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

Plot Individual Variable Priority

Description

Display case-specific iVarPro gradients for one predictor, or compare their distributions across predictors in a beeswarm-style summary.

Usage

## S3 method for class 'ivarpro'
plot(x, var, col.var = NULL, size.var = NULL,
  data = NULL, target = NULL, pch = 16, cex = 0.8,
  cex.range = c(0.5, 2), main = NULL, xlab = NULL,
  ylab = "iVarPro gradient", legend = TRUE, ...)

shap.ivarpro(ivar, dat = NULL, feature_names = NULL,
  max.points = 5000, max.points.per.feature = NULL,
  point.alpha = 1.0, point.size = 0.35, point.pch = 16,
  scale.value = TRUE, style = c("blobby", "jitter"),
  blobby.separation = 3, target = NULL)

Arguments

x, ivar	An iVarPro object, or a numeric data frame or matrix of case-specific gradients.
var	Predictor to display, given by its column name or index in the gradient table. Use the processed predictor name for a hot-encoded factor.
col.var	Optional column of the plotting data used to color points. A factor gives group colors; a continuous variable gives a color gradient.
size.var	Optional column of the plotting data used to scale point sizes.
data, dat	Plotting data with rows in the same order as the gradient table. By default, use the data stored by ivarpro or predict.ivarpro. The plotted predictor columns must be numeric; the stored data provide the appropriate hot-encoding.
target	For a multi-target object, the response or class name, or its integer position. If omitted, use the first target with a warning.
pch, cex	Point symbol and size for the single-predictor plot. Group-specific point styles can override pch.
cex.range	Range of point sizes when size.var is supplied.
main, xlab, ylab	Plot title and axis labels.
legend	Display the color legend in the single-predictor plot?
...	Graphical arguments and optional display controls for plot; see Details.
feature_names	Names for an unnamed gradient matrix in the summary plot. Existing column names take precedence.
max.points	Maximum total number of points in the summary plot. Larger collections are subsampled.
max.points.per.feature	Optional additional limit on the number of displayed points per predictor.
point.alpha, point.size, point.pch	Point opacity, size and symbol for the summary plot.
scale.value	Rescale each predictor's displayed values to the range zero to one for coloring? Default is TRUE. This changes the colors, not the gradient scores.
style	Summary-point arrangement: "blobby" separates overlapping points into a beeswarm-like display; "jitter" uses vertical jitter.
blobby.separation	Spacing between points for style = "blobby". Larger values increase separation.

Details

Single-predictor plot

plot(x, var = "x1") places predictor values on the horizontal axis and their local gradients on the vertical axis. A zero reference line helps distinguish positive and negative relationships. Coloring by another predictor can reveal how the relationship varies across cases.

Smooth curves are drawn by default, with separate curves for color groups. Useful controls passed through ... include smooth = FALSE to suppress curves, smooth.span to adjust smoothing, and jitter = FALSE to suppress horizontal jitter. jitter.seed makes jitter reproducible.

Use x.dist = "rug", "hist", or "density" to show the predictor distribution along the horizontal axis. Combinations such as x.dist = c("hist", "rug") are allowed. zero.line = FALSE suppresses the reference line. col.style selects "auto", "solid", "outline", or "binary" point styling.

Summary plot

shap.ivarpro(x) displays the iVarPro gradients for all predictors. Horizontal position shows a gradient's sign and magnitude; color shows the predictor value. Predictors are ordered by mean absolute gradient. Columns containing only zero or nonfinite scores are omitted.

The gradient scale is set by the original ivarpro call. In particular, scale = "global" expresses changes on a common training-standard-deviation scale within each predictor, while scale = "none" shows slopes in original predictor units. See ivarpro for the three scaling choices.

Value

Called for its plotting side effect. plot.ivarpro returns TRUE invisibly; shap.ivarpro returns NULL invisibly.

See Also

ivarpro, predict.ivarpro

Examples

## Compare local mortality gradients and inspect peak oxygen uptake.
library(survival)
data(peakVO2, package = "randomForestSRC")
peak <- na.omit(peakVO2)
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)
plot(ivp, var = "peak.vo2", col.var = "interval")
## scale points to "y" (here equal to mortality)
plot(ivp, var = "peak.vo2", col.var = "interval", size.var = "y",
     x.dist = c("hist", "rug"), jitter = FALSE)

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