# bplot

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

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), ...)
```perimeter(x, y, xinc=diff(range(x))/10, n=10, lowess.=TRUE)

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

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

##### 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 - 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 omitte - 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`

. - ...
- 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='imag`

- 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 $n$th smallest to the $n$th largest values of`y`

. If there aren't at least 2$n$`y`

values in the`x`

- 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, specif - 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 s

##### 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
`x`

s 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 $n$th 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.

##### 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)
```

*Documentation reproduced from package rms, version 2.0-2, License: GPL (>= 2)*