plotLMER3d.fnc {LMERConvenienceFunctions}

Dynamic 3d plot for mer object.

Description

Plot dynamic 3d partial effects of a (generalized) linear mixed-effects model fit with LMER.

Usage

plotLMER3d.fnc(model = NULL, pred, intr, plot.type = "contour",
xlim = range(x, na.rm = TRUE), ylim = range(y, na.rm = TRUE), 
zlim = range(z, na.rm = TRUE), xlab = NULL, 
ylab = NULL, zlab = NULL, main = NULL, shift = 0, scale = 1, cex = 1, 
fun = NA, n = 30, color = "topo", theta = 0, phi = 0,
contourstepsize = 0.2, legend.args = NULL, rug = FALSE, 
plot.dat = "default", path = "default", ...)

Arguments

model

A mer object or NULL (the default) to plot from an existing data-plotting object returned by this function and saved as an .rda file.

pred

The quoted name of a model predictor.

intr

The quoted name of a continuous model predicor.

plot.type

The type of plot to make. Can be any of "contour" (default), or "image.plot" if package fields is available, "persp"

xlim, ylim, zlim

x-, y- and z-limits. The plot is produced so that the rectangular volume defined by these limits is visible.

xlab, ylab, zlab

Titles for the axes. N.B. These must be character strings; expressions are not accepted. Numbers will be coerced to character strings.

main

The main title on top of the plot.

shift

Constant to add to the smooth (on the scale of the linear predictor) before plotting. Defaults to 0. Passed to plotRaw3d.fnc.

scale

Constant by which to multiply the smooth before plotting. Defaults to 1. Passed to plotRaw3d.fnc.

cex

The size of label and main text.

fun

A function to be applied for transforming the dependent variable, if NA, no transformation is applied; for models with family = "binomial", fun is set to plogis by default; this can be disabled by setting fun=function(x)return(x).

n

Integer denoting number of points for the plot, chosen at equally spaced intervals across the empirical range of the predictor variable.

color

The colour scheme to use for plots. One of topo, heat, cm, terrain, gray or bw. Schemes gray, grey, and bw also modify the colors used.

theta

Angle defining the viewing direction. theta gives the azimuthal direction. Used only if plot.type = "persp".

phi

Angle defining the viewing direction. phi gives the colatitude. Used only if plot.type = "persp".

contourstepsize

The size of the steps from contour line to contour line.

legend.args

When plot.type = "image.plot", arguments for a complete specification of the legend label. This is in the form of list and is just passed to the mtext function. (See example in image.plot help page). Defaults to NULL.

rug

Whether a rug ought to be plotted on the 3d surface. Defaults to FALSE.

plot.dat, path

Whether to cache the plotting data generated by a previous call to plotLMER3d.fnc. Generating the 3d plots can be time consuming. If the plot.dat argument is non-FALSE, the plotting information generated in the first call to the function will be saved so that in a second call to the function with exactly the same argument values, the plotting information will be retrieved and plotting will be significantly quicker. If plotting.data = "default" and path = "default", the plotting information will be saved in a temporary directory and the name of the file containing the information will equal to paste("lmer___",model@call,pred,intr,".rda",sep=""). The name of the file and the path where it will be saved can be set by the user in the plot.dat and path arguments. For example, plot.dat = "my_plotting.data", path = "Documents". Note that "lmer___" will be appended to the begining of whatever is specified in plot.dat and ".rda" to the end. Also note that if the user wants to save the plotting information returned by this function, the name of this object has to be z.

...

Further arguments to be passed to image, contour, image.plot, persp, or persp3d.

Details

See help page to Harald Baayen's plotLMER.fnc function as well as to Duncan Murdoch's persp3d function and the help page to function image.plot from package fields. To save screenshots of "persp3d" plots (after plotting), use function rgl.snapshot (produces png files) or function rgl.postscript (produces eps files).

Value

Invisibly returns plotting information (x and y vectors, z matrix, and colors, col). If plot.type = "contour", plot.type = "image.plot", or plot.type = "persp", a contour or perspective plot, respectively. If ret = TRUE, a two-element list is returned containing the matrix and the matrix of corresponding colors is returned. If argument intel in non-null, a file containing plotting information will be saved.

Author(s)

Antoine Tremblay, Statistics Canada, [e-mail].

See Also

persp; contour; plotLMER.fnc.

Examples

if(try(require(LCFdata,quietly=TRUE))){
	data(z)
	temp.dir <- tempdir()
	save(z,file=file.path(temp.dir,"lmer___z.rda"))

  plotLMER3d.fnc(pred = "LengthBc", intr = "WMCc", 
    plot.dat = "z", path = temp.dir)
  plotLMER3d.fnc(pred = "LengthBc", intr = "WMCc",
    plot.type = "persp", phi = 25, plot.dat = "z", 
    path = temp.dir)
}