layer              package:latticeExtra              R Documentation

_C_o_n_v_e_n_i_e_n_t_l_y _a_u_g_m_e_n_t _t_r_e_l_l_i_s _o_b_j_e_c_t_s

_D_e_s_c_r_i_p_t_i_o_n:

     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.

_U_s_a_g_e:

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

     ## S3 method for class 'trellis':
     x + lay

     flattenPanel(x)

_A_r_g_u_m_e_n_t_s:

     ...: 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. 

_D_e_t_a_i_l_s:

     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.

_V_a_l_u_e:

     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.

_A_u_t_h_o_r(_s):

     Felix Andrews felix@nfrac.org

_S_e_e _A_l_s_o:

     'update.trellis', 'as.layer'

_E_x_a_m_p_l_e_s:

     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)

