pvisgam: Visualization of partial nonlinear interactions.
In itsadug: Interpreting Time Series and Autocorrelated Data Using GAMMs

pvisgam

R Documentation

Visualization of partial nonlinear interactions.

Description

Produces perspective or contour plot views of gam model predictions of the partial effects interactions. Combines the function plot.gam for interaction surfaces with the function vis.gam. Similar to plot.gam, pvisgam plots the partial interaction surface, without including values for other predictors that are not being shown. Similar to vis.gam the user can set the two predictors to be viewed, and colors are added behind the contours to facilitate interpretation. In contrast to plot.gam, this function allows to plotting of interactions with three of more continuous predictors by breaking it down in two-dimensional surfaces. The code is derivated from the script for vis.gam.

Usage

pvisgam(
  x,
  view = NULL,
  select = NULL,
  cond = list(),
  n.grid = 30,
  too.far = 0,
  col = NA,
  color = "terrain",
  contour.col = NULL,
  add.color.legend = TRUE,
  se = 0,
  plot.type = "contour",
  zlim = NULL,
  xlim = NULL,
  ylim = NULL,
  nCol = 50,
  labcex = 0.6,
  hide.label = FALSE,
  print.summary = getOption("itsadug_print"),
  show.diff = FALSE,
  col.diff = 1,
  alpha.diff = 0.5,
  dec = NULL,
  f = 1.96,
  ...
)

Arguments

`x`	A gam object, produced by `gam` or `bam`.
`view`	A two-value vector containing the names of the two main effect terms to be displayed on the x and y dimensions of the plot. Note that variables coerced to factors in the model formula won't work as view variables.
`select`	A number, selecting a single model term for printing. e.g. if you want the plot for the second smooth term set select=2.
`cond`	A named list of the values to use for the other predictor terms (not in view). Used for choosing between smooths that share the same view predictors.
`n.grid`	The number of grid nodes in each direction used for calculating the plotted surface.
`too.far`	Plot grid nodes that are too far from the points defined by the variables given in view can be excluded from the plot. too.far determines what is too far. The grid is scaled into the unit square along with the view variables and then grid nodes more than too.far from the predictor variables are excluded.
`col`	The colors for the facets of the plot.
`color`	The color scheme to use for plots. One of 'topo', 'heat', 'cm', 'terrain', 'gray' or 'bw'. Alternatively a vector with some colors can be provided for a custom color palette (see examples).
`contour.col`	sets the color of contours when using plot.
`add.color.legend`	Logical: whether or not to add a color legend. Default is TRUE. If FALSE (omitted), one could use the function `gradientLegend` to add a legend manually at any position.
`se`	If less than or equal to zero then only the predicted surface is plotted, but if greater than zero, then 3 surfaces are plotted, one at the predicted values minus se standard errors, one at the predicted values and one at the predicted values plus se standard errors.
`plot.type`	one of 'contour' or 'persp' (default is 'contour').
`zlim`	A two item array giving the lower and upper limits for the z- axis scale. NULL to choose automatically.
`xlim`	A two item array giving the lower and upper limits for the x- axis scale. NULL to choose automatically.
`ylim`	A two item array giving the lower and upper limits for the y- axis scale. NULL to choose automatically.
`nCol`	The number of colors to use in color schemes.
`labcex`	Size of the contour labels.
`hide.label`	Logical: whether or not to hide the label (i.e., 'partial effect'). Default is FALSE.
`print.summary`	Logical: whether or not to print summary. Default set to the print info messages option (see `infoMessages`).
`show.diff`	Logical: whether or not to indicate the regions that are significantly different from zero. Note that these regions are just an indication and dependent on the value of `n.grid`. Defaults to FALSE.
`col.diff`	Color to shade the nonsignificant areas.
`alpha.diff`	Level of transparency to mark the nonsignificant areas.
`dec`	Numeric: number of decimals for rounding the color legend. When NULL (default), no rounding. If -1 the values are automatically determined. Note: if value = -1 (default), rounding will be applied also when `zlim` is provided.
`f`	Scaling factor to determine the CI from the se, for marking the difference with 0. Only applies when `se` is smaller or equal to zero and `show.diff` is set to TRUE.
`...`	other options to pass on to persp, image or contour. In particular ticktype='detailed' will add proper axes labeling to the plots.

Warnings

In contrast to vis.gam, do not specify other predictors in cond that are not to be plotted.
When the argument show.diff is set to TRUE a shading area indicates where the confidence intervals include zero. Or, in other words, the areas that are not significantly different from zero. Be careful with the interpretation, however, as the precise shape of the surface is dependent on model constraints such as the value of choose.k and the smooth function used, and the size of the confidence intervals are dependent on the model fit and model characteristics (see vignette('acf', package='itsadug')). In addition, the value of n.grid determines the precision of the plot.

Author(s)

Jacolien van Rij. Modification of vis.gam from package mgcv of Simon N. Wood.

Examples

data(simdat)

## Not run: 
# Model with random effect and interactions:
m1 <- bam(Y ~ te(Time, Trial)+s(Time, Subject, bs='fs', m=1),
    data=simdat, discrete=TRUE)

# Plot summed effects:
vis.gam(m1, view=c('Time', 'Trial'), plot.type='contour', color='topo')
# Partial effect of interaction:
pvisgam(m1, view=c('Time', 'Trial'), select=1)
# Same:
plot(m1, select=1, scheme=2)
plot(m1, select=1)
# Alternatives:
pvisgam(m1, view=c('Trial', 'Time'), select=1)
pvisgam(m1, view=c('Trial', 'Time'), select=1, zlim=c(-20,20))
pvisgam(m1, view=c('Trial', 'Time'), select=1, zlim=c(-20,20), 
    color='terrain')
pvisgam(m1, view=c('Trial', 'Time'), select=1, zlim=c(-20,20), 
    color=c('blue', 'white', 'red'))

# Notes on the color legend:
# Labels can easily fall off the plot, therefore the numbers are 
# automatically rounded.
# To undo the rounding, set dec=NULL:
pvisgam(m1, view=c('Time', 'Trial'), dec=NULL)
# For custom rounding, set dec to a value:
pvisgam(m1, view=c('Time', 'Trial'), dec=1)
# To increase the left marging of the plot (so that the numbers fit):
oldmar <- par()$mar
par(mar=oldmar + c(0,0,0,1) ) # add one line to the right
pvisgam(m1, view=c('Time', 'Trial'), dec=3)
par(mar=oldmar) # restore to default settings

# too.far: 
n <- which(simdat$Time > 1500 & simdat$Trial > 5)
simdat[n,]$Y <- NA
simdat[simdat$Trial == -3,]$Y <- NA
m1 <- bam(Y ~ te(Time, Trial)+s(Time, Subject, bs='fs', m=1),
    data=simdat, discrete=TRUE)
pvisgam(m1, view=c('Time', 'Trial'), select=1, too.far=0.03)


## End(Not run)
# see the vignette for examples:
vignette('overview', package='itsadug')

itsadug documentation built on June 17, 2022, 5:05 p.m.