R Graphical Manual

Browse All

Last data update: 2014.03.03

R: Dynamic 3d plot for 'mer' object.

plotLMER3d.fnc

R Documentation

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", alpha = 1, alpha.rs = 0.65, alpha.u = 1, 
lit = TRUE, theta = 0, phi = 0, contourstepsize = 0.2, legend.args = NULL, 
play3d = FALSE, ref.surf = FALSE, underneath = FALSE, add.raw = FALSE, 
color.raw = "grey", alpha.raw = 0.5, rug = FALSE, rug.u = 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), `"image.plot"` if package `fields` is available, `"persp"`, or, if package `rgl` is available, `"persp3d"`.
`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.
`alpha, alpha.rs, alpha.raw, alpha.u`	For `plot.type = "persp3d"`, alpha values between 0.0 (fully transparent) to 1.0 (opaque) for the main 3d surface, the reference surface, the added raw surface, and the "underneath" surface, respectively.
`lit`	Logical, specifying if lighting calculation should take place on geometry.
`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`.
`play3d`	If `plot.type = "persp3d"` and `play3d` is set to `TRUE`, the 3d plot will spin around `axis` `c(0, 0, 1)` at `rpm` `4` for `duration` `20` seconds. The `axis`, `rpm`, and `duration` can be changed by supplying a three-argument list where the first argument is a three-element vector for the rotation axis, the second argument is an interger for the rotations per minute (rpm), and the the third argument is a rotation duration time.
`ref.surf`	If `plot.type = "persp3d"`, whether a reference surface at the mean ought to be plotted. Defaults to `FALSE`.
`underneath`	If `plot.type = "persp3d"`, whether a flat miror image of the 3d surface ought to be plotted underneath it. Defaults to `FALSE`.
`add.raw`	If `plot.type = "persp3d"`, whether to add a surface representing the raw data. Defaults to `FALSE`.
`color.raw`	The colour scheme to use for the raw data surface. One of `topo`, `heat`, `cm`, `terrain`, `gray` or `bw`. Schemes `gray`, `grey`, and `bw` also modify the colors used.
`rug`	Whether a rug ought to be plotted on the 3d surface. Defaults to `FALSE`.
`rug.u`	For `plot.type = "persp3d"`, whether a rug ought to be plotted on the flat miror image of 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 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 plot.type = "persp3d", a 2d plot as created by plotLMER.fnc as well as a dynamic 3d plot as created by persp3d. 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, Dalhousie University, trea26@gmail.com.

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)
  if(try(require(rgl,quietly=TRUE))){
    require(rgl)
    open3d()
    plotLMER3d.fnc(pred = "LengthBc", intr = "WMCc",
      plot.type = "persp3d", plot.dat = "z", path = temp.dir)
  }
}

Results


R version 3.3.1 (2016-06-21) -- "Bug in Your Hair"
Copyright (C) 2016 The R Foundation for Statistical Computing
Platform: x86_64-pc-linux-gnu (64-bit)

R is free software and comes with ABSOLUTELY NO WARRANTY.
You are welcome to redistribute it under certain conditions.
Type 'license()' or 'licence()' for distribution details.

R is a collaborative project with many contributors.
Type 'contributors()' for more information and
'citation()' on how to cite R or R packages in publications.

Type 'demo()' for some demos, 'help()' for on-line help, or
'help.start()' for an HTML browser interface to help.
Type 'q()' to quit R.

> library(LMERConvenienceFunctions)
> png(filename="/home/ddbj/snapshot/RGM3/R_CC/result/LMERConvenienceFunctions/plotLMER3d.fnc.Rd_%03d_medium.png", width=480, height=480)
> ### Name: plotLMER3d.fnc
> ### Title: Dynamic 3d plot for 'mer' object.
> ### Aliases: plotLMER3d.fnc
> ### Keywords: hplot
> 
> ### ** 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)
+   if(try(require(rgl,quietly=TRUE))){
+     require(rgl)
+     open3d()
+     plotLMER3d.fnc(pred = "LengthBc", intr = "WMCc",
+       plot.type = "persp3d", plot.dat = "z", path = temp.dir)
+   }
+ }
> 
> 
> 
> 
> 
> dev.off()
null device 
          1 
>

Dynamic 3d plot for mer object.