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.
xyplot(x, data, ...)
dotplot(x, data, ...)
barchart(x, data, ...)
stripplot(x, data, ...)
bwplot(x, data, ...)
"xyplot"(x, data, 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, xlab, xlim, ylab, ylim, drop.unused.levels = lattice.getOption("drop.unused.levels"), ..., lattice.options = NULL, default.scales, default.prepanel = lattice.getOption("prepanel.default.xyplot"), subscripts = !is.null(groups), subset = TRUE)
"dotplot"(x, data, panel = lattice.getOption("panel.dotplot"), default.prepanel = lattice.getOption("prepanel.default.dotplot"), ...)
"barchart"(x, data, panel = lattice.getOption("panel.barchart"), default.prepanel = lattice.getOption("prepanel.default.barchart"), box.ratio = 2, ...)
"stripplot"(x, data, panel = lattice.getOption("panel.stripplot"), default.prepanel = lattice.getOption("prepanel.default.stripplot"), ...)
"bwplot"(x, data, 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, xlab, xlim, ylab, ylim, box.ratio = 1, horizontal = NULL, drop.unused.levels = lattice.getOption("drop.unused.levels"), ..., lattice.options = NULL, default.scales, default.prepanel = lattice.getOption("prepanel.default.bwplot"), subscripts = !is.null(groups), subset = TRUE)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.
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.
TRUE
whenever sensible.
x for
details). Defaults to FALSE, except when groups is
explicitly specified or grouping does not make sense for the default
panel function.
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.
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.
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.
"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.
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.
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.
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.
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).
"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.
"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.
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 :
Note that much of the function of scales is accomplished by
pscales in splom.
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.
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.
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.
xlim, applied to the y-axis. 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.
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.
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.
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.
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:
"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.
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).
Lattice for an overview of the package, as well as
barchart.table,
print.trellis,
shingle,
banking,
reshape,
panel.xyplot,
panel.bwplot,
panel.barchart,
panel.dotplot,
panel.stripplot,
panel.superpose,
panel.loess,
panel.average,
strip.default,
simpleKey
trellis.par.set
require(stats)
## Tonga Trench Earthquakes
Depth <- equal.count(quakes$depth, number=8, overlap=.1)
xyplot(lat ~ long | Depth, data = quakes)
update(trellis.last.object(),
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, 1993) obtained
## from http://cm.bell-labs.com/cm/ms/departments/sia/wsc/
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")
## Extended formula interface
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, labels = groups[subscripts], cex=1,
fontfamily = "HersheySans")
})
## Stacked bar chart
barchart(yield ~ variety | site, data = barley,
groups = year, layout = c(1,6), stack = TRUE,
auto.key = list(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)
## Grouped dot plot showing anomaly at Morris
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.data = 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)
Run the code above in your browser using DataLab