xyplot {lattice}R Documentation

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 Scatter plots. The others are useful when one of the variates is a factor or a shingle. Most of these arguments are also applicable to other high level functions in the lattice package, but are only documented here.


xyplot(x, data, ...)
dotplot(x, data, ...)
barchart(x, data, ...)
stripplot(x, data, ...)
bwplot(x, data, ...)

## S3 method for class 'formula':
       allow.multiple = is.null(groups) || outer,
       outer = !is.null(groups),
       auto.key = FALSE,
       aspect = "fill",
       panel = lattice.getOption("panel.xyplot"),
       prepanel = NULL,
       scales = list(),
       strip = TRUE,
       groups = NULL,
       drop.unused.levels = lattice.getOption("drop.unused.levels"),
       lattice.options = NULL,
       subscripts = !is.null(groups),
       subset = TRUE)

## S3 method for class 'formula':
        panel = lattice.getOption("panel.dotplot"),

## S3 method for class 'formula':
         panel = lattice.getOption("panel.barchart"),
         box.ratio = 2,

## S3 method for class 'formula':
          panel = lattice.getOption("panel.stripplot"),

## S3 method for class 'formula':
       allow.multiple = is.null(groups) || outer,
       outer = FALSE,
       auto.key = FALSE,
       aspect = "fill",
       panel = lattice.getOption("panel.bwplot"),
       prepanel = NULL,
       scales = list(),
       strip = TRUE,
       groups = NULL,
       box.ratio = 1,
       horizontal = NULL,
       drop.unused.levels = lattice.getOption("drop.unused.levels"),
       lattice.options = NULL,
       subscripts = !is.null(groups),
       subset = TRUE)


x The object on which method dispatch is carried out.
For the "formula" methods, 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 conditional on the variables g1, g2, .... However, the conditioning variables g1,g2,... may be omitted. The formula can also be supplied as y ~ x | g1 + g2 + ....
For all of these functions, with the exception of xyplot, a formula of the form ~ x | g1 * g2 * ... is also allowed. In that case, y defaults to names(x) if x is named, and a factor with a single level otherwise.
Other usage of the form dotplot(x) is handled by method dispatch as appropriate. The numeric method is equivalent to a call with no left hand side and no conditioning variables in the formula. For barchart and dotplot, non-trivial methods exist for tables and arrays, documented under barchart.table.
The conditioning variables g1, g2, ... must be either factors or shingles. Shingles are a way of processing numeric variables for use in conditioning. See documentation of shingle for details. Like factors, they have a "levels" attribute, which is used in producing the conditional plots.
Numeric conditioning variables are converted to shingles by the function shingle (however, using equal.count might be more appropriate in many cases) and character vectors are coerced to factors.
The formula can involve expressions, e.g. sqrt(), log().
A special case is when the left and/or right sides of the formula (before the conditioning variables) contain a ‘+’ sign, e.g., y1+y2 ~ x | a*b. This formula would be taken to mean that the user wants to plot both y1~x | a*b and y2~x | a*b, but with the y1~x and y2~x superposed in each panel (this is slightly more complicated in barchart). The two parts would be distinguished by different graphical parameters. This is essentially what the groups argument would produce, if y1 and y2 were concatenated to produce a longer vector, with the groups argument being an indicator of which rows come from which variable. In fact, this is exactly what is done internally using the reshape function. This feature cannot be used in conjunction with the groups argument.
To interpret y1 + y2 as a sum, one can either set allow.multiple=FALSE or use I(y1+y2).
A variation on this feature is when the outer argument is set to TRUE as well as allow.multiple. In that case, the plots are not superposed in each panel, but instead separated into different panels (as if a new conditioning variable had been added).
The x and y variables should both be numeric in xyplot, and an attempt is made to coerce them if not. However, if either is a factor, the levels of that factor are used as axis labels. In the other four functions documented here, exactly one of x and y should be numeric, and the other a factor or shingle. Which of these will happen is determined by the horizontal argument — if horizontal=TRUE, then y will be coerced to be a factor or shingle, otherwise x. The default value of horizontal is FALSE if x is a factor or shingle, TRUE otherwise. (The functionality provided by horizontal=FALSE is not S-compatible.)
Note that this argument used to be called formula in earlier versions (when the high level functions were not generic and the formula method was essentially the only method). This is no longer allowed. It is recommended that this argument not be named in any case, but rather be the first (unnamed) argument.
data For the formula method, a data frame containing values (or more precisely, anything that is a valid envir argument in eval, e.g. a list or an environment) for any variables in the formula, as well as groups and subset if applicable. If not found in data, or if data is unspecified, the variables are looked for in the environment of the formula. For other methods (where x is not a formula), data is usually ignored, often with a warning.
allow.multiple, outer logical flags to control what happens with formulas like y1 + y2 ~ x. See the entry for x for details. allow.multiple defaults to TRUE whenever it makes sense, and outer defaults to FALSE except when groups is explicitly specified or grouping doesn't make sense for the default panel function
box.ratio applicable to bwplot, barchart and stripplot, specifies the ratio of the width of the rectangles to the inter rectangle space.
horizontal 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 FALSE if x is a factor or shingle, TRUE otherwise. This argument is used to process the arguments to these high level functions, but more importantly, it is passed as an argument to the panel function, which is supposed to use it as appropriate.
A potentially useful component of scales in this case might be abbreviate = TRUE, in which case long labels which would usually overlap will be abbreviated. scales could also contain a minlength argument in this case, which would be passed to the abbreviate function.
panel 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 other high level functions) are passed on to be plotted in each panel. The actual plotting is done by the function specified by the panel argument. Each high level function has its own default panel function, which could depend on whether the groups argument was supplied.
The panel function can be a function object or a character string giving the name of a predefined function.
Much of the power of Trellis Graphics comes from the ability to define customized panel functions. A panel function appropriate for the functions described here would usually expect arguments named x and y, which would be provided by the conditioning process. It can also have other arguments. It might be useful to know in this context that all arguments passed to a high level Trellis function (such as xyplot) that are not recognized by it are passed through to the panel function. It is thus generally good practice when defining panel functions to allow a ... argument. Such extra arguments typically control graphical parameters, but other uses are also common. See documentation for individual panel functions for specifics.
Note that unlike in S-PLUS, it is not guaranteed that panel functions will be supplied only numeric vectors for the x and y arguments; they can be factors as well (but not shingles). Panel functions need to handle this case, which in most cases can be done by simply coercing them to numeric.
Technically speaking, panel functions must be written using Grid graphics functions. However, knowledge of Grid is usually not necessary to construct new custom panel functions, there are several predefined panel functions which can help; for example, panel.grid, panel.loess, etc. There are also some grid-compatible replacements of commonly used base R graphics functions useful for this purpose. For example, lines can be replaced by llines (or equivalently, panel.lines). Note that base R graphics functions like lines will not work in a lattice panel function.
One case where a bit more is required of the panel function is when the groups argument is not null. In that case, the panel function should also accept arguments named groups and subscripts (see below for details). A useful panel function predefined for use in such cases is panel.superpose, which can be combined with different panel.groups functions determining what is plotted for each group. See the examples section for an interaction plot constructed in this way. Several other panel functions can also handle the groups argument, including the default ones for barchart, dotplot and stripplot.
Even when groups is not present, the panel function can have subscripts as a formal argument. In either case, the subscripts argument passed to the panel function are the indices of the x and y data for that panel in the original data, BEFORE taking into account the effect of the subset argument. Note that groups remains unaffected by any subsetting operations, so groups[subscripts] gives the values of groups that correspond to the data in that panel. The value of subscripts becomes slightly more complicated when allow.multiple is in effect. Details can be found in the source code of the function latticeParseFormula.
A panel function can have two other optional arguments for convenience, namely panel.number and packet.number, representing panel order and packet order respectively. Both provide a simple integer index indicating which panel is currently being drawn, but differ in how the count is calculated. panel.number is a simple incremental counter that starts with 1 and is incremented each time a panel is drawn. packet.number on the other hand indexes the combination of levels of the conditioning variables that is represented by that panel. The two indices coincide unless the order of conditioning variables is permuted and/or the plotting order of levels within one or more conditioning variables is altered (using perm.cond and index.cond respectively), in which case packet.number gives the index corresponding to the ‘natural’ ordering of that combination of levels of the conditioning variables.
panel.xyplot has an argument called type which is worth mentioning here because it is quite frequently used (and as mentioned above, can be passed to xyplot directly). panel functions for bwplot and friends should have an argument called horizontal to account for the cases when x is the factor or shingle.
aspect 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 big as possible to fill the available space; "xy", which tries to compute the aspect based on the 45 degree banking rule (see Visualizing Data by William S. Cleveland for details); and "iso" for isometric scales, where the relation between physical distance on the device and distance in the data scale are forced to be the same for both axes.
If a prepanel function is specified and it returns components dx and dy, these are used for banking calculations. Otherwise, values from the default prepanel function are used. Currently, only the default prepanel function for xyplot can be expected to produce sensible banking calculations. See banking for details on the implementation of banking .
groups 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 line type. Formally, if groups is specified, then groups along with subscripts is passed to the panel function, which is expected to handle these arguments. Not all pre-defined panel functions know how to, but for high level functions where grouping is appropriate, the default panel functions are chosen so that they do.
It is very common to use a key (legend) when a grouping variable is specified. See entries for key, auto.key and simpleKey for how to draw a key.
auto.key 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 (in effect, most valid components of key can be specified in this manner). If auto.key is not FALSE, groups is non-null and there is no key or legend argument specified in the call, a key is created with simpleKey with levels(groups) as the first argument. (Note: this may not work in all high level functions, but it does work for the ones where grouping makes sense with the default panel function)
simpleKey uses the trellis settings to determine the graphical parameters in the key, so this will be meaningful only if the settings are used in the plot as well.
One disadvantage to using key (or even simpleKey) directly is that the graphical parameters used in the key are absolutely determined at the time when the "trellis" object is created. Consequently, if a plot once created is re-printed with different settings, the parameter settings for the original device will be used. However, with auto.key, the key is actually created at printing time, so the key settings will match the device settings.
prepanel 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 and yat).
The xlim and ylim components are similar to the high level xlim and ylim arguments (i.e., they are usually a numeric vector of length 2 defining a range of values, or a character vector representing levels of a factor). If the xlim and ylim arguments are not explicitly specified (possibly as components in scales), then the actual limits of the panels are guaranteed to include the limits returned by the prepanel function. This happens globally if the relation component of scales is "same", and on a panel by panel basis otherwise. See xlim to see what forms of the components xlim and ylim are allowed.
The dx and dy components are used for banking computations in case aspect is specified as "xy". See documentation for the function banking for details regarding how this is done.
The return value of the prepanel function need not have all the components named above; in case some are missing, they are replaced by the usual component-wise defaults.
If xlim or ylim is a character vector (which is appropriate when the corresponding variable is a factor), this implicitly indicates that the scale should include the first n integers, where n is the length of xlim or ylim, as the case may be. The elements of the character vector are used as the default labels for these n integers. Thus, to make this information consistent between panels, the xlim or ylim values should represent all the levels of the corresponding factor, even if some are not used within that particular panel.
In such cases, an additional component xat or yat may be returned by the prepanel function, which should be a subset of 1:n, indicating which of the n values (levels) are actually represented in the panel. This is useful when calculating the limits with relation="free" or relation="sliced" in scales.
The prepanel function is responsible for providing a meaningful return value when the x, y (etc.) variables are zero-length vectors. When nothing is appropriate, values of NA should be returned for the xlim and ylim components.
strip 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 the arguments that are available to the strip function. This description also applies to the strip.left argument (see ... below), which can be used to draw strips on the left of each panel, which can be useful for wide short panels, e.g. in time series plots.
xlab 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, as described in the entry for main, with the additional feature that if the label component is omitted from the list, it is replaced by the default xlab.
ylab 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 entries for main and xlab.
scales 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 below). Components of x and y affect the respective axes only, while those in scales affect both. When parameters are specified in both lists, the values in x or y are used. Note that certain high-level functions have defaults that are specific to a particular axis (e.g., bwplot has alternating=FALSE for the y-axis only); these can be overridden only by an entry in the corresponding component of scales.
The possible components are :
character string that determines how axis limits are calculated for each panel. Possible values are "same" (default), "free" and "sliced". For relation="same", the same limits, usually large enough to encompass all the data, are used for all the panels. For relation="free", limits for each panel is determined by just the points in that panel. Behavior for relation="sliced" is similar, except that the length (max - min) of the scales are constrained to remain the same across panels.
The determination of what axis limits are suitable for each panel can be controlled by the prepanel function, which can be overridden by xlim, ylim or scales$limits. If relation is not "same", the value of xlim etc is normally ignored, except when it is a list, in which case it is treated as if its components were the limit values obtained from the prepanel calculations for each panel.
Suggested number of ticks (ignored for a factor, shingle or character vector, in which case there is no natural rule for leaving out some of the labels. But see xlim).
logical, defaults to TRUE, whether to draw the axis at all.
logical specifying whether axis labels should alternate from one side of the group of panels to the other. For finer control, alternating can be a vector (replicated to be as long as the number of rows or columns per page) consisting of the following numbers
  • 0: do not draw tick labels
  • 1: bottom/left
  • 2: top/right
  • 3: both.
alternating applies only when relation="same". The default is TRUE, or equivalently, c(1, 2)
same as xlim and ylim.
location of tick marks along the axis (in native coordinates), or a list as long as the number of panels describing tick locations for each panel.
Labels (strings or expressions) to go along with at. Can be a list like at as well.
numeric multiplier to control character sizes for axis labels. Can be a vector of length 2, to control left/bottom and right/top separately.
font, fontface, fontfamily
specifies font for axis labels.
numeric to control length of tick marks. Can be a vector of length 2, to control left/bottom and right/top separately.
color of ticks and labels.
Angle by which the axis labels are to be rotated. Can be a vector of length 2, to control left/bottom and right/top separately.
logical, whether to abbreviate the labels using abbreviate. Can be useful for long labels (e.g., in factors), especially on the x-axis.
argument passed to abbreviate if abbreviate=TRUE.
whether to use a log scale. Defaults to FALSE, other possible values are any number that works as a base for taking logarithm, TRUE, equivalent to 10, and "e" (for natural logarithm). Note that in this case the values passed to the panel function are already transformed, so all computations done inside the panel function will be affected accordingly. For example, panel.lmline will fit a line to the transformed values.
the format to use for POSIXct variables. See strptime for description of valid values.
character, "r" or "i". In the latter case, the axis limits are calculated as the exact data range, instead of being padded on either side. (May not always work as expected.)

Note that much of the function of scales is accomplished by pscales in splom.
subscripts 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 subscripts. (One should be careful when defining the panel function on-the-fly.)
subset 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 indices to the rows of data before the subsetting is done. Whether levels of factors in the data frame that are unused after the subsetting will be dropped depends on the drop.unused.levels argument.
xlim 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, length(xlim)), with the character vector determining labels at tick positions 1:length(xlim)
xlim could also be a list, with as many components as the number of panels (recycled if necessary), with each component as described above. This is meaningful only when scales$x$relation is "free" or "sliced", in which case these are treated as if they were the corresponding limit components returned by prepanel calculations.
ylim similar to xlim, applied to the y-axis.
drop.unused.levels logical indicating whether the unused levels of factors will be dropped, usually relevant with a subsetting operation is performed or an interaction is created. Unused levels are usually dropped, but it is sometimes appropriate to suppress dropping to preserve a useful layout. For finer control, this argument could also be list containing components cond and data, both logical, indicating desired behavior for conditioning variables and data variables respectively. The default is given by lattice.getOption("drop.unused.levels"), which is initially set to TRUE for both components. Note that this argument does not control dropping of levels of the groups argument.
default.scales 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 lattice functions.
lattice.options a list that could be supplied to lattice.options. These options are temporarily in effect for the duration of the call, after which the settings revert back to whatever they were before. The settings are also retained along with the object and reused during plotting. This enables the user to attach options settings to the trellis object itself rather than change the settings globally. See also the par.settings argument described below for a similar treatment of graphical settings.
... further arguments, usually not directly processed by the high level functions documented here, but rather passed on to other functions. Such arguments can be broadly categorized into two types: those that affect all high level Trellis functions in a similar manner, and those that are meant for the specific panel function used, which may differ across high level functions.
The first group of arguments are processed by a common, unexported function called trellis.skeleton. These arguments affect all high level functions, but are only documented here, except to override the behaviour described here. All other arguments specified in a high level call, specifically those neither described here nor in the help page of the relevant high level function, are passed unchanged to the panel function used. By convention, the default panel function used for any high level function is named as "panel." followed by the name of the high level function; for example, the default panel function for bwplot is panel.bwplot. In practical terms, this means that in addition to the help page of the high level function being used, the user should also consult the help page of the corresponding panel function for arguments that may be specified in the high level call.
The effect of the first group of common arguments are as follows:

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 panels in a page and any extra components are ignored. The result is used for all pages in a multi page display. (In other words, it is not possible to use different between values for different pages).

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 for "trellis" objects.
There is also a less flexible but usually sufficient shortcut function simpleKey that can generate such a list, as well as the argument auto.key that can be convenient in the most common situation where legends are used, namely when there is a grouping variable. To use more than one legend, or to have arbitrary legends not constrained by the structure imposed by key, use the legend argument.
The position of the key can be controlled in either of two possible ways. If a component called space is present, the key is positioned outside the plot region, in one of the four sides, determined by the value of space, which can be one of "top", "bottom", "left" and "right". Alternatively, the key can be positioned inside the plot region by specifying components x, y and corner. x and y determine the location of the corner of the key given by corner, which can be one of c(0,0), c(1,0), c(1,1) and c(0,1), which denote the corners of the unit square. x and y must be numbers between 0 and 1, giving coordinates with respect to the whole display area.
The key essentially consists of a number of columns, possibly divided into blocks, each containing some rows. The contents of the key are determined by (possibly repeated) components named "rectangles", "lines", "points" or "text". Each of these must be lists with relevant graphical parameters (see later) controlling their appearance. The key list itself can contain graphical parameters, these would be used if relevant graphical components are omitted from the other components.
The length (number of rows) of each such column (except "text"s) is taken to be the largest of the lengths of the graphical components, including the ones specified outside (see the entry for rep below for details on this). The "text" component has to have a character or expression vector as its first component, and the length of this vector determines the number of rows.
The graphical components that can be included in key (and also in the components named "text", "lines", "points" and "rectangles" as appropriate) are:
  • cex=1
  • col="black"
  • alpha=1
  • lty=1
  • lwd=1
  • font=1
  • fontface
  • fontfamily
  • pch=8
  • adj=0
  • type="l"
  • size=5
  • angle=0
  • density=-1

angle and density are currently unimplemented. size determines the width of columns of rectangles and lines in character widths. type is relevant for lines; "l" denotes a line, "p" denotes a point, and "b" and "o" both denote both together.
Other possible components of key are:
logical, defaulting to FALSE. If TRUE, all components are reversed after being replicated (the details of which may depend on the value of rep). This is useful in certain situations, e.g. with a grouped barchart with stack = FALSE with the categorical variable on the vertical axis, where the bars in the plot will usually be ordered from bottom to top, but the corresponding legend will have the levels from top to bottom (unless, of course, reverse.rows = TRUE). Note that in this case, unless all columns have the same number or rows, they will no longer be aligned.
numeric vector giving the amount of space (character widths) surrounding each column (split equally on both sides)
string or expression giving a title for the key
logical, defaults to TRUE. By default, it's assumed that all columns in the key (except the "text"s) will have the same number of rows, and all components are replicated to be as long as the longest. This can be suppressed by specifying rep=FALSE, in which case the length of each column will be determined by components of that column alone.
cex for the title
how many lines the title should occupy (in multiples of itself). Defaults to 2.
how much space (padding) should be used above and below each row containing text, in multiples of the default, which is currently 0.2 * "lines". This padding is in addition to the normal height of any row that contains text, which is the minimum amount necessary to contain all the text entries.
background color, defaults to default background
An alpha transparency value between 0 and 1
either a color for the border, or a logical. In the latter case, the border color is black if border is TRUE, and no border is drawn if it is FALSE (the default)
logical, whether key area should have a transparent background
the number of columns column-blocks the key is to be divided into, which are drawn side by side.
Space between column blocks, in addition to between.
Number of point symbols to divide each line when type is "b" or "o" in lines.
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. Each component must be named one of "left", "right", "top", "bottom" or "inside". The name "inside" can be repeated, but not the others. This name will be used to determine the location for that component, and is similar to the space component of key. If key (or colorkey for levelplot and wireframe) is specified, their space component must not conflict with the name of any component of legend.
Each component of legend must have a component called fun. This can be a "grob", or a function or the name of a function that produces a "grob" when called. If this function expects any arguments, they must be supplied as a list in another component called args. For components named "inside", there can be additional components called x, y and corner, which work in the same way as it does for key.

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.
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, col, alpha and font. The label tag can be omitted if it is the first element of the list. Expressions are treated as specification of LaTeX-like markup as in plotmath.
main can also be an arbitrary "grob" (grid graphical object).
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.
list of parameters to control the appearance of strip text. Notable components are col, cex, font and lines. The first three control graphical parameters while the last is a means of altering the height of the strips. This can be useful, for example, if the strip labels (derived from factor levels, say) are double height (i.e., contains "\n"-s) or if the default height seems too small or too large. The lineheight component can control the space between multiple lines. Also, the labels can be abbreviated when shown by specifying abbreviate = TRUE, in which case the components minlength and dot (passed along to the abbreviate function) can be specified to control the details of how this is done.
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 of columns, rows and pages in a multi panel display. By default, the number of columns is the number of levels of the first conditioning variable and the number of rows is the number of levels of the second conditioning variable. If there is only one conditioning variable, the default layout vector is c(0,n), where n is the number of levels of the given vector. Any time the first value in the layout vector is 0, the second value is used as the desired number of panels per page and the actual layout is computed from this, taking into account the aspect ratio of the panels and the device dimensions (via par("din")). The number of pages is by default set to as many as is required to plot all the panels. In general, giving a high value of layout[3] is not wasteful because blank pages are never created.
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 position. The panel that was supposed to be drawn there is now drawn in the next available panel position, and the positions of all the subsequent panels are bumped up accordingly. This is often useful for arranging plots in an informative manner.

strip.left can be used to draw strips on the left of each panel, which can be useful for wide short panels, as in time series (or similar) plots. It is a function similar to strip.

xlab.default, ylab.default:
fallback default for xlab and ylab when they are not specified. If NULL, the defaults are parsed from the Trellis formula. This is rarely useful for the end-user, but can be helpful when developing new Trellis functions.

xscale.components, yscale.components:
functions that determine axis annotation for the x and y axes respectively. See documentation for xscale.components.default, the default values of these arguments, to learn more.

function that draws axis annotation. See documentation for axis.default, the default value of this argument, to learn more.

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. perm.cond can modify this order. If the trellis display is thought of as an n-dimensional array, then during printing, its dimensions are permuted using perm.cond as the perm argument to aperm.
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 behavior in each case described below.
The panel display order within each conditioning variable depends on the order of their levels. index.cond can be used to choose a ‘subset’ (in the R sense) of these levels, which is then used as the display order for that variable. If index.cond is a list, it has to be as long as the number of conditioning variables, and the i-th component has to be a valid indexing vector for the integer vector 1:nlevels(g_i) (which can, among other things, repeat some of the levels or drop some altogether). The result of this indexing determines the order of panels within that conditioning variable. To keep the order of a particular variable unchanged, the corresponding component must be set to TRUE.
Note that the components of index.cond are in the order of the conditioning variables in the original call, and is not affected by perm.cond.
Another possibility is to specify index.cond as a function. In this case, this function is called once for each panel, potentially with all arguments that are passed to the panel function for that panel. (More specifically, if this function has a ... argument, then all panel arguments are passed, otherwise, only named arguments that match are passed.) For a single conditioning variable, the levels of that variable are then sorted so that these values are in ascending order. For multiple conditioning variables, the order for each variable is determined by first taking the average over all other conditioning variables.
Although they can be supplied in high level function calls directly, it is more typical to use perm.cond and index.cond to update an existing "trellis" object, thus allowing it to be displayed in a different arrangement without re-calculating the data subsets that go into each panel. In the update method, both can be set to NULL, which reverts these back to their defaults.
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 object is plotted, these settings are temporarily in effect for the duration of the plot, after which the settings revert back to whatever they were before.
a list of possible arguments to plot.trellis, which will be used by the plot or print methods when drawing the object, unless overridden explicitly. This enables the user to attach such arguments to the trellis object itself. Partial matching is not performed.


All the functions documented here are generic, with the formula method usually doing the actual work. The structure of the plot that is produced is mostly controlled by 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 display can be though of as a 3-dimensional array of panels, consisting of one 2-dimensional matrix per page. The dimensions 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 by default is 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. One might wish to set a global preference for a table-like arrangement by changing the default to as.table=TRUE; this can be done by setting lattice.options(default.args = list(as.table = TRUE)). In fact, default values can be set in this manner for the following arguments: as.table, aspect, between, page, main, sub, par.strip.text, layout, skip and strip. Note that these global defaults are sometimes overridden by individual functions.

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 (and other related) method(s).


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.


Deepayan Sarkar Deepayan.Sarkar@R-project.org

See Also

Lattice for an overview of the package, as well as barchart.table, 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


## Not run: 
## wait for user input before each new page (like 'par(ask = TRUE)')
old.prompt <- grid::grid.prompt(TRUE)
## End(Not run)


## Tonga Trench Earthquakes

Depth <- equal.count(quakes$depth, number=8, overlap=.1)
xyplot(lat ~ long | Depth, data = quakes)
       strip = strip.custom(strip.names = TRUE, strip.levels = TRUE),
       par.strip.text = list(cex = 0.75),
       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 = "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

xyplot(decrease ~ treatment, OrchardSprays, groups = rowpos,
       type = "a",
       auto.key =
       list(space = "right", points = FALSE, lines = TRUE))

## longer version with no x-ticks

## Not run: 
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"))
## End(Not run)

## Not run: 
## End(Not run)

[Package lattice version 0.15-4 Index]