R2BayesX: plot3d – R documentation

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

plot3d

3D Effect Plot

Description

Function to plot 3D graphics or image and/or contour plots for bivariate effects/functions, typically used for objects of class "sm.bayesx" and "geo.bayesx" returned from function bayesx and read.bayesx.output.

Usage

plot3d(x, residuals = FALSE, col.surface = NULL, 
  ncol = 99L, swap = FALSE, col.residuals = NULL, col.contour = NULL, 
  c.select = NULL, grid = 30L, image = FALSE, contour = FALSE, 
  legend = TRUE, cex.legend = 1, breaks = NULL, range = NULL, 
  digits = 2L, d.persp = 1L, r.persp = sqrt(3), outscale = 0,
  data = NULL, sep = "", shift = NULL, trans = NULL,
  type = "akima", linear = FALSE, extrap = FALSE,
  k = 40, ...)

Arguments

`x`	a matrix or data frame, containing the covariates for which the effect should be plotted in the first and second column and at least a third column containing the effect, typically the structure for bivariate functions returned within `bayesx` and `read.bayesx.output` model term objects is used, also see `fitted.bayesx`. Another possibility is to specify the plot via a `formula`, e.g. for simple plotting of bivariate surfaces `z ~ x + y`, also see the example. `x` may also be a character file path to the data to be used for plotting.
`residuals`	if set to `TRUE`, partial residuals may also be plotted if available.
`col.surface`	the color of the surface, may also be a function, e.g. `col.surface = heat.colors`.
`ncol`	the number of different colors that should be generated, if `col.surface` is a function.
`swap`	if set to `TRUE` colors will be represented in reverse order.
`col.residuals`	the color of the partial residuals, or if `contour = TRUE` the color of the contour lines.
`col.contour`	the color of the contour lines.
`c.select`	`integer` vector of maximum length of columns of `x`, selects the columns of the resulting data matrix that should be used for plotting. E.g. if `x` has 5 columns, then `c.select = c(1, 2, 5)` will select column 1, 2 and 5 for plotting. If `c.select = 95` or `c.select = 80`, function `plot3d` will search for the corresponding columns to plot a 95\% or 80\% confidence surfaces respectively. Note that if e.g. `c.select = c(1, 2)`, `plot3d` will use columns 1 + 2 and 2 + 2 for plotting.
`grid`	the grid size of the surface(s).
`image`	if set to `TRUE`, an `image.plot` is drawn.
`contour`	if set to `TRUE`, a `contour` plot is drawn.
`legend`	if `image = TRUE` an additional legend may be added to the plot.
`cex.legend`	the expansion factor for the legend text, see `text`.
`breaks`	a set of breakpoints for the colors: must give one more breakpoint than `ncol`.
`range`	specifies a certain range values should be plotted for.
`digits`	specifies the legend decimal places.
`d.persp`	see argument `d` in function `persp`.
`r.persp`	see argument `r` in function `persp`.
`outscale`	scales the outer ranges of `x` and `z` limits used for interpolation.
`data`	if `x` is a `formula`, a `data.frame` or `list`. By default the variables are taken from `environment(x)`: typically the environment from which `plot3d` is called. Note that `data` may also be a character file path to the data.
`sep`	the field separator character when `x` or `data` is a character, see function `read.table`.
`shift`	numeric. Constant to be added to the smooth before plotting.
`trans`	function to be applied to the smooth before plotting, e.g., to transform the plot to the response scale.
`type`	character. Which type of interpolation metjod should be used. The default is `type = "akima"`, see function `interp`. The two other options are `type = "mba"`, which calls function `mba.surf` of package MBA, or `type = "mgcv"`, which uses a spatial smoother withing package mgcv for interpolation. The last option is definitely the slowest, since a full regression model needs to be estimated.
`linear`	logical. Should linear interpolation be used withing function `interp`?
`extrap`	logical. Should interpolations be computed outside the observation area (i.e., extrapolated)?
`k`	integer. The number of basis functions to be used to compute the interpolated surface when `type = "mgcv"`.
`...`	parameters passed to `colorlegend` if an image plot with legend is drawn, also other graphical parameters, please see the details.

Details

For 3D plots the following graphical parameters may be specified additionally:

cex: specify the size of partial residuals,
col: it is possible to specify the color for the surfaces if se > 0, then e.g. col = c("green", "black", "red"),
pch: the plotting character of the partial residuals,
...: other graphical parameters passed functions persp, image.plot and contour.

Note

Function plot3d uses per default the akima package to construct smooth interpolated surfaces, therefore, package akima needs to be installed. The akima package has an ACM license that restricts applications to non-commercial usage, see

http://www.acm.org/publications/policies/softwarecrnotice

Function plot3d prints a note refering to the ACM licence. This note can be supressed by setting

options("use.akima" = TRUE)

Author(s)

Nikolaus Umlauf, Thomas Kneib, Stefan Lang, Achim Zeileis.

Examples

## generate some data
set.seed(111)
n <- 500

## regressors
dat <- data.frame(z = runif(n, -3, 3), w = runif(n, 0, 6))

## response
dat$y <- with(dat, 1.5 + cos(z) * sin(w) + rnorm(n, sd = 0.6))

## Not run: 
## estimate model
b <- bayesx(y ~ sx(z, w, bs = "te", knots = 5), data = dat, method = "REML")
summary(b)

## plot estimated effect
plot(b, term = "sx(z,w)")

## extract fitted effects
f <- fitted(b, term = "sx(z,w)")

## now use plot3d
plot3d(f)
plot3d(f, swap = TRUE)
plot3d(f, residuals = TRUE)
plot3d(f, resid = TRUE, cex.resid = 0.1)
plot3d(f, resid = TRUE, pch = 2, col.resid = "green3")
plot3d(f, resid = TRUE, c.select = 95, cex.resid = 0.1)
plot3d(f, resid = TRUE, c.select = 80, cex.resid = 0.1)
plot3d(f, grid = 100, border = NA)
plot3d(f, c.select = 95, border = c("red", NA, "green"),
  col.surface = c(1, NA, 1), resid = TRUE, cex.resid = 0.2)

## now some image and contour
plot3d(f, image = TRUE, legend = FALSE)
plot3d(f, image = TRUE, legend = TRUE)
plot3d(f, image = TRUE, contour = TRUE)
plot3d(f, image = TRUE, contour = TRUE, swap = TRUE)
plot3d(f, image = TRUE, contour = TRUE, col.contour = "white")
plot3d(f, contour = TRUE)
op <- par(no.readonly = TRUE)
par(mfrow = c(1, 3))
plot3d(f, image = TRUE, contour = TRUE, c.select = 3)
plot3d(f, image = TRUE, contour = TRUE, c.select = "Estimate")
plot3d(f, image = TRUE, contour = TRUE, c.select = "97.5
par(op)

## End(Not run)

## another variation
dat$f1 <- with(dat, sin(z) * cos(w))
with(dat, plot3d(cbind(z, w, f1)))

## same with formula 
plot3d(sin(z) * cos(w) ~ z + w, zlab = "f(z,w)", data = dat)
plot3d(sin(z) * cos(w) ~ z + w, zlab = "f(z,w)", data = dat, 
  ticktype = "detailed")

## play with palettes
plot3d(sin(z) * cos(w) ~ z + w, col.surface = heat.colors, data = dat)
plot3d(sin(z) * cos(w) ~ z + w, col.surface = topo.colors, data = dat)
plot3d(sin(z) * cos(w) ~ z + w, col.surface = cm.colors, data = dat)
plot3d(sin(z) * cos(w) ~ z + w, col.surface = rainbow, data = dat)
plot3d(sin(z) * cos(w) ~ z + w, col.surface = terrain.colors, data = dat)

plot3d(sin(z) * cos(w) ~ z + w, col.surface = rainbow_hcl, data = dat)
plot3d(sin(z) * cos(w) ~ z + w, col.surface = diverge_hcl, data = dat)
plot3d(sin(z) * cos(w) ~ z + w, col.surface = sequential_hcl, data = dat)

plot3d(sin(z) * cos(w) ~ z + w, 
  col.surface = rainbow_hcl(n = 99, c = 300, l = 80, start = 0, end = 100), 
  data = dat)
plot3d(sin(z) * cos(w) ~ z + w, 
  col.surface = rainbow_hcl(n = 99, c = 300, l = 80, start = 0, end = 100), 
  image = TRUE, grid = 200, data = dat)

R2BayesX

Estimate Structured Additive Regression Models with 'BayesX'

v1.1-1

GPL-2 | GPL-3

Authors

Nikolaus Umlauf [aut, cre], Thomas Kneib [aut], Stefan Lang [aut], Achim Zeileis [aut] (0000-0003-0918-3766)

Initial release

2017-12-05