bplot {rms}R Documentation

3-D Plots Showing Effects of Two Continuous Predictors in a Regression Model Fit

Description

Uses base graphics and the output from Predict to plot image, contour, or perspective plots showing the simultaneous effects of two continuous predictor variables. The x-axis is constructed from the first variable listed in the call to Predict and the y-axis variable comes from the second.

The perimeter function is used to generate the boundary of data to plot when a 3-d plot is made. It finds the area where there are sufficient data to generate believable interaction fits.

iLegend is function for adding legends to an existing graph produced with bplot using method="image".

Usage

bplot(x, xlab, ylab, zlab,
      adj.subtitle=TRUE, cex.adj, perim,
      method=c("image", "persp", "contour"),
      zlim=range(yhat, na.rm=TRUE), nlevels=10, ...)

perimeter(x, y, xinc=diff(range(x))/10, n=10, lowess.=TRUE)

## S3 method for class 'perimeter':
lines(x, ...)

iLegend(object, x, y, size=c(1,1), horizontal=TRUE,
       nint=50, fun.=NULL, at=NULL, zlab, zlim, par.=NULL, ...)

Arguments

x for bplot, an object created by Predict for which exactly two numeric predictors varied. For iLegend, is either a vector of 1 or 2 x-coordinates or a list with elements x and y each with 1 or 2 coordinates. A single coordinate represents the upper left corner of the legend box. x and y are optional. If omitted, locator is used to position legends with the mouse. For perim is the first variable of a pair of predictors forming a 3-d plot. For lines.perimeter, x is the result of perimeter.
xlab Label for x-axis. Default is given by Predict.
ylab Label for y-axis
zlab z-axis label for perspective plots or for iLegend. Default comes from Predict. zlab will often be specified if fun was specified to Predict or iLegend.
adj.subtitle Set to FALSE to suppress subtitling the graph with the list of settings of non-graphed adjustment values. Default is TRUE if there are non-plotted adjustment variables.
cex.adj cex parameter for size of adjustment settings in subtitles. Default is 0.75 times par("cex").
perim names a matrix created by perimeter when used for 3-d plots of two continuous predictors. When the combination of variables is outside the range in perim, that section of the plot is suppressed. If perim is omitted, 3-d plotting will use the marginal distributions of the two predictors to determine the plotting region, when the grid is not specified explicitly in variables. When instead a series of curves is being plotted, perim specifies a function having two arguments. The first is the vector of values of the first variable that is about to be plotted on the x-axis. The second argument is the single value of the variable representing different curves, for the current curve being plotted. The function's returned value must be a logical vector whose length is the same as that of the first argument, with values TRUE if the corresponding point should be plotted for the current curve, FALSE otherwise. See one of the latter examples.
method Use method="persp" for perspective plots (persp()), method="contour" to use contour(), or method="image" to use image() (the default).
zlim If 'type="persp"' controls the range for plotting in the z-axis. Computed by default. Also used by iLegend.
nlevels passed to contour
par. a list of arguments to pass to par, such as mgp. The user can use the argument name par, omitting the period.
... optional arguments to pass to persp, image, or contour. Specify a vector to assign different colors to different curves or to components of 3-d plots, e.g. col=rainbow(30) when method='image'.
y second variable of the pair for perim, or y-coordinates for iLegend. If omitted, x is assumed to be a list with both x and y components.
xinc increment in x over which to examine the density of y in perimeter
n within intervals of x for perimeter, takes the informative range of y to be the nth smallest to the nth largest values of y. If there aren't at least 2n y values in the x interval, no y ranges are used for that interval.
lowess. set to FALSE to not have lowess smooth the data perimeters
object object created by Predict
size size of legend in inches; omitted with 2 points are given in x and y
horizontal set to FALSE to make the labeled legend axis vertical
nint number of intervals of predicted values to use in legend
fun. For iLegend, fun is a function for transforming tick mark labels for color or gray scale legends for method="image". For example, if bplot is used to make an image plot of log odds ratios, specifying fun=plogis will cause the color legend to be labeled with probability values rather than log odds. The user will usually omit the . from the argument name fun..
at If fun is specified to iLegend, at may be given. at is a vector of values at which to evaluate fun for drawing tick marks in the color legend. For example, if you want to show the median survival time for a log-normal survival model whereas the linear predictor (log median) was used in constructing the image plot, and if you want to place tick marks at nice median values, specify fun=exp, at=log(c(1,10,100,1000)).

Details

perimeter is a kind of generalization of datadist for 2 continuous variables. First, the n smallest and largest x values are determined. These form the lowest and highest possible xs to display. Then x is grouped into intervals bounded by these two numbers, with the interval widths defined by xinc. Within each interval, y is sorted and the nth smallest and largest y are taken as the interval containing sufficient data density to plot interaction surfaces. The interval is ignored when there are insufficient y values. When the data are being readied for persp, bplot uses the approx function to do linear interpolation of the y-boundaries as a function of the x values actually used in forming the grid (the values of the first variable specified to Predict). To make the perimeter smooth, specify lowess.=TRUE to perimeter.

Value

perimeter returns a matrix of class perimeter. This outline can be conveniently plotted by lines.perimeter. iLegend invisibly returns the position of the legend.

Author(s)

Frank Harrell
Department of Biostatistics, Vanderbilt University
f.harrell@vanderbilt.edu

See Also

datadist, Predict, rms, rmsMisc, image, contour, persp, subplot

Examples

n <- 1000    # define sample size
set.seed(17) # so can reproduce the results
age            <- rnorm(n, 50, 10)
blood.pressure <- rnorm(n, 120, 15)
cholesterol    <- rnorm(n, 200, 25)
sex            <- factor(sample(c('female','male'), n,TRUE))
label(age)            <- 'Age'      # label is in Hmisc
label(cholesterol)    <- 'Total Cholesterol'
label(blood.pressure) <- 'Systolic Blood Pressure'
label(sex)            <- 'Sex'
units(cholesterol)    <- 'mg/dl'   # uses units.default in Hmisc
units(blood.pressure) <- 'mmHg'

# Specify population model for log odds that Y=1
L <- .4*(sex=='male') + .045*(age-50) +
  (log(cholesterol - 10)-5.2)*(-2*(sex=='female') + 2*(sex=='male'))
# Simulate binary y to have Prob(y=1) = 1/[1+exp(-L)]
y <- ifelse(runif(n) < plogis(L), 1, 0)

ddist <- datadist(age, blood.pressure, cholesterol, sex)
options(datadist='ddist')

fit <- lrm(y ~ blood.pressure + sex * (age + rcs(cholesterol,4)),
               x=TRUE, y=TRUE)
p <- Predict(fit, age=., cholesterol=., np=100)
bplot(p)                 # image plot for age, cholesterol with color
                         # coming from yhat; use default ranges for
                         # both continuous predictors
bplot(p, method='persp', theta=30, ticktype='detailed')
                         # 3-d perspective plot
bplot(p, method='contour')       # contour plot
boundaries <- perimeter(age, cholesterol, lowess=TRUE)
plot(age, cholesterol)   # show bivariate data density
lines(boundaries)        # and perimeter that will be used for 3-D plot
p <- Predict(fit, age=., cholesterol=.)
par(mgp=c(1.7, .35, 0))
bplot(p, perim=boundaries)
                         # draws image() plot
                         # don't show estimates where data are sparse
                         # doesn't make sense here since vars don't interact
iLegend(p, x=c(30,40), y=c(230, 245))   # original logit scale
iLegend(p, x=c(65,75), y=c(230, 245), fun=plogis,
        at=qlogis(c(.1,.25,.5,.75,.9)),
        zlab='Probability')             # probability scale
options(datadist=NULL)

[Package rms version 2.1-0 Index]