Common Bivariate Trellis Plots

These are the most commonly used high level Trellis functions to plot pairs of variables. By far the most common is xyplot, designed mainly for two continuous variates (though factors can be supplied as well, in which case they will simply be coerced to numeric), which produces Conditional Scatterplots. The others are useful when one of the variates is a factor or a shingle. Most of these arguments are also applicable for other high level functions in the lattice package, but are only documented here.

       data = parent.frame(),
       panel = if (is.null(groups)) "panel.xyplot"
               else "panel.superpose",
       aspect = "fill",
       as.table = FALSE,
       auto.key = FALSE,
       strip = "strip.default",
       panel.groups = "panel.xyplot",
        panel = "panel.dotplot",
        groups = NULL,
        subset = TRUE)
         panel = "panel.barchart",
         box.ratio = 2,
         groups = NULL,
         subset = TRUE)
          panel = "panel.stripplot",
          jitter = FALSE,
          factor = .5,
          box.ratio = if (jitter) 1 else 0,
          groups = NULL,
          subset = TRUE)
       panel = "panel.bwplot",
       box.ratio = 1,
       subset = TRUE)
a formula describing the form of conditioning plot. The formula is generally of the form y ~ x | g1 * g2 * ..., indicating that plots of y (on the y axis) versus x (on the x axis) should be produced condi
a data frame containing values for any variables in the formula, as well as groups and subset if applicable. By default the environment where the function was called from is used.
allow.multiple, outer
logical flags to control what happens with formulas like y1 + y2 ~ x. See the entry for formula for details. allow.multiple defaults to TRUE whenever it makes sense, and outer
applicable to bwplot, barchart and stripplot, specifies the ratio of the width of the rectangles to the inter rectangle space.
logical, applicable to bwplot, dotplot, barchart and stripplot. Determines which of x and y is to be a factor or shingle (y if TRUE, x otherwise). Defaults to
logical specifying whether the values should be jittered by adding a random noise in stripplot.
numeric controlling amount of jitter as in jitter.
Once the subset of rows defined by each unique combination of the levels of the grouping variables are obtained (see details), the corresponding x and y variables (or other variables, as appropriate, in the case of ot
useful mostly for xyplot and densityplot. Applies when panel is panel.superpose (which happens by default in these cases if groups is non-null)
controls physical aspect ratio of the panels (same for all the panels). It can be specified as a ratio (vertical size/horizontal size) or as a character string. Legitimate values are "fill" (the default) which tries to make the panels as
logical that controls the order in which panels should be plotted: if FALSE (the default), panels are drawn left to right, bottom to top (as in a graph); if TRUE, left to right, top to bottom.
a list with components x and y (both usually 0 by default), numeric vectors specifying the space between the panels (units are character heights). x and y are repeated to account for all pane
a variable or expression to be evaluated in the data frame specified by data, expected to act as a grouping variable within each panel, typically used to distinguish different groups by varying graphical parameters like color and
A logical (indicating whether a key is to be drawn automatically when a grouping variable is present in the plot), or a list of parameters that would be valid arguments to simpleKey. If
A list of arguments that define a legend to be drawn on the plot. This list is used as an argument to the draw.key function, which produces a grid object eventually plotted by the print method
the legend argument can be useful if one wants to place more than one key. It also allows one to use arbitrary ``grob''s (grid objects) as legends. If used, legend must be a list, with an arbitrary number of components. E
In general, a Trellis conditioning plot consists of several panels arranged in a rectangular array, possibly spanning multiple pages. layout determines this arrangement.

layout is a numeric vector giving the number o

typically a character string or expression or list describing the main title to be placed on top of each page. Defaults to NULL. Can be a character string or expression, or a list with components label, cex
a function of one argument (page number) to be called after drawing each page. The function must be `grid-compliant', and is called with the whole display area as the default viewport.
list of graphical parameters to control the strip text, possible components are col, cex, font and lines. The first three control graphical parameters while the last is a means of altering t
function that takes the same arguments as the panel function and returns a list, possibly containing components named xlim, ylim, dx and dy (and less frequently, xat
list determining how the x- and y-axes (tick marks and labels) are drawn. The list contains parameters in name=value form, and may also contain two other lists called x and y of the same form (described
logical vector (default FALSE), replicated to be as long as the number of panels (spanning all pages). For elements that are TRUE, the corresponding panel position is skipped; i.e., nothing is plotted in that positio
logical flag or function. If FALSE, strips are not drawn. Otherwise, strips are drawn using the strip function, which defaults to strip.default. See documentation of strip.default to see th
character string or expression (or a ``grob'') for a subtitle to be placed at the bottom of each page. See entry for main for finer control options.
logical specifying whether or not a vector named subscripts should be passed to the panel function. Defaults to FALSE, unless groups is specified, or if the panel function accepts an argument named
logical or integer indexing vector (can be specified in terms of variables in data). Only these rows of data will be used for the plot. If subscripts is TRUE, the subscripts will provide in
character string or expression (or a ``grob'') giving label for the x-axis. Defaults to the expression for x in formula. Can be specified as NULL to omit the label altogether. Finer control is possible
Normally a numeric vector of length 2 (possibly a DateTime object) giving minimum and maximum for the x-axis, or, a character vector, expected to denote the levels of x. The latter form is interpreted as a range containing c(1, l
character string or expression (or ``grob'') giving label for the y-axis. Defaults to the expression for y in formula. Fine control is possible, see entry for xlab.
similar to xlim, applied to the y-axis.
logical indicating whether the unused levels of factors will be dropped. Unused levels are usually dropped, but it is sometimes appropriate to suppress dropping to preserve an useful layout. For finer control, this argument could also be lis
a list that could be supplied to trellis.par.set. This enables the user to attach some display settings to the trellis object itself rather than change the settings globally. When the o
numeric vector, a permutation of 1:n, where n is the number of conditioning variables. By default, the order in which panels are drawn depends on the order of the conditioning variables specified in the formula
While perm.cond permutes the dimensions of the multidimensional array of panels, index.cond can be used to subset (or reorder) margins of that array. index.cond can be a list or a function, with behaviou
list giving the default values of scales for a particular high level function. This should not be of any interest to the normal user, but may be helpful when defining other functions that act as a wrapper to one of the high level
other arguments, passed to the panel function.

The arguments horizontal and panel.groups are documented here to avoid confusion, but they are actually not recognised by these high level functions. Instead, they are


The structure of the plot that is produced depends mostly on the formula. For each unique combination of the levels of the conditioning variables g1, g2, ..., a separate panel is produced using the points (x,y) for the subset of the data (also called packet) defined by that combination. The panels can be though of as a 3-dimensional array, consisting of one 2-dimensional matrix per page. The dimesions of this array are determined by the layout argument.

If there are no conditioning variables, the plot produced consists of a single panel.

The coordinate system used by lattice is almost always like a graph, with the origin at the bottom left, with axes increasing to left and up. In particular, panels are by default drawn starting from the bottom left corner, going right and then up; unless as.table = TRUE, in which case panels are drawn from the top left corner, going right and then down.

The order of the panels depends on the order in which the conditioning variables are specified, with g1 varying fastest. Within a conditioning variable, the order depends on the order of the levels (which for factors is usually in alphabetical order). Both of these orders can be modified using the index.cond and perm.cond arguments, possibly using the update method.


  • An object of class ``trellis''. The `update' method can be used to update components of the object and the `print' method (usually called by default) will plot it on an appropriate plotting device.


Most of the arguments documented here are also applicable for the other high level functions in the lattice package. These are not described in any detail elsewhere unless relevant, and this should be considered the canonical documentation for such arguments.

Any arguments passed to these functions and not recognized by them will be passed to the panel function. Most predefined panel functions have arguments that customize its output. These arguments are described only in the help pages for these panel functions, but can usually be supplied as arguments to the high level plot.


xyplot(formula, data = parent.frame(), allow.multiple = is.null(groups) || outer, outer = FALSE, auto.key = FALSE, aspect = "fill", panel = if (is.null(groups)) "panel.xyplot" else "panel.superpose", prepanel = NULL, scales = list(), strip = TRUE, groups = NULL, xlab, xlim, ylab, ylim, drop.unused.levels = lattice.getOption("drop.unused.levels"), ..., default.scales, subscripts = !is.null(groups), subset = TRUE) bwplot(formula, data = parent.frame(), allow.multiple = is.null(groups) || outer, outer = FALSE, auto.key = FALSE, aspect = "fill", panel = "panel.bwplot", prepanel = NULL, scales = list(), strip = TRUE, groups = NULL, xlab, xlim, ylab, ylim, box.ratio = 1, horizontal = NULL, drop.unused.levels = lattice.getOption("drop.unused.levels"), ..., default.scales, subscripts = !is.null(groups), subset = TRUE)

See Also

Lattice, print.trellis, shingle, banking, reshape, panel.xyplot, panel.bwplot, panel.barchart, panel.dotplot, panel.stripplot, panel.superpose, panel.loess, panel.linejoin, strip.default, simpleKey trellis.par.set

  • xyplot
  • barchart
  • bwplot
  • dotplot
  • stripplot
## Tonga Trench Earthquakes
Depth <- equal.count(quakes$depth, number=8, overlap=.1)
xyplot(lat ~ long | Depth, data = quakes)
update(trellis.last.object(), aspect = "iso")

## Examples with data from `Visualizing Data' (Cleveland)
## (obtained from Bill Cleveland's Homepage :
## http://cm.bell-labs.com/cm/ms/departments/sia/wsc/, also
## available at statlib)

EE <- equal.count(ethanol$E, number=9, overlap=1/4)
## Constructing panel functions on the fly; prepanel
xyplot(NOx ~ C | EE, data = ethanol,
       prepanel = function(x, y) prepanel.loess(x, y, span = 1),
       xlab = "Compression Ratio", ylab = "NOx (micrograms/J)",
       panel = function(x, y) {
           panel.grid(h=-1, v= 2)
           panel.xyplot(x, y)
           panel.loess(x,y, span=1)
       aspect = "xy")

## with and without banking

plot <- xyplot(sunspot.year ~ 1700:1988, xlab = "", type = "l",
               scales = list(x = list(alternating = 2)),
               main = "Average Yearly Sunspots")
print(plot, position = c(0, .3, 1, .9), more = TRUE)
print(update(plot, aspect = "xy", main = "", xlab = "Year"),
      position = c(0, 0, 1, .3))

## Multiple variables in formula for grouped displays

xyplot(Sepal.Length + Sepal.Width ~ Petal.Length + Petal.Width | Species, 
       data = iris, scales = "free", layout = c(2, 2),
       auto.key = list(x = .6, y = .7, corner = c(0, 0)))

## user defined panel functions

states <- data.frame(state.x77,
                     state.name = dimnames(state.x77)[[1]], 
                     state.region = state.region) 
xyplot(Murder ~ Population | state.region, data = states, 
       groups = state.name, 
       panel = function(x, y, subscripts, groups)  
       ltext(x = x, y = y, label = groups[subscripts], cex=1,
             fontfamily = "HersheySans"))

barchart(yield ~ variety | site, data = barley,
         groups = year, layout = c(1,6),
         ylab = "Barley Yield (bushels/acre)",
         scales = list(x = list(abbreviate = TRUE,
                       minlength = 5)))
barchart(yield ~ variety | site, data = barley,
         groups = year, layout = c(1,6), stack = TRUE, 
         auto.key = list(points = FALSE, rectangles = TRUE, space = "right"),
         ylab = "Barley Yield (bushels/acre)",
         scales = list(x = list(rot = 45)))

bwplot(voice.part ~ height, data=singer, xlab="Height (inches)")
dotplot(variety ~ yield | year * site, data=barley)

dotplot(variety ~ yield | site, data = barley, groups = year,
        key = simpleKey(levels(barley$year), space = "right"),
        xlab = "Barley Yield (bushels/acre) ",
        aspect=0.5, layout = c(1,6), ylab=NULL)

stripplot(voice.part ~ jitter(height), data = singer, aspect = 1,
          jitter = TRUE, xlab = "Height (inches)")
## Interaction Plot

bwplot(decrease ~ treatment, OrchardSprays, groups = rowpos,
       panel = "panel.superpose",
       panel.groups = "panel.linejoin",
       xlab = "treatment",
       key = list(lines = Rows(trellis.par.get("superpose.line"),
                  c(1:7, 1)), 
                  text = list(lab = as.character(unique(OrchardSprays$rowpos))),
                  columns = 4, title = "Row position"))
Documentation reproduced from package lattice, version 0.10-10, License: GPL version 2 or later

Community examples

Looks like there are no examples yet.