rpanel (version 1.1-5.2)

rp.plot4d: Animated scatterplot

Description

This function plots two covariates coloured by a response variable and animates this by a third covariate. In particular, it is useful for plotting spatiotemporal data.

Usage

rp.plot4d(x, z, y, model, group, subset, col.palette, col.breaks, col.labels,
                  hscale = 1, vscale = hscale, panel = TRUE,
                  x1lab, x2lab, zlab, ylab,
                  display = "image", Display = NULL,
                  background.plot = NULL, foreground.plot = NULL, 
                  z.window = "normal", z.window.pars = c(min(z), sd(z)/5),
                  coords = rep(NA, 2), radius = 0.05,  col.circle = "black",
                  lwd.circle = 1,
                  location.plot = TRUE, retain.location.plot = FALSE,
                  group.level, group.name,
                  eqscplot = FALSE, location.plot.type = "histogram")
 
   rp.spacetime(space, time, y, model, group, subset, col.palette, col.breaks, col.labels,
                  hscale = 1, vscale = hscale, panel = TRUE,
                  x1lab, x2lab, zlab, ylab,
                  display = "image", Display = NULL,
                  background.plot = NULL, foreground.plot = NULL,
                  time.window = "normal",
                  time.window.pars = c(min(time), sd(time)/5),
                  coords = rep(NA, 2), radius = 0.05,  col.circle = "black",
                  lwd.circle = 1,
                  location.plot = TRUE, retain.location.plot = FALSE,
                  group.level, group.name,
                  eqscplot = TRUE, location.plot.type = "histogram")

Value

Nothing is returned.

Arguments

x, space

a two column matrix of covariates, in particular defining spatial locations.

z, time

a vector of values, such as times, over which the scatterplot will be animated.

y

a vector of response values which will be used to colour the plotted points.

model

a list with components x (a two-column matrix), z (a vector) and y (an array) which defines the fitted values (y) over a regular grid of x and z values. When group is not present y should be three-dimensional. When group is present it should be four-dimensional, with the fourth dimension indexing the fitted values of the model at the different levels of group.

group

an optional factor allowing plots to be created for each factor level.

subset

a vector of logical values or indices which will be used to subset x (or space), z (or time), y, group before plotting.

col.palette, col.breaks, col.labels

the colour palette used to colour the points, the break points on the scale which define the range associated with the each colour and the labels associated with the break points. If col.palette is missing, topo.colors(20) will be used, or topo.colors with the number of colours set by the number of levels when y is a factor. If col.breaks is missing then a regular grid over the range of the observed data is used. If col.labels is specified then the colour key has a grid of equally spaced colour blocks labelled by col.labels; otherwise the scale is linear. Setting col.breaks and col.labels differently can be useful if the data y are on a transformed scale but labels on the original scale are desired.

hscale, vscale

scaling parameters for the size of the plot when panel is set to TRUE. The default values are 1 on Unix platforms and 1.4 on Windows platforms.

panel

a logical value determining whether an interactive plot with control panel is created.

x1lab,x2lab,zlab,ylab

the axis labels of the variables

display

a character string which determines whether an "image" or "persp" plot is displayed.

Display

a logical vector which controls whether the points, and where present model and reference information, are displayed.

background.plot,foreground.plot

function to add further graphical material, such as a map, onto the background or foreground of the plot.

z.window,time.window

a character string which determines whether the window in z is initially "normal" or "uniform". This can be changed in the interactive panel.

z.window.pars,time.window.pars

a vector of length two which sets initial values for the location and width of the z.window. These values can be changed in the interactive panel.

coords

a vector of length two which defines the location of the window in the x space when the function is not used interactively (panel = FALSE).

radius

the radius of the window in the x space when the function is not used interactively.

col.circle,lwd.circle

the colour and line width of the circle used to define the window in the x space.

location.plot

a logical value which determines whether the mouse can be used to interact with the x plot to create a plot of y against z for a nominated neighbourhood.

retain.location.plot

a logical value which determines the initial state of the checkbox determining whether a plot of y against z for a nominated neighbourhood remains in place after the mouse has been released.

group.level

the initial value of the group factor. This defaults to the first level.

group.name

an optional character value giving a name to the group variable.

eqscplot

a logical value which determines whether the x plot is constructed by using the eqscplot function in the MASS package, so that the same distances on each axis represent the same changes in the corresponding axis variables.

location.plot.type

a character variable controlling whether a histogram or a density estimate (using the lattice package) is produced when y is a factor or absent and a location plot is requested by clicking the mouse on the plot of x.

Details

The colour black should be avoided when using a normal window shape for z. This is because hsv shading is used to indicate increasing distance from the current z location and black has an hsv representation with s component 0, which cannot therefore be reduced further.

References

rpanel: Simple interactive controls for R functions using the tcltk package. Journal of Statistical Software, 17, issue 9.

Examples

if (FALSE) {
# The quakes data

with(quakes, {
  rp.plot4d(cbind(long, lat), depth)
  rp.plot4d(cbind(long, lat), depth, mag)
})

# SO2 over Europe

with(SO2, {
  location <- cbind(longitude, latitude)

  if (require(mgcv) & require(maps)) {
     location1 <- location[,1]
     location2 <- location[,2]
     model <- gam(logSO2 ~ s(location1, location2, year))
     loc1  <- seq(min(location1), max(location1), length = 30)
     loc2  <- seq(min(location2), max(location2), length = 30)
     yr    <- seq(min(year), max(year), length = 30)
     newdata <- expand.grid(loc1, loc2, yr)
     names(newdata) <- c("location1", "location2", "year")
     model <- predict(model, newdata)
     model <- list(x = cbind(loc1, loc2), z = yr,
                   y = array(model, dim = rep(30, 3)))
     mapxy <- map('world', plot = FALSE,
                  xlim = range(longitude), ylim = range(latitude))
     rp.plot4d(location, year, logSO2, model,
                 col.palette = rev(heat.colors(20)),
                 foreground.plot = function() map(mapxy, add = TRUE))
  }
  else
    rp.plot4d(location, year, logSO2, col.palette = rev(heat.colors(20)))
})

# Dissolved Oxygen in the River Clyde

with(Clyde, {

  rp.plot4d(cbind(Doy, DO), Station, location.plot = FALSE)
  rp.plot4d(cbind(Station, DO), Doy, location.plot = FALSE)
  rp.plot4d(cbind(Station, Doy), Year, DO)

  # Highlight the data before and after a sewage treatment plant update in 1985
  ind     <- Year >= 80 & Year <= 89 & !(Year == 85)
  year    <- Year[ind] + Doy[ind] / 365
  station <- Station[ind]
  doy     <- Doy[ind]
  do      <- DO[ind]
  group   <- factor(c("after 1985", "before 1985")[1 + 
                  as.numeric(year < 85)])
  rp.plot4d(cbind(doy, do), station, group,
       col.palette = c("red", "green"), location.plot = FALSE)
})

}