margins: persp – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

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`.

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