layer: Conveniently augment trellis objects

Description

A mechanism to add new layers to a trellis object, optionally using a new data source. This works by adding arbitrary expressions to the panel function. It can simplify programmatic augmentation of trellis objects.

Usage

layer(..., data = NULL, under = FALSE, style = NULL)

## S3 method for class 'trellis':
+(x, lay)

flattenPanel(x)

Arguments

...

expressions as they would appear in a panel function. These can refer to the panel function arguments (typically x, y and subscripts), or alternatively ..., which represents all panel func

data

an optional data source (data.frame, environment, etc: see eval). The value TRUE can be given, in which case the data argument from the lattice cal

under

whether the layer should be drawn below the existing panel.

style

style index of the layer, used only to set lattice graphical parameters (same effect as in grouped displays).

a trellis object.

lay

a layer object.

Value

a layer object is defined as a list of expression objects, each of which may have a data attribute. The result of "adding" a layer to a trellis object (+.trellis) is the updated trellis object.

Details

The layer mechanism is an alternative method for editing the panel function. It allows expressions to be added to the panel function without knowing what the original panel function was. In this way it can be useful for programmatic augmentation of trellis objects. A typical example would be adding a reference line to each panel: layer(panel.refline(h = 0)). Note that the expressions are quoted, so if you have local variables they will need to be passed in via the data object: layer(panel.refline(h = myVal), data = list(myVal = myVal)). Alternatively, eval(bquote( layer(panel.refline(h = .(myVal))) )). layer() is an experimental function. It probably should not be used in package code, since it does not fit well with the trellis model, and the implementation is fairly inefficient. A better option for package code is usually a custom panel function. When the data argument is TRUE, an attempt is made to extract the object passed as a data argument in the original lattice plot call. The flattenPanel function will construct a human-readable function incorporating code from all layers (and the original panel function). Note that this does not return a usable function, as it lacks the correct argument list and ignores any extra data sources that layers might use. It is intended be edited manually.

Examples

Run this code

foo <- xyplot(ozone ~ wind, environmental)

## overlay reference lines
foo <- foo + layer(panel.abline(h = 0)) +
             layer(panel.lmline(x, y))

## underlay a flat colour
foo <- foo + layer(panel.fill(grey(.9)), under = TRUE)
foo

## layers can access the panel function arguments
foo <- foo + layer(ok <- (y>100),
            panel.text(x[ok], y[ok], y[ok], pos = 1))
foo

## see an outline of the complete panel function
flattenPanel(foo)

## layers with superposed styles
zoip <- xyplot(ozone ~ wind | equal.count(temperature, 2),
        data = environmental) +
   layer(panel.loess(x, y, span = 0.5), style = 1) +
   layer(panel.loess(x, y, span = 1.0), style = 2)
update(zoip, key = simpleKey(c("span = 0.5", "span = 1.0"),
   title = "loess smooth", lines = TRUE, points = FALSE))

## using other variables from the original `data` object
## NOTE: need subscripts = TRUE in original call!
zoip <- xyplot(wind ~ temperature | equal.count(radiation, 2),
   data = environmental, subscripts = TRUE)
zoip + layer(panel.points(..., pch = 19,
   col = grey(1 - ozone[subscripts] / max(ozone))), data = TRUE)

## example of a new data source
qua <- xyplot(lat ~ long | cut(depth, 2), quakes,
    aspect = "iso", pch = ".", cex = 2)
qua
## add layer showing distance from Auckland
newdat <- with(quakes, expand.grid(
            gridlat = seq(min(lat), max(lat), length = 60),
            gridlon = seq(min(long), max(long), length = 60)))
newdat$dist <- with(newdat, sqrt((gridlat - -36.87)^2 +
                                 (gridlon - 174.75)^2))
qua + layer(panel.contourplot(gridlon, gridlat, dist,
   contour = TRUE, subscr = TRUE), data = newdat, under = TRUE)