layer {latticeExtra}R Documentation

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)

\S3method{+}{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 function arguments. In addition, data is used as the evaluation frame.
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 call is used.
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).
x a trellis object.
lay a layer 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 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

See Also

update.trellis, as.layer

Alias

layer, +.trellis, flattenPanel, print.layer

Keyword

aplot

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)

Results


R version 2.9.0 (2009-04-17)
Copyright (C) 2009 The R Foundation for Statistical Computing
ISBN 3-900051-07-0

R is free software and comes with ABSOLUTELY NO WARRANTY.
You are welcome to redistribute it under certain conditions.
Type 'license()' or 'licence()' for distribution details.

R is a collaborative project with many contributors.
Type 'contributors()' for more information and
'citation()' on how to cite R or R packages in publications.

Type 'demo()' for some demos, 'help()' for on-line help, or
'help.start()' for an HTML browser interface to help.
Type 'q()' to quit R.

> library(latticeExtra)
> png(filename="images/layer_%03d.png" ,width=480, height=480)
> ### Name: layer
> ### Title: Conveniently augment trellis objects
> ### Aliases: layer +.trellis flattenPanel print.layer
> ### Keywords: aplot
> 
> ### ** 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)
{
    panel.fill(grey(0.9))
    panel.xyplot(...)
    panel.abline(h = 0)
    panel.lmline(x, y)
    ok <- (y > 100)
    panel.text(x[ok], y[ok], y[ok], pos = 1)
}
> 
> ## 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)
> 
> 
> 
> dev.off()
null device 
          1 
>






[Package latticeExtra Index]