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

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 and is likely to change. It probably should not be used routinely, since it does not fit well with the trellis model, and the implementation is fairly inefficient. A better option for interactive use is to edit the panel function directly.

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.

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.

Author(s)

Felix Andrews felix@nfrac.org

See Also

update.trellis, as.layer

Examples

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)