persp: Perspective and heatmap/contour plots for models

In margins: Marginal Effects for Model Objects

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

plot.margins, cplot

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 documentation built on Jan. 22, 2021, 5:09 p.m.