cgam (version 1.6)

plotpersp: Create a 3D Plot for a CGAM or WPS Object

Description

Given an object of the cgam class, which has at least two non-parametrically modelled predictors, this routine will make a 3D plot of the fit with a set of two non-parametrically modelled predictors in the formula being the x and y labs. If there are more than two non-parametrically modelled predictors, any other such predictor will be evaluated at the largest value which is smaller than or equal to its median value.

If there is any categorical covariate and if the user specifies the argument categ to be a character representing a categorical covariate in the formula, then a 3D plot with multiple parallel surfaces, which represent the levels of a categorical covariate in an ascending order, will be created; otherwise, a 3D plot with only one surface will be created. Each level of a categorical covariate will be evaluated at its mode.

This routine is extended to make a 3D plot for an object of the wps class, which has only two isotonically modelled predictors. See the documentation below for more details.

This routine is an extension of the generic R graphics routine persp.

Usage

plotpersp(object,...)

Arguments

object

An object of the cgam class with at least two non-parametrically modelled predictors, or an object of the wps class.

...

Arguments to be passed to the S3 method for the cgam or wps class:

• x1: A non-parametrically modelled predictor in a cgam or wps fit. For a cgam object, if the user omits x1 and x2, then the first two non-parametric predictors in a cgam formula will be used; for a wps object, x1 and x2 can be omitted.

• x2: A non-parametrically modelled predictor in a cgam or wps fit. For a cgam object, if the user omits x1 and x2, then the first two non-parametric predictors in a cgam formula will be used; for a wps object, x1 and x2 can be omitted.

• data: The data frame based on which the user get a cgam or wps fit.

• surface: The type of the surface of a 3D plot. For a cgam fit, if surface == "mu", then the surface of the estimated mean value of the fit will be plotted; if surface == "eta", then the surface of the estimated systematic component value of the fit will be plotted. The default is surface = "mu"; for a wps fit, if surface == "C", then the surface of the constrained estimated mean value of the fit will be plotted, while if surface == "U", then the surface of the unconstrained estimated mean value of the fit will be plotted. The default is surface = "C".

• categ: Optional categorical covariate(s) in a cgam or wps fit. If there is any categorical covariate and if the user specifies the argument categ to be a character representing a categorical covariate in the formula, then a 3D plot with multiple parallel surfaces, which represent the levels of a categorical covariate in an ascending order, will be created; otherwise, a 3D plot with only one surface will be created. Each level of a categorical covariate will be evaluated at its mode. The default is categ = NULL.

• col: The color(s) of a 3D plot created by plotpersp. If col == NULL, "white" will be used when there is only one surface in the plot, and a sequence of colors will be used in a fixed order when there are multiple parallel surfaces in the plot. For example, when there are two surfaces, the lower surface will be in the color "peachpuff", and the higher surface will be in the color "lightblue". The default is col = NULL.

• random: A logical scalar. If random == TRUE, color(s) for a 3D plot will be randomly chosen from ten colors, namely, "peachpuff", "lightblue", "limegreen", "grey", "wheat", "yellowgreen", "seagreen1", "palegreen", "azure", "whitesmoke"; otherwise, "white" will be used when there is only one surface in the plot, and a sequence of colors will be used in a fixed order when there are multiple parallel surfaces in the plot.

• x_grid: This is a positive integer specifying how dense the \(x\) grid will be. The default is x_grid = \(10\). Note that this argument is only used for a cgam fit.

• y_grid: This is a positive integer specifying how dense the \(y\) grid will be. The default is y_grid = \(10\). Note that this argument is only used for a cgam fit.

• xlim: The xlim argument inherited from the persp routine.

• ylim: The ylim argument inherited from the persp routine.

• zlim: The zlim argument inherited from the persp routine.

• xlab: The xlab argument inherited from the persp routine.

• ylab: The ylab argument inherited from the persp routine.

• zlab: The zlab argument inherited from the persp routine.

• main: The main argument inherited from the persp routine.

• th: The theta argument inherited from the persp routine.

• ltheta: The ltheta argument inherited from the persp routine.

• ticktype: The ticktype argument inherited from the persp routine.

• ...: More parameters which could be passed to "persp".

Value

The routine plotpersp returns a 3D plot of an object of the cgam class or the wps class. The \(x\) lab and \(y\) lab represent a set of non-parametrically modelled predictors used in a cgam formula and represent the two isotonically modelled predictors in a wps formula. For a cgam fit, the \(z\) lab represents the estimated mean value or the estimated systematic component value, and for a wps fit, the \(z\) lab represents the constrained or the unconstrained estimated mean value.

References

The official documentation for the generic R routine persp: http://stat.ethz.ch/R-manual/R-patched/library/graphics/html/persp.html

Examples

# Example 1.
  data(FEV)

  # extract the variables
  y <- FEV$FEV
  age <- FEV$age
  height <- FEV$height
  sex <- FEV$sex
  smoke <- FEV$smoke

  fit <- cgam(y ~ incr(age) + incr(height) + factor(sex) + factor(smoke), nsim = 0)
  fit.s <- cgam(y ~ s.incr(age) + s.incr(height) + factor(sex) + factor(smoke), nsim = 0)

  plotpersp(fit, age, height, x_grid = 10, y_grid = 10, main = "Cgam Increasing Fit", 
  sub = "Categorical Variable: Sex", categ = "sex")
  plotpersp(fit.s, age, height, x_grid = 10, y_grid = 10, main = "Cgam Smooth Increasing Fit", 
  sub = "Categorical Variable: Smoke", categ = "smoke")

# Example 2.
  data(plasma)

  # extract the variables
  y <- plasma$logplasma
  bmi <- plasma$bmi
  logdietfat <- plasma$logdietfat
  cholest <- plasma$cholest
  fiber <- plasma$fiber
  betacaro <- plasma$betacaro
  retinol <- plasma$retinol
  smoke <- plasma$smoke
  vituse <- plasma$vituse

  fit <- cgam(y ~  s.decr(bmi) + s.decr(logdietfat) + s.decr(cholest) + s.incr(fiber) 
+ s.incr(betacaro) + s.incr(retinol) + factor(smoke) + factor(vituse)) 

  plotpersp(fit, bmi, logdietfat, x_grid = 10, y_grid = 10, th = 120, ylab = "log(dietfat)", 
zlab = "est mean of log(plasma)", main = "Cgam Fit with the Plasma Data Set", 
sub = "Categorical Variable: Vitamin Use", categ = "vituse")

# Example 3.
  data(plasma)
  addl <- 1:314*0 + 1 
  addl[runif(314) < .3] <- 2
  addl[runif(314) > .8] <- 4
  addl[runif(314) > .8] <- 3

  ans <- cgam(logplasma ~ s.incr(betacaro, 5) + s.decr(bmi) + s.decr(logdietfat) 
+ as.factor(addl), data = plasma)
  plotpersp(ans, betacaro, logdietfat, th = 240, random = TRUE, 
categ = "addl", data = plasma)

# Example 4.
  n <- 100
  set.seed(123)
  x1 <- sort(runif(n))
  x2 <- sort(runif(n))
  y <- 4 * (x1 - x2) + rnorm(n, sd = .5)

  # regress y on x1 and x2 under the shape-restriction: "decreasing-increasing"
  # with a penalty term = .1
  ans <- wps(y ~ di(x1, x2), pen = .1)

# plot the constrained surface
  plotpersp(ans, surface = "C")
# plot the unconstrained surface
  plotpersp(ans, surface = "U", th = 120)