B_00_xyplot

Common Bivariate Trellis Plots

This help page documents several commonly used high-level Lattice
functions. xyplot produces bivariate scatterplots or
time-series plots, bwplot produces box-and-whisker plots,
dotplot produces Cleveland dot plots, barchart produces
bar plots, and stripplot produces one-dimensional scatterplots.
All these functions, along with other high-level Lattice functions,
respond to a common set of arguments that control conditioning,
layout, aspect ratio, legends, axis annotation, and many other details
in a consistent manner. These arguments are described extensively in
this help page, and should be used as the reference for other
high-level functions as well.

For control and customization of the actual display in each panel, the
help page of the respective default panel function will often be more
informative. In particular, these help pages describe many arguments
commonly used when calling the corresponding high-level function but
are specific to them.

Arguments

x

All high-level function in lattice are generic. x is
the object on which method dispatch is carried out.

For the "formula" methods, x must be a formula
describing the primary variables (used for the per-panel display)
and the optional conditioning variables (which define the subsets
plotted in different panels) to be used in the plot. Conditioning
is described in the “Details” section below.

For the functions documented here, the formula is generally of the
form y ~ x | g1 * g2 * … (or equivalently, 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, …. Here x and y are
the primary variables, and g1, g2, … are the conditioning
variables. The conditioning variables may be omitted to give a
formula of the form y ~ x, in which case the plot will
consist of a single panel with the full dataset. The formula can
also involve expressions, e.g., sqrt(), log(), etc.
See the data argument below for rules regarding evaluation of
the terms in the formula.

With the exception of xyplot, the functions documented here
may also be supplied a formula of the form ~ x | g1 * g2 *
…. In that case, y defaults to names(x) if
x is named, and a factor with a single level otherwise.

Cases where x is not a formula is handled by appropriate
methods. The numeric methods are 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 at barchart.table.

The conditioning variables g1, g2, … must be either
factors or shingles. Shingles provide a way of using numeric
variables for conditioning; see the help page of
shingle for details. Like factors, they have a
"levels" attribute, which is used in producing the
conditional plots. If necessary, numeric conditioning variables are
converted to shingles using the shingle function; however,
using equal.count may be more appropriate in many
cases. Character variables are coerced to factors.

Extended formula interface: As a useful extension of the
interface described above, the primary variable terms (both the LHS
y and RHS x) may consist of multiple terms separated
by 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. The two
groups will be distinguished by different graphical parameters.
This is essentially what the groups argument (see below)
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. 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).

Primary variables: 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 the x 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 instead be the first (unnamed) argument.

data

For the formula methods, a data frame (or more precisely,
anything that is a valid envir argument in
eval, e.g., a list or an environment) containing values
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
if it is explicitly specified.

allow.multiple

Logical flag specifying whether the extended formula interface
described above should be in effect. Defaults to TRUE
whenever sensible.

outer

Logical flag controlling what happens with formulas using the
extended interface described above (see the entry for x for
details). Defaults to FALSE, except when groups is
explicitly specified or grouping does not make sense for the default
panel function.

box.ratio

Applicable to barchart and bwplot. Specifies the
ratio of the width of the rectangles to the inter-rectangle space.
See also the box.width argument in the respective default
panel functions.

horizontal

Logical flag 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 expected to use it as appropriate.

A potentially useful component of scales in this case may 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. The argument may be a function object or a character
string giving the name of a predefined function. Each high-level
function has its own default panel function, named as
“panel.” followed by the name of the corresponding
high-level function (e.g., panel.xyplot,
panel.barchart, etc).

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 is useful to know in
this context that all arguments passed to a high-level Lattice
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, as 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 traditional graphics
functions useful for this purpose. For example, lines can be
replaced by llines (or equivalently, panel.lines).
Note that traditional 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
to determine 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
xyplot, 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.

This interpretation of subscripts does not hold when the
extended formula interface is in use (i.e., when
allow.multiple is in effect). A comprehensive description
would be too complicated (details can be found in the source code of
the function latticeParseFormula), but in short, the extended
interface works by creating an artificial grouping variable that is
longer than the original data frame, and consequently,
subscripts needs to refer to rows beyond those in the
original data. To further complicate matters, the artificial
grouping variable is created after any effect of subset, in
which case subscripts may have no relationship with
corresponding rows in the original data frame.

One can also use functions called panel.number and
packet.number, representing panel order and packet
order respectively, inside the panel function (as well as the strip
function or while interacting with a lattice display using
trellis.focus etc). Both provide a simple integer
index indicating which panel is currently being drawn, but differ in
how the count is calculated. The panel number is a simple
incremental counter that starts with 1 and is incremented each time
a panel is drawn. The 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). In the
event that a groups variable is used,
panel.xyplot calls panel.superpose,
arguments of which can also be passed directly to xyplot.
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

This argument controls the physical aspect ratio of the panels,
which is usually the same for all the panels. It can be specified as
a ratio (vertical size/horizontal size) or as a character string.
In the latter case, legitimate values are "fill" (the
default) which tries to make the panels as big as possible to fill
the available space; "xy", which computes the aspect ratio
based on the 45 degree banking rule (see banking); 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. Not
all default prepanel functions produce sensible banking
calculations.

groups

A variable or expression to be evaluated in 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. For high
level functions where grouping is appropriate, the default panel
functions can handle grouping.

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, or a list containing components to be used as arguments
to simpleKey. auto.key=TRUE is equivalent to
auto.key=list(), in which case simpleKey is
called with a set of default arguments (which may depend on the
relevant high-level function). Most valid components to the
key argument can be specified in this manner, as
simpleKey will simply add unrecognized arguments to
the list it produces.

auto.key is typically used to automatically produce a
suitable legend in conjunction with a grouping variable. If
auto.key=TRUE, a suitable legend will be drawn if a
groups argument is also provided, and not otherwise. In list
form, auto.key will modify the default legend thus produced.
For example, auto.key=list(columns = 2) will create a legend
split into two columns (columns is documented in the entry
for key).

More precisely, 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
(text) 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). If auto.key is provided as
a list and includes a text component, then that is used
instead as the text labels in the key, and the key is drawn even if
groups is not specified.

Note that simpleKey uses the default settings (see
trellis.par.get) to determine the graphical parameters
in the key, so the resulting legend will be meaningful only if the
same settings are used in the plot as well. The par.settings
argument, possibly in conjunction with simpleTheme,
may be useful to temporarily modify the default settings for this
purpose.

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-plot-ted with different settings, the original parameter
settings will be used for the key even though the new settings are
used for the actual display. However, with auto.key, the key
is actually created at plotting time, so the settings will match.

prepanel

A 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 return value of a
user-supplied prepanel function need not contain all these
components; in case some are missing, they are replaced by the
component-wise defaults.

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, or a
character vector representing levels of a factor). If the
xlim and ylim arguments are not explicitly specified
(possibly as components in scales) in the high-level call,
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 per-panel basis otherwise.

The dx and dy components are used for banking
computations in case aspect is specified as "xy". See
documentation of banking for details.

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 else is appropriate, values of NA
should be returned for the xlim and ylim components.

strip

A 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 (useful for wide short
panels, e.g., in time-series plots).

xlab

Character or expression (or a "grob") giving label(s) for the
x-axis. Generally defaults to the expression for x in the
formula defining the plot. Can be specified as NULL to omit
the label altogether. Finer control is possible, as described in
the entry for main, with the modification that if the
label component is omitted from the list, it is replaced by
the default xlab.

ylab

Character or expression (or "grob") giving label for the
y-axis. Generally defaults to the expression for y in the
formula defining the plot. Finer control is possible, see entries
for main and xlab.

scales

Generally a 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 categorical axis only); these can
only be overridden by an entry in the corresponding component of
scales.

As a special exception, scales (or its x and y
components) can also be a character string, in which case it is
interpreted as the relation component.

The possible components are :

relation

A 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 (except when relation="sliced", in
which case explicitly specified limits are ignored with a
warning). When relation is "free", xlim or
ylim can be a list, in which case it is treated as if its
components were the limit values obtained from the prepanel
calculations for each panel (after being replicated if
necessary).

tick.number

An integer, giving the suggested number of intervals between
ticks. This is ignored for a factor, shingle, or character
vector, for in these cases there is no natural rule for leaving
out some of the labels. But see xlim.

draw

A logical flag, defaulting to TRUE, that determines
whether to draw the axis (i.e., tick marks and labels) at all.

alternating

Usually a logical flag specifying whether axis labels should
alternate from one side of the group of panels to the other.
For finer control, alternating can also 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)

limits

Same as xlim and ylim.

at

The 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

Vector of labels (characters or expressions) to go along with
at. Can also be a list like at.

cex

A numeric multiplier to control character sizes for axis labels.
Can be a vector of length 2, to control left/bottom and
right/top labels separately.

font, fontface, fontfamily

Specifies the font to be used for axis labels.

lineheight

Specifies the line height parameter (height of line as a
multiple of the size of text); relevant for multi-line labels.
(This is currently ignored for cloud.)

tck

Usually a numeric scalar controlling the length of tick marks.
Can also be a vector of length 2, to control the length of
left/bottom and right/top tick marks separately.

col

Color of tick marks and labels.

rot

Angle (in degrees) by which the axis labels are to be rotated.
Can be a vector of length 2, to control left/bottom and
right/top axes separately.

abbreviate

A logical flag, indicating whether to abbreviate the labels
using the abbreviate function. Can be useful for
long labels (e.g., in factors), especially on the x-axis.

Controls whether the corresponding variable (x or
y) will be log transformed before being passed to the
panel function. Defaults to FALSE, in which case the
data are not transformed. Other possible values are any number
that works as a base for taking logarithm, TRUE (which is
equivalent to 10), and "e" (for the natural logarithm).
As a side effect, the corresponding axis is labeled differently.
Note that this is in reality a transformation of the data, not
the axes. Other than the axis labeling, using this feature is
no different than transforming the data in the formula; e.g.,
scales=list(x = list(log = 2)) is equivalent to y ~
log2(x).

See entry for equispaced.log below for details on how to
control axis labeling.

equispaced.log

A logical flag indicating whether tick mark locations should be
equispaced when ‘log scales’ are in use. Defaults to
TRUE.

Tick marks are always labeled in the original (untransformed)
scale, but this makes the choice of tick mark locations
nontrivial. If equispaced.log is FALSE, the
choice made is similar to how log scales are annotated in
traditional graphics. If TRUE, tick mark locations are
chosen as ‘pretty’ equispaced values in the transformed
scale, and labeled in the form "base^loc", where
base is the base of the logarithm transformation, and
loc are the locations in the transformed scale.

See also xscale.components.logpower in the
latticeExtra package.

format

The format to use for POSIXct variables. See
strptime for description of valid values.

axs

A character string, "r" (default) 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

A logical flag 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. This argument
is useful if one wants the subscripts to be passed on even if these
conditions do not hold; a typical example is when one wishes to
augment a Lattice plot after it has been drawn, e.g., using
panel.identify.

subset

An expression that evaluates to a logical or integer indexing
vector. Like groups, it is evaluated in data. Only
the resulting rows of data are used for the plot. If
subscripts is TRUE, the subscripts provided to the
panel function will be indices referring to the rows of data
prior to the subsetting. 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 (or a DateTime object) of length 2 giving
left and right limits 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", 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

A logical flag indicating whether the unused levels of factors will
be dropped, usually relevant when 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 primary 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

A list giving the default values of scales for a particular
high-level function. This is rarely of interest to the end-user,
but may be helpful when defining other functions that act as a
wrapper to one of the high-level Lattice functions.

default.prepanel

A function or character string giving the name of a function that
serves as the (component-wise) fallback prepanel function when the
prepanel argument is not specified, or does not return all
necessary components. The main purpose of this argument is to
enable the defaults to be overridden through the use of
lattice.options.

lattice.options

A list that could be supplied to lattice.options.
These options are applied temporarily for the duration of the call,
after which the settings revert back to what they were before. The
options are 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 instead passed on to other
functions. Such arguments can be broadly categorized into two types:
those that affect all high-level Lattice functions in a similar
manner, and those that are meant for the specific panel function
being used.

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:

as.table:

A logical flag that controls the order in which panels should be
displayed: 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 (as in a table).

between:

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.

key:

A list that defines a legend to be drawn on the plot. This list
is used as an argument to the draw.key function,
which produces a "grob" (grid object) eventually plotted
by the print method for "trellis" objects. The structure
of the legend is constrained in the ways described below.

Although such a list can be and often is created explicitly, it
is also possible to generate such a list using the
simpleKey function; the latter is more convenient
but less flexible. The auto.key argument can be even
more convenient for the most common situation where legends are
used, namely, in conjunction with 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 is usually
one of c(0,0), c(1,0), c(1,1) and
c(0,1), which denote the corners of the unit square.
Fractional values are also allowed, in which case x and
y determine the position of an arbitrary point inside (or
outside for values outside the unit interval) the key.

x and y should be numbers between 0 and 1, giving
coordinates with respect to the “display area”.
Depending on the value of the "legend.bbox" option (see
lattice.getOption), this can be either the full
figure region ("full"), or just the region that bounds
the panels and strips ("panel").

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 must have a character or expression
vector as its first component, to be used as labels. 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 (text, lines, points)

col="black" (text, rectangles, lines, points)

alpha=1 (text, rectangles, lines, points)

fill="transparent" (lines, points)

lty=1 (lines)

lwd=1 (lines, points)

font=1 (text, points)

fontface (text, points)

fontfamily (text, points)

pch=8 (lines, points)

adj=0 (text)

type="l" (lines)

size=5 (rectangles, lines)

height=1 (rectangles)

lineheight=1 (text)

angle=0 (rectangles, but ignored)

density=-1 (rectangles, but ignored)

In addition, the component border can be included inside
the "rect" component to control the border color of the
rectangles; when specified at the top level, border
controls the border of the entire key (see below).

angle and density are 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. height gives
heights of rectangles as a fraction of the default.

Other possible components of key are:

reverse.rows

Logical flag, 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 = TRUE 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 reverse.rows = TRUE. Note that in
this case, unless all columns have the same number or rows,
they will no longer be aligned.

Logical flag, defaults to TRUE. By default, it is
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.title

Zoom factor for the title.

lines.title

The amount of vertical space to be occupied by the title in
lines (in multiples of itself). Defaults to 2.

padding.text

The amount of space (padding) to 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

Background color for the legend. Defaults to the global
background color.

alpha.background

An alpha transparency value between 0 and 1 for the
background.

border

Either a color for the border, or a logical flag. In the
latter case, the border color is black if border is
TRUE, and no border is drawn if it is FALSE
(the default).

transparent=FALSE

Logical flag, whether legend should have a transparent
background.

just

A character or numeric vector of length one or two giving
horizontal and vertical justification for the placement of
the legend. See grid.layout
for more precise details.

columns

The number of column-blocks (drawn side by side) the legend
is to be divided into.

between.columns

Space between column blocks, in addition to between.

divide

Number of point symbols to divide each line when type is
"b" or "o" in lines.

legend:

The legend argument can be useful if one wants to place more
than one key. It also allows the use of 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 for key.

page:

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.

xlab.top, ylab.right:

Labels for the x-axis on top, and y-axis on the right. Similar
to xlab and ylab, but less commonly used.

main:

Typically a character string or expression describing the main
title to be placed on top of each page. Defaults to
NULL.

main (as well as xlab, ylab and sub)
is usually a character string or an expression that gets used as
the label, but can also be a list that controls further details.
Expressions are treated as specification of LaTeX-like markup as
described in plotmath. The label can be a vector,
in which case the components will be spaced out horizontally (or
vertically for ylab). This feature can be used to
provide column or row labels rather than a single axis label.

When main (etc.) is a list, the actual label should be
specified as the label component (which may be unnamed if
it is the first component). The label can be missing, in which
case the default will be used (xlab and ylab
usually have defaults, but main and sub do not).
Further named arguments are passed on to
textGrob; this can include
arguments controlling positioning like just and
rot as well as graphical parameters such as col
and font (see gpar for a full
list).

Character string or expression (or a list or "grob") for
a subtitle to be placed at the bottom of each page. See entry
for main for finer control options.

par.strip.text:

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

Additionally, the lineheight component can control the
space between multiple lines. 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.

layout:

In general, a conditioning plot in Lattice consists of several
panels arranged in a rectangular array, possibly spanning
multiple pages. layout determines this arrangement.

layout is a numeric vector of length 2 or 3 giving the
number of columns, rows, and pages (optional) in a multipanel
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")). If NA
is specified for the number of rows or columns (but not both),
that dimension will be filled out according to the number of
panels.

The number of pages is by default set to as many as is required
to plot all the panels, and so rarely needs to be specified.
However, in certain situations the default calculation may be
incorrect, and in that case the number of pages needs to be
specified explicitly.

skip:

A 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 may be useful
for arranging plots in an informative manner.

strip.left:

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. See the entry for strip
for detailed usage.

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

axis:

Function responsible for drawing axis annotation. See
documentation for axis.default, the default value
of this argument, to learn more.

perm.cond:

An integer 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 does in aperm.

index.cond:

Whereas 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
levels(g_i), where g_i is the i-th
conditioning variable in the plot (note that these levels may
not contain all levels of the original variable, depending on
the effects of the subset and drop.unused.levels
arguments). In particular, this indexing may repeat 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 interpreted 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.) If there is only one 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.trellis method, both can be set to
NULL, which reverts these back to their defaults.

par.settings:

A list that could be supplied to trellis.par.set.
When the resulting object is plotted, these options are applied
temporarily for the duration of the plotting, after which the
settings revert back to what they were before. This enables the
user to attach some display settings to the trellis object
itself rather than change the settings globally. See also the
lattice.options argument described above for a similar
treatment of non-graphical options.

plot.args:

A list containing 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.

Details

The high-level functions documented here, as well as other high-level
Lattice functions, are generic, with the formula method usually
doing the most substantial work. The structure of the plot that is
produced is mostly controlled by the formula (implicitly in the case
of the non-formula methods). For each unique combination of the
levels of the conditioning variables g1, g2, …, a separate
“packet” is produced, consisting of the points (x,y) for
the subset of the data defined by that combination. The display can
be thought of as a three-dimensional array of panels, consisting of one
two-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 packet.
Each packet usually corresponds to one panel, but this is not strictly
necessary (see the entry for index.cond above).

The coordinate system used by lattice by default is like a
graph, with the origin at the bottom left, with axes increasing to the
right and top. 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. It is possible to set a
global preference for the 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)). 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, followed by
g2, and so on. 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).

Value

The high-level functions documented here, as well as other high-level
Lattice functions, return an object of class "trellis". The
update method can be used to
subsequently update components of the object, and the
print method (usually called by
default) will plot it on an appropriate plotting device.

Note

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.