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.
- Keywords
- hplot
Usage
xyplot(x, data, …)
dotplot(x, data, …)
barchart(x, data, …)
stripplot(x, data, …)
bwplot(x, data, …)# S3 method for 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,
default.prepanel = lattice.getOption("prepanel.default.xyplot"),
subscripts = !is.null(groups),
subset = TRUE)
# S3 method for formula
dotplot(x,
data,
panel = lattice.getOption("panel.dotplot"),
default.prepanel = lattice.getOption("prepanel.default.dotplot"),
…)
# S3 method for formula
barchart(x,
data,
panel = lattice.getOption("panel.barchart"),
default.prepanel = lattice.getOption("prepanel.default.barchart"),
box.ratio = 2,
…)
# S3 method for formula
stripplot(x,
data,
panel = lattice.getOption("panel.stripplot"),
default.prepanel = lattice.getOption("prepanel.default.stripplot"),
…)
# S3 method for 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,
default.prepanel = lattice.getOption("prepanel.default.bwplot"),
subscripts = !is.null(groups),
subset = TRUE)
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 ofy
(on the y-axis) versusx
(on the x-axis) should be produced conditional on the variablesg1, g2, …
. Herex
andy
are the primary variables, andg1, g2, …
are the conditioning variables. The conditioning variables may be omitted to give a formula of the formy ~ 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 thedata
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 tonames(x)
ifx
is named, and a factor with a single level otherwise.Cases where
x
is not a formula is handled by appropriate methods. Thenumeric
methods are equivalent to a call with no left hand side and no conditioning variables in the formula. Forbarchart
anddotplot
, non-trivial methods exist for tables and arrays, documented atbarchart.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 ofshingle
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 theshingle
function; however, usingequal.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 RHSx
) 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 bothy1 ~ x | a * b
andy2 ~ x | a * b
, but with they1 ~ x
andy2 ~ x
superposed in each panel. The two groups will be distinguished by different graphical parameters. This is essentially what thegroups
argument (see below) would produce, ify1
andy2
were concatenated to produce a longer vector, with thegroups
argument being an indicator of which rows come from which variable. In fact, this is exactly what is done internally using thereshape
function. This feature cannot be used in conjunction with thegroups
argument.To interpret
y1 + y2
as a sum, one can either setallow.multiple=FALSE
or useI(y1+y2)
.A variation on this feature is when the
outer
argument is set toTRUE
. 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
andy
variables should both be numeric inxyplot
, 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 ofx
andy
should be numeric, and the other a factor or shingle. Which of these will happen is determined by thehorizontal
argument --- ifhorizontal=TRUE
, theny
will be coerced to be a factor or shingle, otherwisex
. The default value ofhorizontal
isFALSE
ifx
is a factor or shingle,TRUE
otherwise. (The functionality provided byhorizontal=FALSE
is not S-compatible.)Note that the
x
argument used to be calledformula
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 validenvir
argument ineval
, e.g., a list or an environment) containing values for any variables in the formula, as well asgroups
andsubset
if applicable. If not found indata
, or ifdata
is unspecified, the variables are looked for in the environment of the formula. For other methods (wherex
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 toFALSE
, except whengroups
is explicitly specified or grouping does not make sense for the default panel function.- box.ratio
Applicable to
barchart
andbwplot
. Specifies the ratio of the width of the rectangles to the inter-rectangle space. See also thebox.width
argument in the respective default panel functions.- horizontal
Logical flag applicable to
bwplot
,dotplot
,barchart
, andstripplot
. Determines which ofx
andy
is to be a factor or shingle (y
if TRUE,x
otherwise). Defaults toFALSE
ifx
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 beabbreviate = TRUE
, in which case long labels which would usually overlap will be abbreviated.scales
could also contain aminlength
argument in this case, which would be passed to theabbreviate
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
andy
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 thepanel
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
andy
, 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 asxyplot
) 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
andy
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 byllines
(or equivalently,panel.lines
). Note that traditional graphics functions likelines
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 notNULL
. In that case, the panel function should also accept arguments namedgroups
andsubscripts
(see below for details). A useful panel function predefined for use in such cases ispanel.superpose
, which can be combined with differentpanel.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 thegroups
argument, including the default ones forxyplot
,barchart
,dotplot
, andstripplot
.Even when
groups
is not present, the panel function can havesubscripts
as a formal argument. In either case, thesubscripts
argument passed to the panel function are the indices of thex
andy
data for that panel in the originaldata
, BEFORE taking into account the effect of thesubset
argument. Note thatgroups
remains unaffected by any subsetting operations, sogroups[subscripts]
gives the values ofgroups
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., whenallow.multiple
is in effect). A comprehensive description would be too complicated (details can be found in the source code of the functionlatticeParseFormula
), 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 ofsubset
, in which casesubscripts
may have no relationship with corresponding rows in the original data frame.One can also use functions called
panel.number
andpacket.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 usingtrellis.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 (usingperm.cond
andindex.cond
respectively), in which casepacket.number
gives the index corresponding to the ‘natural’ ordering of that combination of levels of the conditioning variables.panel.xyplot
has an argument calledtype
which is worth mentioning here because it is quite frequently used (and as mentioned above, can be passed toxyplot
directly). In the event that agroups
variable is used,panel.xyplot
callspanel.superpose
, arguments of which can also be passed directly toxyplot
. Panel functions forbwplot
and friends should have an argument calledhorizontal
to account for the cases whenx
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 (seebanking
); 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 componentsdx
anddy
, 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, ifgroups
is specified, thengroups
along withsubscripts
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
andsimpleKey
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 toauto.key=list()
, in which casesimpleKey
is called with a set of default arguments (which may depend on the relevant high-level function). Most valid components to thekey
argument can be specified in this manner, assimpleKey
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. Ifauto.key=TRUE
, a suitable legend will be drawn if agroups
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 forkey
).More precisely, if
auto.key
is notFALSE
,groups
is non-null, and there is nokey
orlegend
argument specified in the call, a key is created withsimpleKey
withlevels(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). Ifauto.key
is provided as a list and includes atext
component, then that is used instead as the text labels in the key, and the key is drawn even ifgroups
is not specified.Note that
simpleKey
uses the default settings (seetrellis.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. Thepar.settings
argument, possibly in conjunction withsimpleTheme
, may be useful to temporarily modify the default settings for this purpose.One disadvantage to using
key
(or evensimpleKey
) 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, withauto.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 namedxlim
,ylim
,dx
, anddy
(and less frequently,xat
andyat
). 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
andylim
components are similar to the high levelxlim
andylim
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 thexlim
andylim
arguments are not explicitly specified (possibly as components inscales
) 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 therelation
component ofscales
is"same"
, and on a per-panel basis otherwise.The
dx
anddy
components are used for banking computations in caseaspect
is specified as"xy"
. See documentation ofbanking
for details.If
xlim
orylim
is a character vector (which is appropriate when the corresponding variable is a factor), this implicitly indicates that the scale should include the firstn
integers, wheren
is the length ofxlim
orylim
, as the case may be. The elements of the character vector are used as the default labels for thesen
integers. Thus, to make this information consistent between panels, thexlim
orylim
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
oryat
may be returned by theprepanel
function, which should be a subset of1:n
, indicating which of then
values (levels) are actually represented in the panel. This is useful when calculating the limits withrelation="free"
orrelation="sliced"
inscales
.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 thexlim
andylim
components.- strip
A logical flag or function. If
FALSE
, strips are not drawn. Otherwise, strips are drawn using thestrip
function, which defaults tostrip.default
. See documentation ofstrip.default
to see the arguments that are available to the strip function. This description also applies to thestrip.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 forx
in the formula defining the plot. Can be specified asNULL
to omit the label altogether. Finer control is possible, as described in the entry formain
, with the modification that if thelabel
component is omitted from the list, it is replaced by the defaultxlab
.- ylab
Character or expression (or
"grob"
) giving label for the y-axis. Generally defaults to the expression fory
in the formula defining the plot. Finer control is possible, see entries formain
andxlab
.- 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 calledx
andy
of the same form (described below). Components ofx
andy
affect the respective axes only, while those inscales
affect both. When parameters are specified in both lists, the values inx
ory
are used. Note that certain high-level functions have defaults that are specific to a particular axis (e.g.,bwplot
hasalternating=FALSE
for the categorical axis only); these can only be overridden by an entry in the corresponding component ofscales
.As a special exception,
scales
(or itsx
andy
components) can also be a character string, in which case it is interpreted as therelation
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"
. Forrelation="same"
, the same limits, usually large enough to encompass all the data, are used for all the panels. Forrelation="free"
, limits for each panel is determined by just the points in that panel. Behavior forrelation="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 byxlim
,ylim
orscales$limits
(except whenrelation="sliced"
, in which case explicitly specified limits are ignored with a warning). Whenrelation
is"free"
,xlim
orylim
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 numbers0: do not draw tick labels
1: bottom/left
2: top/right
3: both.
alternating
applies only whenrelation="same"
. The default isTRUE
, or equivalently,c(1, 2)
limits
Same as
xlim
andylim
.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 likeat
.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.minlength
Argument passed to
abbreviate
ifabbreviate=TRUE
.log
Controls whether the corresponding variable (
x
ory
) will be log transformed before being passed to the panel function. Defaults toFALSE
, 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 toy ~ 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
isFALSE
, the choice made is similar to how log scales are annotated in traditional graphics. IfTRUE
, tick mark locations are chosen as ‘pretty’ equispaced values in the transformed scale, and labeled in the form"base^loc"
, wherebase
is the base of the logarithm transformation, andloc
are the locations in the transformed scale.See also
xscale.components.logpower
in the latticeExtra package.format
The
format
to use for POSIXct variables. Seestrptime
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 bypscales
insplom
.- subscripts
A logical flag specifying whether or not a vector named
subscripts
should be passed to the panel function. Defaults toFALSE
, unlessgroups
is specified, or if the panel function accepts an argument namedsubscripts
. 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., usingpanel.identify
.- subset
An expression that evaluates to a logical or integer indexing vector. Like
groups
, it is evaluated indata
. Only the resulting rows ofdata
are used for the plot. Ifsubscripts
isTRUE
, the subscripts provided to the panel function will be indices referring to the rows ofdata
prior to the subsetting. Whether levels of factors in the data frame that are unused after the subsetting will be dropped depends on thedrop.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 positions1: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 whenscales$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 componentscond
anddata
, both logical, indicating desired behavior for conditioning variables and primary variables respectively. The default is given bylattice.getOption("drop.unused.levels")
, which is initially set toTRUE
for both components. Note that this argument does not control dropping of levels of thegroups
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 oflattice.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 thepar.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 forbwplot
ispanel.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); ifTRUE
, left to right, top to bottom (as in a table).between
:A list with components
x
andy
(both usually 0 by default), numeric vectors specifying the space between the panels (units are character heights).x
andy
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 differentbetween
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. Theauto.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 bykey
, use thelegend
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 ofspace
, which can be one of"top"
,"bottom"
,"left"
and"right"
. Alternatively, the key can be positioned inside the plot region by specifying componentsx
,y
andcorner
.x
andy
determine the location of the corner of the key given bycorner
, which is usually one ofc(0,0)
,c(1,0)
,c(1,1)
andc(0,1)
, which denote the corners of the unit square. Fractional values are also allowed, in which casex
andy
determine the position of an arbitrary point inside (or outside for values outside the unit interval) the key.x
andy
should be numbers between 0 and 1, giving coordinates with respect to the “display area”. Depending on the value of the"legend.bbox"
option (seelattice.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. Thekey
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 forrep
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
anddensity
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
. IfTRUE
, all components are reversed after being replicated (the details of which may depend on the value ofrep
). This is useful in certain situations, e.g., with a groupedbarchart
withstack = 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 unlessreverse.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 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 specifyingrep=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
isTRUE
, and no border is drawn if it isFALSE
(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"
inlines
.
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 thespace
component ofkey
. Ifkey
(orcolorkey
forlevelplot
andwireframe
) is specified, theirspace
component must not conflict with the name of any component oflegend
.Each component of
legend
must have a component calledfun
. 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 calledargs
. For components named"inside"
, there can be additional components calledx
,y
andcorner
, which work in the same way as forkey
.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
andylab
, 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 asxlab
,ylab
andsub
) 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 inplotmath
. The label can be a vector, in which case the components will be spaced out horizontally (or vertically forylab
). 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 thelabel
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
andylab
usually have defaults, butmain
andsub
do not). Further named arguments are passed on totextGrob
; this can include arguments controlling positioning likejust
androt
as well as graphical parameters such ascol
andfont
(seegpar
for a full list).main
,sub
,xlab
,ylab
,xlab.top
, andylab.right
can also be arbitrary"grob"
s (grid graphical objects).sub
:Character string or expression (or a list or
"grob"
) for a subtitle to be placed at the bottom of each page. See entry formain
for finer control options.par.strip.text
:A list of parameters to control the appearance of strip text. Notable components are
col
,cex
,font
, andlines
. 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 specifyingabbreviate = TRUE
, in which case the componentsminlength
anddot
(passed along to theabbreviate
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 isc(0,n)
, wheren
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 (viapar("din")
). IfNA
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 areTRUE
, 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 forstrip
for detailed usage.xlab.default
,ylab.default
:Fallback default for
xlab
andylab
when they are not specified. IfNULL
, 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
, wheren
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 ann
-dimensional array, then during printing, its dimensions are permuted usingperm.cond
as theperm
argument does inaperm
.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. Ifindex.cond
is a list, it has to be as long as the number of conditioning variables, and thei
-th component has to be a valid indexing vector forlevels(g_i)
, whereg_i
is thei
-th conditioning variable in the plot (note that these levels may not contain all levels of the original variable, depending on the effects of thesubset
anddrop.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 toTRUE
.Note that the components of
index.cond
are interpreted in the order of the conditioning variables in the original call, and is not affected byperm.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
andindex.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 theupdate.trellis
method, both can be set toNULL
, 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 thelattice.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 theplot
orprint
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.
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.average
,
strip.default
,
simpleKey
trellis.par.set
Examples
# 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, 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"))
# }
# NOT RUN {
# }