partial.ivarpro: Partial iVarPro Plot for a Single Variable

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

Partial iVarPro Plot for a Single Variable

Description

partial.ivarpro() draws a base-graphics scatterplot of case-specific iVarPro gradients for one predictor: x is the predictor value and y is the iVarPro local gradient. Points can be colored (col.var), sized (size.var), optionally jittered, and optionally overlaid with loess smooths stratified by col.var.

Usage

partial.ivarpro(ivar,
                var,
                col.var = NULL,
                size.var = NULL,
                x = NULL,
                ladder = FALSE,
                ladder.cuts = NULL,
                ladder.max.segments = 3000,
                pch = 16,
                cex = 0.8,
                cex.range = c(0.5, 2),
                main = NULL,
                xlab = NULL,
                ylab = "iVarPro gradient",
                legend = TRUE,
                ...)

Arguments

ivar	An object returned by ivarpro. If x is not supplied, partial.ivarpro() uses attr(ivar, "data") when available.
var	Variable to plot (name or column index). Must exist in both ivar and x.
col.var	Optional variable (column name in x) used for coloring. If treated as categorical, colors are assigned per level; if continuous, a color ramp is used and the legend shows selected quantiles.
size.var	Optional variable (column name in x) used to scale point sizes to cex.range.
x	Optional data.frame or matrix of original feature values.
ladder	Logical. If TRUE, attempt to draw a ladder-based band (vertical segments spanning the range across ladder.cuts) when path membership information is present.
ladder.cuts	Optional subset of ladder indices/values used for the band.
ladder.max.segments	Maximum number of ladder segments to draw.
pch	Point character for the default point style.
cex	Base point size (used when size.var is not supplied).
cex.range	Min/max point sizes used when size.var is supplied.
main	Main title (defaults to paste0(var, " vs iVarPro gradient")).
xlab	X-axis label (defaults to var).
ylab	Y-axis label (defaults to "iVarPro gradient").
legend	Logical. If TRUE and col.var is supplied, draw a legend describing the color mapping.
...	Additional arguments passed to graphics::plot(), plus these optional controls: smooth Logical. Draw loess smooth curves. Default TRUE. For categorical col.var, one curve per level. For continuous col.var, curves are drawn for strata defined by quantiles. smooth.span Loess span (default 0.75). Other loess controls: smooth.degree, smooth.family, smooth.lwd, smooth.lty, smooth.alpha, smooth.min.n, smooth.n.grid. jitter Logical or numeric. Default TRUE. Adds horizontal jitter to x to reduce overplotting. Related options: jitter.amount, jitter.fraction, jitter.seed. x.dist Character vector controlling an x-axis distribution strip. Default "none". Supported values include "rug", "hist", "density", and "auto" (defaults to c("hist","rug")). Use x.dist = c("hist","rug") (or c("density","rug")) to combine. Related options: x.dist.side, x.dist.height, x.dist.pad, x.dist.col, x.dist.border, x.dist.lwd, x.dist.lty, x.dist.bins, x.dist.adjust, x.dist.n, x.dist.rug.col, x.dist.rug.lwd, x.dist.rug.ticksize, x.dist.rug.max. By default, an outline is drawn to keep the strip visible; set x.dist.lwd = 0 to suppress the outline. col.legend.probs, col.legend.n Quantiles shown in the legend when col.var is continuous. Default is 5 quantiles: c(0.05, 0.25, 0.5, 0.75, 0.95). smooth.probs, smooth.n Quantiles defining strata for smooth curves when col.var is continuous. Default matches the legend quantiles. zero.line Logical. Default TRUE. Adds a dashed reference line at gradient 0 (y = 0). Related options: zero.line.col, zero.line.lty, zero.line.lwd. col.var.discrete.max If col.var is numeric with at most this many distinct values, treat it as categorical (default 10). col.style How categorical colors are rendered: "auto" (default), "solid", "outline", "binary". Related options include col.outline, col.binary.pch, col.dodge.

Details

Jitter is applied for visualization only; loess smooths and the optional x-axis distribution strip (x.dist) are computed using the unjittered x-values.

Value

Invisibly returns TRUE.

See Also

ivarpro, varpro, shap.ivarpro

Examples

## ------------------------------------------------------------
##
## Survival example: peakVO2 partial plot
##
## ------------------------------------------------------------

data(peakVO2, package = "randomForestSRC")

ipv <- ivarpro(varpro(Surv(ttodead, died) ~ ., peakVO2))

## Continuous col.var: legend + smooth strata default to 5 quantiles
partial.ivarpro(ipv, var = "peak.vo2", col.var = "interval", size.var = "y")

## Add an x-axis distribution strip (histogram + rug)
partial.ivarpro(ipv, var = "peak.vo2", col.var = "interval", size.var = "y",
                x.dist = c("hist", "rug"))

## Increase legend/smooth strata (e.g., 7 quantiles)
partial.ivarpro(ipv, var = "peak.vo2", col.var = "interval", size.var = "y",
                col.legend.n = 7, smooth.n = 7)

## Classic 3-quantile view (5%, 50%, 95%)
partial.ivarpro(ipv, var = "peak.vo2", col.var = "interval", size.var = "y",
                col.legend.probs = c(0.05, 0.5, 0.95),
                smooth.probs = c(0.05, 0.5, 0.95))

## Factor col.var example: one smooth per level
partial.ivarpro(ipv, var = "peak.vo2", col.var = "betablok", size.var = "y")

## ------------------------------------------------------------
##
## multiclass example: iris (use target= to choose a class)
##
## ------------------------------------------------------------

data(iris)

vp.ir  <- varpro(Species ~ ., iris, ntree = 50)
ivp.ir <- ivarpro(vp.ir)

## Plot gradients for the "setosa" class (target selects the list element)
partial.ivarpro(ivp.ir, var = "Petal.Length", target = "setosa",
                col.var = "Species", x = iris)

## Alternatively, color by the predicted class probability stored in ivp.ir
partial.ivarpro(ivp.ir, var = "Petal.Length", target = "setosa",
                col.var = "y.setosa")


## ------------------------------------------------------------
##
## multiclass example: wine (advanced example)
##
## ------------------------------------------------------------

data(wine, package = "randomForestSRC")

## Give the class labels nicer names than "3", "4", ..., "9"
wine$quality <- factor(wine$quality)
levels(wine$quality) <- paste0("Q", levels(wine$quality))  # "Q3" "Q4" ... "Q9"

vp  <- varpro(quality ~ ., wine, ntree = 50)
ivp <- ivarpro(vp)

## Available targets correspond to class probability columns
names(ivp)

## Build a plotting data.frame that contains:
##  - predictors (from attr(ivp,"data"))
##  - predicted class probabilities (y.Q3, y.Q4, ..., y.Q9)
##  - the observed class label (quality)
xdat <- attr(ivp, "data")
xdat$quality <- wine$quality

## Plot gradients for the "Q7" class:
## y-axis: d P(Y="Q7" | x) / d alcohol  (iVarPro gradient)
## x-axis: alcohol
## color: observed class label
partial.ivarpro(ivp, var = "alcohol", target = "Q7",
                x = xdat, col.var = "quality")

## Alternatively, color by the model's predicted probability for the same class.
## (These columns come from attr(ivp,"data") as y.<class>)
partial.ivarpro(ivp, var = "alcohol", target = "Q7", col.var = "y.Q7")

varPro documentation built on Feb. 12, 2026, 5:07 p.m.