layer: Conveniently augment trellis objects

Description

A convenience mechanism to add new layers to a trellis object, optionally using a new data source. This works by augmenting the panel function with arbitrary expressions, defined using the layer() function.

Usage

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

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

undoLayer(x)
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.

layer

index of the layer, used only to set lattice graphical parameters.

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. Then undoLayer returns the original trellis object.

Details

The layer mechanism allows for incremental design of trellis displays. It is an alternative to editing the panel function, designed mainly for interactive use. This is an experimental feature and is likely to change. When the data argument is TRUE, an attempt is made to use the object passed as a data argument in the original lattice plot call. The undoLayer function will reverse the effect of the layer last added to a trellis object. It can be applied repeatedly. 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

## remove the colour
foo <- undoLayer(foo)
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) +
   layer2(panel.loess(x,y,span=.5)) +
   layer3(panel.loess(x,y,span=1))

## 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)