B_01_xyplot {lattice} | R Documentation |
Common Bivariate Trellis Plots
Description
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.
Usage
xyplot(x, data, ...)
dotplot(x, data, ...)
barchart(x, data, ...)
stripplot(x, data, ...)
bwplot(x, data, ...)
## S3 method for class 'formula':
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,
subscripts = !is.null(groups),
subset = TRUE)
## S3 method for class 'formula':
dotplot(x,
data,
panel = lattice.getOption("panel.dotplot"),
...)
## S3 method for class 'formula':
barchart(x,
data,
panel = lattice.getOption("panel.barchart"),
box.ratio = 2,
...)
## S3 method for class 'formula':
stripplot(x,
data,
panel = lattice.getOption("panel.stripplot"),
...)
## S3 method for class 'formula':
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,
subscripts = !is.null(groups),
subset = TRUE)
Arguments
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.
|
The following arguments are common to all the functions documented
here, as well as most other high level Trellis functions. These are
not documented elsewhere, except to override the usage given here.
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.
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 has practically 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 |
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, 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.
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 |
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 :
relation -
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.
tick.number -
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 ).
draw -
logical, defaults to
TRUE , whether to draw the axis at
all.
alternating -
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)
limits -
same as xlim and ylim.
at - 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 -
Labels (strings or expressions) to go along with
at . Can
be a list like at as well.
cex -
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.
tck -
numeric to control length of tick marks. Can be a vector of
length 2, to control left/bottom and right/top separately.
col -
color of ticks and labels.
rot -
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.
abbreviate -
logical, whether to abbreviate the labels using
abbreviate . Can be useful for long labels (e.g., in
factors), especially on the x-axis.
minlength -
argument passed to
abbreviate if abbreviate=TRUE .
log -
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 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) .
format -
the
format to use for POSIXct variables. See
strptime for description of valid values.
axs -
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:
as.table :- 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.
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 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 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
lattice.getOption("legend.bbox") , 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 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
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.
Other possible components of key are:
reverse.rows -
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.
between -
numeric vector giving the amount of space (character widths)
surrounding each column (split equally on both sides)
title -
string or expression giving a title for the key
rep -
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.title -
cex for the title
lines.title -
how many lines the title should occupy (in multiples of
itself). Defaults to 2.
padding.text -
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 -
background color, defaults to default background
alpha.background -
An alpha transparency value between 0 and 1
border -
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)
transparent=FALSE -
logical, whether key area should have a transparent background
columns -
the number of columns column-blocks the key is to be divided
into, which are drawn side by side.
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 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 .
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.
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).
main , xlab , ylab and sub can also be
an arbitrary "grob" (grid graphical object).
sub :-
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 :- 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.
layout :-
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.
If NA is specified for the number of rows or columns (not
both), that dimension will be filled out according to the number
of panels.
skip :-
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 :-
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.
axis :- function that draws axis annotation. See
documentation for
axis.default , the default value
of this argument, to learn more.
perm.cond :-
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 .
index.cond :-
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
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 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.
par.settings :-
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.
plot.args :-
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.
|
Details
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 right 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).
Value
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.
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.
Author(s)
Deepayan Sarkar Deepayan.Sarkar@R-project.org
References
Sarkar, Deepayan (2008) "Lattice: Multivariate Data Visualization with
R", Springer. http://lmdvr.r-forge.r-project.org/
See Also
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.linejoin
,
strip.default
,
simpleKey
trellis.par.set
Examples
## Not run:
## wait for user input before each new page (like 'par(ask = TRUE)')
old.prompt <- grid::grid.prompt(TRUE)
## End(Not run)
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)
## (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, labels = 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.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)
## Not run:
grid::grid.prompt(old.prompt)
## End(Not run)
[Package
lattice version 0.18-5
Index]