Plot iVarPro Gradients for a Single Variable

plot.ivarpro() draws a base-graphics scatterplot of case-specific iVarPro gradients for one predictor: the x-axis is the predictor value and the y-axis 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.

# S3 method for class 'ivarpro'
plot(x,
    var,
    col.var = NULL,
    size.var = NULL,
    data = NULL,
    target = 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

x

An object returned by ivarpro or predict.ivarpro. If data is not supplied, plot.ivarpro() uses attr(x, "data") when available.

var

Variable to plot (name or column index). Must exist in both the iVarPro object and data.

col.var

Optional variable (column name in data) 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 data) used to scale point sizes to cex.range.

data

Optional data.frame or matrix of feature values used for the x-axis variable and any auxiliary variables referenced by col.var or size.var.

target

Optional target/outcome coordinate when x is a list-valued iVarPro result (for example multiclass or multivariate output). May be specified as a single name or index. If omitted, the first element is used.

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 the x-values 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.

Examples

# \donttest{

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

data(peakVO2, package = "randomForestSRC")

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

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

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

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

## Classic 3-quantile view (5%, 50%, 95%)
plot(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
plot(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)
plot(ivp.ir, var = "Petal.Length", target = "setosa",
     col.var = "Species", data = iris)

## Alternatively, color by the predicted class probability stored in ivp.ir
plot(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
plot(ivp, var = "alcohol", target = "Q7",
     data = 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>)
plot(ivp, var = "alcohol", target = "Q7", col.var = "y.Q7")

# }

Arguments

Details

Value

See also

Examples