partial.ivarpro: 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,
                ...)

Value

Invisibly returns 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.

Examples

Run this code

# \donttest{

## ------------------------------------------------------------
##
## 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.)
partial.ivarpro(ivp, var = "alcohol", target = "Q7", col.var = "y.Q7")

# }