Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!
Get Started for Free

persp

Perspective and heatmap/contour plots for models


Description

Draw one or more perspectives plots reflecting predictions or marginal effects from a model, or the same using a flat heatmap or “filled contour” (image) representation. Currently methods exist for “lm”, “glm”, and “loess” models.

Usage

## S3 method for class 'lm'
image(
  x,
  xvar = attributes(terms(x))[["term.labels"]][1],
  yvar = attributes(terms(x))[["term.labels"]][2],
  dx = xvar,
  what = c("prediction", "effect"),
  type = c("response", "link"),
  vcov = stats::vcov(x),
  nx = 25L,
  ny = nx,
  nz = 20,
  xlab = xvar,
  ylab = yvar,
  xaxs = "i",
  yaxs = xaxs,
  bty = "o",
  col = gray(seq(0.05, 0.95, length.out = nz), alpha = 0.75),
  contour = TRUE,
  contour.labels = NULL,
  contour.drawlabels = TRUE,
  contour.cex = 0.6,
  contour.col = "black",
  contour.lty = 1,
  contour.lwd = 1,
  ...
)

## S3 method for class 'glm'
image(
  x,
  xvar = attributes(terms(x))[["term.labels"]][1],
  yvar = attributes(terms(x))[["term.labels"]][2],
  dx = xvar,
  what = c("prediction", "effect"),
  type = c("response", "link"),
  vcov = stats::vcov(x),
  nx = 25L,
  ny = nx,
  nz = 20,
  xlab = xvar,
  ylab = yvar,
  xaxs = "i",
  yaxs = xaxs,
  bty = "o",
  col = gray(seq(0.05, 0.95, length.out = nz), alpha = 0.75),
  contour = TRUE,
  contour.labels = NULL,
  contour.drawlabels = TRUE,
  contour.cex = 0.6,
  contour.col = "black",
  contour.lty = 1,
  contour.lwd = 1,
  ...
)

## S3 method for class 'loess'
image(
  x,
  xvar = attributes(terms(x))[["term.labels"]][1],
  yvar = attributes(terms(x))[["term.labels"]][2],
  dx = xvar,
  what = c("prediction", "effect"),
  type = c("response", "link"),
  vcov = stats::vcov(x),
  nx = 25L,
  ny = nx,
  nz = 20,
  xlab = xvar,
  ylab = yvar,
  xaxs = "i",
  yaxs = xaxs,
  bty = "o",
  col = gray(seq(0.05, 0.95, length.out = nz), alpha = 0.75),
  contour = TRUE,
  contour.labels = NULL,
  contour.drawlabels = TRUE,
  contour.cex = 0.6,
  contour.col = "black",
  contour.lty = 1,
  contour.lwd = 1,
  ...
)

## S3 method for class 'lm'
persp(
  x,
  xvar = attributes(terms(x))[["term.labels"]][1],
  yvar = attributes(terms(x))[["term.labels"]][2],
  dx = xvar,
  what = c("prediction", "effect"),
  type = c("response", "link"),
  vcov = stats::vcov(x),
  nx = 25L,
  ny = nx,
  theta = 45,
  phi = 10,
  shade = 0.75,
  xlab = xvar,
  ylab = yvar,
  zlab = if (match.arg(what) == "prediction") "Predicted value" else
    paste0("Marginal effect of ", dx),
  ticktype = c("detailed", "simple"),
  ...
)

## S3 method for class 'glm'
persp(
  x,
  xvar = attributes(terms(x))[["term.labels"]][1],
  yvar = attributes(terms(x))[["term.labels"]][2],
  dx = xvar,
  what = c("prediction", "effect"),
  type = c("response", "link"),
  vcov = stats::vcov(x),
  nx = 25L,
  ny = nx,
  theta = 45,
  phi = 10,
  shade = 0.75,
  xlab = xvar,
  ylab = yvar,
  zlab = if (match.arg(what) == "prediction") "Predicted value" else
    paste0("Marginal effect of ", dx),
  ticktype = c("detailed", "simple"),
  ...
)

## S3 method for class 'loess'
persp(
  x,
  xvar = attributes(terms(x))[["term.labels"]][1],
  yvar = attributes(terms(x))[["term.labels"]][2],
  dx = xvar,
  what = c("prediction", "effect"),
  type = c("response", "link"),
  vcov = stats::vcov(x),
  nx = 25L,
  ny = nx,
  theta = 45,
  phi = 10,
  shade = 0.75,
  xlab = xvar,
  ylab = yvar,
  zlab = if (match.arg(what) == "prediction") "Predicted value" else
    paste0("Marginal effect of ", dx),
  ticktype = c("detailed", "simple"),
  ...
)

Arguments

x

A model object.

xvar

A character string specifying the name of variable to use as the x dimension in the plot. See persp for details.

yvar

A character string specifying the name of variable to use as the y dimension in the plot. See persp for details.

dx

A character string specifying the name of the variable for which the conditional average marginal effect is desired when what = "effect". By default this is xvar.

what

A character string specifying whether to draw “prediction” (fitted values from the model, calculated using predict) or “effect” (marginal effect of dx, using margins).

type

A character string specifying whether to calculate predictions on the response scale (default) or link (only relevant for non-linear models).

vcov

A matrix containing the variance-covariance matrix for estimated model coefficients, or a function to perform the estimation with model as its only argument.

nx

An integer specifying the number of points across x at which to calculate the predicted value or marginal effect.

ny

An integer specifying the number of points across y at which to calculate the predicted value or marginal effect.

nz

An integer specifying, for image, the number of breakpoints to use when coloring the plot.

xlab

A character string specifying the value of xlab in persp or image.

ylab

A character string specifying the value of ylab in persp or image.

xaxs

A character string specifying the x-axis type (see par).

yaxs

A character string specifying the y-axis type (see par).

bty

A character string specifying the box type (see par).

col

A character vector specifying colors to use when coloring the contour plot.

contour

For image, a logical specifying whether to overlay contour lines onto the heatmap using contour.

contour.labels

For image, if contour = TRUE a logical specifying whether to overlay contour lines onto the heatmap.

contour.drawlabels

For image, if contour = TRUE a logical specifying whether to overlay contour lines onto the heatmap.

contour.cex

For image, if contour = TRUE and contour.drawlabels = TRUE a numeric specifying the label size for contour line labels (see par).

contour.col

For image, if contour = TRUE a character string specifying a color for contour lines.

contour.lty

For image, if contour = TRUE an integer specifying a line type for contour lines (see par).

contour.lwd

For image, if contour = TRUE an integer specifying a line width for contour lines (see par).

...

Additional arguments passed to persp or image.

theta

For persp, an integer vector specifying the value of theta in persp. If length greater than 1, multiple subplots are drawn with different rotations.

phi

For persp, an integer vector specifying the value of phi in persp. If length greater than 1, multiple subplots are drawn with different rotations.

shade

For persp, an integer vector specifying the value of shade in persp.

zlab

A character string specifying the value of zlab (vertical axis label) in persp.

ticktype

A character string specifying one of: “detailed” (the default) or “simple”. See persp.

See Also

Examples

## Not run: 
  require('datasets')
  # prediction from several angles
  m <- lm(mpg ~ wt*drat, data = mtcars)
  persp(m, theta = c(45, 135, 225, 315))

  # flat/heatmap representation
  image(m)

  # marginal effect of 'drat' across drat and wt
  m <- lm(mpg ~ wt*drat*I(drat^2), data = mtcars)
  persp(m, xvar = "drat", yvar = "wt", what = "effect", 
        nx = 10, ny = 10, ticktype = "detailed")

  # a non-linear model
  m <- glm(am ~ wt*drat, data = mtcars, family = binomial)
  persp(m, theta = c(30, 60)) # prediction
  # flat/heatmap representation
  image(m)

  # effects on linear predictor and outcome
  persp(m, xvar = "drat", yvar = "wt", what = "effect", type = "link")
  persp(m, xvar = "drat", yvar = "wt", what = "effect", type = "response")

## End(Not run)

margins

Marginal Effects for Model Objects

v0.3.26
MIT + file LICENSE
Authors
Thomas J. Leeper [aut, cre] (<https://orcid.org/0000-0003-4097-6326>), Jeffrey Arnold [ctb], Vincent Arel-Bundock [ctb], Jacob A. Long [ctb] (<https://orcid.org/0000-0002-1582-6214>)
Initial release
2021-01-10

We don't support your browser anymore

Please choose more modern alternatives, such as Google Chrome or Mozilla Firefox.