EVOLUTION-MANAGER

Edit File: xyplot.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: Common Bivariate Trellis Plots</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<link rel="stylesheet" type="text/css" href="R.css" />
</head><body>

<table width="100%" summary="page for B_00_xyplot {lattice}"><tr><td>B_00_xyplot {lattice}</td><td style="text-align: right;">R Documentation</td></tr></table>

<h2>Common Bivariate Trellis Plots</h2>

<h3>Description</h3>

This help page documents several commonly used high-level Lattice
functions. <code>xyplot</code> produces bivariate scatterplots or
time-series plots, <code>bwplot</code> produces box-and-whisker plots,
<code>dotplot</code> produces Cleveland dot plots, <code>barchart</code> produces
bar plots, and <code>stripplot</code> 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.

<h3>Usage</h3>

<pre>
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,
       default.prepanel = lattice.getOption("prepanel.default.xyplot"),
       subscripts = !is.null(groups),
       subset = TRUE)

## S3 method for class 'formula'
dotplot(x,
        data,
        panel = lattice.getOption("panel.dotplot"),
        default.prepanel = lattice.getOption("prepanel.default.dotplot"),
        ...)

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

## S3 method for class 'formula'
stripplot(x,
          data,
          panel = lattice.getOption("panel.stripplot"),
          default.prepanel = lattice.getOption("prepanel.default.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,
       default.prepanel = lattice.getOption("prepanel.default.bwplot"),
       subscripts = !is.null(groups),
       subset = TRUE)

</pre>

<h3>Arguments</h3>

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

For the <code>"formula"</code> methods, <code>x</code> 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 &ldquo;Details&rdquo; section below. 

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

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

Cases where <code>x</code> is not a formula is handled by appropriate
methods. The <code>numeric</code> methods are equivalent to a call with
no left hand side and no conditioning variables in the formula. For
<code>barchart</code> and <code>dotplot</code>, non-trivial methods exist for
tables and arrays, documented at <code><a href="barchart.table.html">barchart.table</a></code>.

The conditioning variables <code>g1, g2, ...</code> must be either
factors or shingles. Shingles provide a way of using numeric
variables for conditioning; see the help page of
<code><a href="shingles.html">shingle</a></code> for details. Like factors, they have a
<code>"levels"</code> attribute, which is used in producing the
conditional plots. If necessary, numeric conditioning variables are
converted to shingles using the <code>shingle</code> function; however,
using <code><a href="shingles.html">equal.count</a></code> 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
<code>y</code> and RHS <code>x</code>) may consist of multiple terms separated
by a &lsquo;+&rsquo; sign, e.g., <code>y1 + y2 ~ x | a * b</code>. This
formula would be taken to mean that the user wants to plot both
<code>y1 ~ x | a * b</code> and <code>y2 ~ x | a * b</code>, but with the
<code>y1 ~ x</code> and <code>y2 ~ x</code> superposed in each panel. The two
groups will be distinguished by different graphical parameters.
This is essentially what the <code>groups</code> argument (see below)
would produce, if <code>y1</code> and <code>y2</code> were concatenated to
produce a longer vector, with the <code>groups</code> argument being an
indicator of which rows come from which variable. In fact, this is
exactly what is done internally using the <code><a href="../../stats/html/reshape.html">reshape</a></code>
function. This feature cannot be used in conjunction with the
<code>groups</code> argument.

To interpret <code>y1 + y2</code> as a sum, one can either set
<code>allow.multiple=FALSE</code> or use <code>I(y1+y2)</code>.

A variation on this feature is when the <code>outer</code> argument is set
to <code>TRUE</code>. 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 <code>x</code> and <code>y</code> variables should
both be numeric in <code>xyplot</code>, 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 <code>x</code> and <code>y</code> should be
numeric, and the other a factor or shingle. Which of these will
happen is determined by the <code>horizontal</code> argument &mdash; if
<code>horizontal=TRUE</code>, then <code>y</code> will be coerced to be a factor
or shingle, otherwise <code>x</code>. The default value of
<code>horizontal</code> is <code>FALSE</code> if <code>x</code> is a factor or
shingle, <code>TRUE</code> otherwise. (The functionality provided by
<code>horizontal=FALSE</code> is not S-compatible.)

Note that the <code>x</code> argument used to be called <code>formula</code> 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.

</td></tr>
<tr valign="top"><td><code>data</code></td>
<td>

For the <code>formula</code> methods, a data frame (or more precisely,
anything that is a valid <code>envir</code> argument in
<code><a href="../../base/html/eval.html">eval</a></code>, e.g., a list or an environment) containing values
for any variables in the formula, as well as <code>groups</code> and
<code>subset</code> if applicable. If not found in <code>data</code>, or if
<code>data</code> is unspecified, the variables are looked for in the
environment of the formula. For other methods (where <code>x</code> is
not a formula), <code>data</code> is usually ignored, often with a warning
if it is explicitly specified.

</td></tr>
<tr valign="top"><td><code>allow.multiple</code></td>
<td>

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

</td></tr>
<tr valign="top"><td><code>outer</code></td>
<td>

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

</td></tr>
<tr valign="top"><td><code>box.ratio</code></td>
<td>

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

</td></tr>
<tr valign="top"><td><code>horizontal</code></td>
<td>

Logical flag applicable to <code>bwplot</code>, <code>dotplot</code>,
<code>barchart</code>, and <code>stripplot</code>. Determines which of <code>x</code>
and <code>y</code> is to be a factor or shingle (<code>y</code> if TRUE,
<code>x</code> otherwise). Defaults to <code>FALSE</code> if <code>x</code> is a
factor or shingle, <code>TRUE</code> 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 <code>scales</code> in this case may be
<code>abbreviate = TRUE</code>, in which case long labels which would
usually overlap will be abbreviated. <code>scales</code> could also
contain a <code>minlength</code> argument in this case, which would be
passed to the <code>abbreviate</code> function.

</td></tr>
</table>

Common arguments: 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.

<table summary="R argblock">
<tr valign="top"><td><code>panel</code></td>
<td>

Once the subset of rows defined by each unique combination of the
levels of the grouping variables are obtained (see
&ldquo;Details&rdquo;), the corresponding <code>x</code> and <code>y</code> 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 <code>panel</code>
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
&ldquo;<code>panel.</code>&rdquo; followed by the name of the corresponding
high-level function (e.g., <code><a href="panel.xyplot.html">panel.xyplot</a></code>,
<code><a href="panel.barchart.html">panel.barchart</a></code>, 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
<code>x</code> and <code>y</code>, which would be provided by the conditioning
process. It can also have other arguments. It is useful to know in
this context that all arguments passed to a high-level Lattice
function (such as <code>xyplot</code>) 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 <code>...</code>
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 <code>x</code> and
<code>y</code> 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,
<code>panel.grid</code>, <code>panel.loess</code>, etc. There are also some
grid-compatible replacements of commonly used traditional graphics
functions useful for this purpose. For example, <code>lines</code> can be
replaced by <code>llines</code> (or equivalently, <code>panel.lines</code>).
Note that traditional graphics functions like <code>lines</code> will not
work in a lattice panel function.

One case where a bit more is required of the panel function is when
the <code>groups</code> argument is not <code>NULL</code>. In that case, the
panel function should also accept arguments named <code>groups</code> and
<code>subscripts</code> (see below for details). A useful panel function
predefined for use in such cases is <code><a href="panel.superpose.html">panel.superpose</a></code>,
which can be combined with different <code>panel.groups</code> functions
to determine what is plotted for each group. See the
&ldquo;Examples&rdquo; section for an interaction plot constructed in
this way. Several other panel functions can also handle the
<code>groups</code> argument, including the default ones for
<code>xyplot</code>, <code>barchart</code>, <code>dotplot</code>, and
<code>stripplot</code>.

Even when <code>groups</code> is not present, the panel function can have
<code>subscripts</code> as a formal argument. In either case, the
<code>subscripts</code> argument passed to the panel function are the
indices of the <code>x</code> and <code>y</code> data for that panel in the
original <code>data</code>, BEFORE taking into account the effect of
the <code>subset</code> argument. Note that <code>groups</code> remains
unaffected by any subsetting operations, so
<code>groups[subscripts]</code> gives the values of <code>groups</code> that
correspond to the data in that panel.

This interpretation of <code>subscripts</code> does not hold when the
extended formula interface is in use (i.e., when
<code>allow.multiple</code> is in effect). A comprehensive description
would be too complicated (details can be found in the source code of
the function <code>latticeParseFormula</code>), but in short, the extended
interface works by creating an artificial grouping variable that is
longer than the original data frame, and consequently,
<code>subscripts</code> 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 <code>subset</code>, in
which case <code>subscripts</code> may have no relationship with
corresponding rows in the original data frame.

One can also use functions called <code><a href="panel.number.html">panel.number</a></code> and
<code><a href="panel.number.html">packet.number</a></code>, 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
<code><a href="interaction.html">trellis.focus</a></code> 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 <code>perm.cond</code> and <code>index.cond</code> respectively), in
which case <code>packet.number</code> gives the index corresponding to the
&lsquo;natural&rsquo; ordering of that combination of levels of the
conditioning variables.

<code><a href="panel.xyplot.html">panel.xyplot</a></code> has an argument called <code>type</code> which
is worth mentioning here because it is quite frequently used (and as
mentioned above, can be passed to <code>xyplot</code> directly). In the
event that a <code>groups</code> variable is used,
<code><a href="panel.xyplot.html">panel.xyplot</a></code> calls <code><a href="panel.superpose.html">panel.superpose</a></code>,
arguments of which can also be passed directly to <code>xyplot</code>.
Panel functions for <code>bwplot</code> and friends should have an
argument called <code>horizontal</code> to account for the cases when
<code>x</code> is the factor or shingle.

</td></tr>
</table>

<table summary="R argblock">
<tr valign="top"><td><code>aspect</code></td>
<td>

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 <code>"fill"</code> (the
default) which tries to make the panels as big as possible to fill
the available space; <code>"xy"</code>, which computes the aspect ratio
based on the 45 degree banking rule (see <code><a href="banking.html">banking</a></code>); and
<code>"iso"</code> 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 <code>prepanel</code> function is specified and it returns components
<code>dx</code> and <code>dy</code>, these are used for banking calculations.
Otherwise, values from the default prepanel function are used. Not
all default prepanel functions produce sensible banking
calculations.

</td></tr>
<tr valign="top"><td><code>groups</code></td>
<td>

A variable or expression to be evaluated in <code>data</code>, 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 <code>groups</code> is specified, then
<code>groups</code> along with <code>subscripts</code> 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 <code>key</code>, <code>auto.key</code> and
<code><a href="simpleKey.html">simpleKey</a></code> for how to draw a key.

</td></tr>
<tr valign="top"><td><code>auto.key</code></td>
<td>

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

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

More precisely, if <code>auto.key</code> is not <code>FALSE</code>,
<code>groups</code> is non-null, and there is no <code>key</code> or
<code>legend</code> argument specified in the call, a key is created with
<code>simpleKey</code> with <code>levels(groups)</code> as the first
(<code>text</code>) 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 <code>auto.key</code> is provided as
a list and includes a <code>text</code> component, then that is used
instead as the text labels in the key, and the key is drawn even if
<code>groups</code> is not specified.

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

One disadvantage to using <code>key</code> (or even <code>simpleKey</code>)
directly is that the graphical parameters used in the key are
absolutely determined at the time when the <code>"trellis"</code> object
is created. Consequently, if a plot once created is
re-<code>plot</code>-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 <code>auto.key</code>, the key
is actually created at plotting time, so the settings will match.

</td></tr>
<tr valign="top"><td><code>prepanel</code></td>
<td>

A function that takes the same arguments as the <code>panel</code>
function and returns a list, possibly containing components named
<code>xlim</code>, <code>ylim</code>, <code>dx</code>, and <code>dy</code> (and less
frequently, <code>xat</code> and <code>yat</code>). 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 <code>xlim</code> and <code>ylim</code> components are similar to the high
level <code>xlim</code> and <code>ylim</code> arguments (i.e., they are usually
a numeric vector of length 2 defining a range, or a
character vector representing levels of a factor). If the
<code>xlim</code> and <code>ylim</code> arguments are not explicitly specified
(possibly as components in <code>scales</code>) in the high-level call,
then the actual limits of the panels are guaranteed to include the
limits returned by the prepanel function. This happens globally if
the <code>relation</code> component of <code>scales</code> is <code>"same"</code>, and
on a per-panel basis otherwise.

The <code>dx</code> and <code>dy</code> components are used for banking
computations in case <code>aspect</code> is specified as <code>"xy"</code>. See
documentation of <code><a href="banking.html">banking</a></code> for details.

If <code>xlim</code> or <code>ylim</code> is a character vector (which is
appropriate when the corresponding variable is a factor), this
implicitly indicates that the scale should include the first
<code>n</code> integers, where <code>n</code> is the length of <code>xlim</code> or
<code>ylim</code>, as the case may be. The elements of the character
vector are used as the default labels for these <code>n</code> integers.
Thus, to make this information consistent between panels, the
<code>xlim</code> or <code>ylim</code> 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 <code>xat</code> or <code>yat</code> may
be returned by the <code>prepanel</code> function, which should be a
subset of <code>1:n</code>, indicating which of the <code>n</code> values
(levels) are actually represented in the panel. This is useful when
calculating the limits with <code>relation="free"</code> or
<code>relation="sliced"</code> in <code>scales</code>.

The prepanel function is responsible for providing a meaningful
return value when the <code>x</code>, <code>y</code> (etc.) variables are
zero-length vectors. When nothing else is appropriate, values of NA
should be returned for the <code>xlim</code> and <code>ylim</code> components.

</td></tr>
<tr valign="top"><td><code>strip</code></td>
<td>

A logical flag or function. If <code>FALSE</code>, strips are not drawn.
Otherwise, strips are drawn using the <code>strip</code> function, which
defaults to <code>strip.default</code>. See documentation of
<code><a href="strip.default.html">strip.default</a></code> to see the arguments that are available
to the strip function. This description also applies to the
<code>strip.left</code> argument (see <code>...</code> 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).

</td></tr>
<tr valign="top"><td><code>xlab</code></td>
<td>

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

</td></tr>
<tr valign="top"><td><code>ylab</code></td>
<td>

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

</td></tr>
<tr valign="top"><td><code>scales</code></td>
<td>

Generally a list determining how the x- and y-axes (tick marks and
labels) are drawn. The list contains parameters in
<code>name=value</code> form, and may also contain two other lists called
<code>x</code> and <code>y</code> of the same form (described below).
Components of <code>x</code> and <code>y</code> affect the respective axes only,
while those in <code>scales</code> affect both. When parameters are
specified in both lists, the values in <code>x</code> or <code>y</code> are
used. Note that certain high-level functions have defaults that are
specific to a particular axis (e.g., <code>bwplot</code> has
<code>alternating=FALSE</code> for the categorical axis only); these can
only be overridden by an entry in the corresponding component of
<code>scales</code>.

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

The possible components are :

<dl>
<dt><code>relation</code></dt><dd>
A character string that determines how axis limits are
calculated for each panel. Possible values are <code>"same"</code>
(default), <code>"free"</code> and <code>"sliced"</code>. For
<code>relation="same"</code>, the same limits, usually large enough to
encompass all the data, are used for all the panels. For
<code>relation="free"</code>, limits for each panel is determined by
just the points in that panel. Behavior for
<code>relation="sliced"</code> 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 <code>prepanel</code> function, which
can be overridden by <code>xlim</code>, <code>ylim</code> or
<code>scales$limits</code> (except when <code>relation="sliced"</code>, in
which case explicitly specified limits are ignored with a
warning). When <code>relation</code> is <code>"free"</code>, <code>xlim</code> or
<code>ylim</code> 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).

</dd>
<dt><code>tick.number</code></dt><dd>
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 <code>xlim</code>.

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

</dd>
<dt><code>alternating</code></dt><dd>
Usually a logical flag specifying whether axis labels should
alternate from one side of the group of panels to the other.
For finer control, <code>alternating</code> can also be a vector
(replicated to be as long as the number of rows or columns per
page) consisting of the following numbers

<ul>
<li> 0: do not draw tick labels

</li>
<li> 1: bottom/left

</li>
<li> 2: top/right

</li>
<li> 3: both.

</li></ul>

<code>alternating</code> applies only when <code>relation="same"</code>.
The default is <code>TRUE</code>, or equivalently, <code>c(1, 2)</code>

</dd>
<dt><code>limits</code></dt><dd>
Same as <code>xlim</code> and <code>ylim</code>.

</dd>
<dt><code>at</code></dt><dd>
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.

</dd>
<dt><code>labels</code></dt><dd>
Vector of labels (characters or expressions) to go along with
<code>at</code>. Can also be a list like <code>at</code>.

</dd>
<dt><code>cex</code></dt><dd>
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.

</dd>
<dt><code>font</code>, <code>fontface</code>, <code>fontfamily</code></dt><dd>
Specifies the font to be used for axis labels.

</dd>
<dt><code>lineheight</code></dt><dd>
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 <code><a href="cloud.html">cloud</a></code>.)

</dd>
<dt><code>tck</code></dt><dd>
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.

</dd>
<dt><code>col</code></dt><dd>
Color of tick marks and labels.

</dd>
<dt><code>rot</code></dt><dd>
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.

</dd>
<dt><code>abbreviate</code></dt><dd>
A logical flag, indicating whether to abbreviate the labels
using the <code><a href="../../base/html/abbreviate.html">abbreviate</a></code> function. Can be useful for
long labels (e.g., in factors), especially on the x-axis.

</dd>
<dt><code>minlength</code></dt><dd>
Argument passed to <code><a href="../../base/html/abbreviate.html">abbreviate</a></code> if
<code>abbreviate=TRUE</code>.

</dd>
<dt><code>log</code></dt><dd>
Controls whether the corresponding variable (<code>x</code> or
<code>y</code>) will be log transformed before being passed to the
panel function. Defaults to <code>FALSE</code>, in which case the
data are not transformed. Other possible values are any number
that works as a base for taking logarithm, <code>TRUE</code> (which is
equivalent to 10), and <code>"e"</code> (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.,
<code>scales=list(x = list(log = 2))</code> is equivalent to <code>y ~
 log2(x)</code>.

See entry for <code>equispaced.log</code> below for details on how to
control axis labeling.

</dd>
<dt><code>equispaced.log</code></dt><dd>
A logical flag indicating whether tick mark locations should be
equispaced when &lsquo;log scales&rsquo; are in use. Defaults to
<code>TRUE</code>.

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

See also <code>xscale.components.logpower</code> in the
latticeExtra package.

</dd>
<dt><code>format</code></dt><dd>
The <code>format</code> to use for POSIXct variables. See
<code><a href="../../base/html/strptime.html">strptime</a></code> for description of valid values.

</dd>
<dt><code>axs</code></dt><dd>
A character string, <code>"r"</code> (default) or <code>"i"</code>. 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.)

</dd>
</dl>

Note that much of the function of <code>scales</code> is accomplished by
<code>pscales</code> in <code><a href="splom.html">splom</a></code>.

</td></tr>
<tr valign="top"><td><code>subscripts</code></td>
<td>

A logical flag specifying whether or not a vector named
<code>subscripts</code> should be passed to the panel function. Defaults
to <code>FALSE</code>, unless <code>groups</code> is specified, or if the panel
function accepts an argument named <code>subscripts</code>. This argument
is useful if one wants the subscripts to be passed on even if these
conditions do not hold; a typical example is when one wishes to
augment a Lattice plot after it has been drawn, e.g., using
<code><a href="interaction.html">panel.identify</a></code>.

</td></tr>
<tr valign="top"><td><code>subset</code></td>
<td>

An expression that evaluates to a logical or integer indexing
vector. Like <code>groups</code>, it is evaluated in <code>data</code>. Only
the resulting rows of <code>data</code> are used for the plot. If
<code>subscripts</code> is <code>TRUE</code>, the subscripts provided to the
panel function will be indices referring to the rows of <code>data</code>
prior to the subsetting. Whether levels of factors in the data
frame that are unused after the subsetting will be dropped depends
on the <code>drop.unused.levels</code> argument.

</td></tr>
<tr valign="top"><td><code>xlim</code></td>
<td>

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 <code>x</code>. The latter form is
interpreted as a range containing c(1, length(xlim)), with the
character vector determining labels at tick positions
<code>1:length(xlim)</code>.

<code>xlim</code> 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
<code>scales$x$relation</code> is <code>"free"</code>, in which case these are
treated as if they were the corresponding limit components returned
by prepanel calculations.

</td></tr>
<tr valign="top"><td><code>ylim</code></td>
<td>
 Similar to <code>xlim</code>, applied to the y-axis. 
</td></tr>
<tr valign="top"><td><code>drop.unused.levels</code></td>
<td>

A logical flag indicating whether the unused levels of factors will
be dropped, usually relevant when a subsetting operation is
performed or an <code><a href="../../base/html/interaction.html">interaction</a></code> 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 <code>cond</code> and
<code>data</code>, both logical, indicating desired behavior for
conditioning variables and primary variables respectively. The
default is given by <code>lattice.getOption("drop.unused.levels")</code>,
which is initially set to <code>TRUE</code> for both components. Note
that this argument does not control dropping of levels of the
<code>groups</code> argument.

</td></tr>
<tr valign="top"><td><code>default.scales</code></td>
<td>

A list giving the default values of <code>scales</code> 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.

</td></tr>
<tr valign="top"><td><code>default.prepanel</code></td>
<td>

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

</td></tr>
<tr valign="top"><td><code>lattice.options</code></td>
<td>

A list that could be supplied to <code><a href="lattice.options.html">lattice.options</a></code>.
These options are applied temporarily for the duration of the call,
after which the settings revert back to what they were before. The
options are retained along with the object and reused during
plotting. This enables the user to attach options settings to the
trellis object itself rather than change the settings globally. See
also the <code>par.settings</code> argument described below for a similar
treatment of graphical settings.

</td></tr>
<tr valign="top"><td><code>...</code></td>
<td>

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 <code>trellis.skeleton</code>. 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
&ldquo;<code>panel.</code>&rdquo; followed by the name of the high-level
function; for example, the default panel function for <code>bwplot</code>
is <code>panel.bwplot</code>. 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:

<dl>
<dt><code>as.table</code>:</dt><dd>
A logical flag that controls the order in which panels should be
displayed: if <code>FALSE</code> (the default), panels are drawn left to
right, bottom to top (as in a graph); if <code>TRUE</code>, left to
right, top to bottom (as in a table).

</dd>
<dt><code>between</code>:</dt><dd>
A list with components <code>x</code> and <code>y</code> (both usually 0 by
default), numeric vectors specifying the space between the
panels (units are character heights). <code>x</code> and <code>y</code> 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 <code>between</code> values for different pages.

</dd>
<dt><code>key</code>:</dt><dd>
A list that defines a legend to be drawn on the plot. This list
is used as an argument to the <code><a href="draw.key.html">draw.key</a></code> function,
which produces a <code>"grob"</code> (grid object) eventually plotted
by the print method for <code>"trellis"</code> 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
<code><a href="simpleKey.html">simpleKey</a></code> function; the latter is more convenient
but less flexible. The <code>auto.key</code> argument can be even
more convenient for the most common situation where legends are
used, namely, in conjunction with a grouping variable. To use
more than one legend, or to have arbitrary legends not
constrained by the structure imposed by <code>key</code>, use the
<code>legend</code> argument.

The position of the key can be controlled in either of two
possible ways. If a component called <code>space</code> is present,
the key is positioned outside the plot region, in one of the
four sides, determined by the value of <code>space</code>, which can
be one of <code>"top"</code>, <code>"bottom"</code>, <code>"left"</code> and
<code>"right"</code>. Alternatively, the key can be positioned inside
the plot region by specifying components <code>x</code>, <code>y</code> and
<code>corner</code>. <code>x</code> and <code>y</code> determine the location of
the corner of the key given by <code>corner</code>, which is usually
one of <code>c(0,0)</code>, <code>c(1,0)</code>, <code>c(1,1)</code> and
<code>c(0,1)</code>, which denote the corners of the unit square.
Fractional values are also allowed, in which case <code>x</code> and
<code>y</code> determine the position of an arbitrary point inside (or
outside for values outside the unit interval) the key.

<code>x</code> and <code>y</code> should be numbers between 0 and 1, giving
coordinates with respect to the &ldquo;display area&rdquo;.
Depending on the value of the <code>"legend.bbox"</code> option (see
<code><a href="lattice.options.html">lattice.getOption</a></code>), this can be either the full
figure region (<code>"full"</code>), or just the region that bounds
the panels and strips (<code>"panel"</code>).

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
<code>"rectangles"</code>, <code>"lines"</code>, <code>"points"</code> or
<code>"text"</code>. Each of these must be lists with relevant graphical
parameters (see later) controlling their appearance. The <code>key</code>
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
<code>"text"</code>s) is taken to be the largest of the lengths of the
graphical components, including the ones specified outside (see
the entry for <code>rep</code> below for details on this). The
<code>"text"</code> 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 <code>key</code> and
also in the components named <code>"text"</code>, <code>"lines"</code>,
<code>"points"</code> and <code>"rectangles"</code> (as appropriate) are:

<ul>
<li> <code>cex=1</code> (text, lines, points)

</li>
<li> <code>col="black"</code> (text, rectangles, lines, points)

</li>
<li> <code>alpha=1</code> (text, rectangles, lines, points)

</li>
<li> <code>fill="transparent"</code> (lines, points)

</li>
<li> <code>lty=1</code> (lines)

</li>
<li> <code>lwd=1</code> (lines, points)

</li>
<li> <code>font=1</code> (text, points)

</li>
<li> <code>fontface</code> (text, points)

</li>
<li> <code>fontfamily</code> (text, points)

</li>
<li> <code>pch=8</code> (lines, points)

</li>
<li> <code>adj=0</code> (text)

</li>
<li> <code>type="l"</code> (lines)

</li>
<li> <code>size=5</code> (rectangles, lines)

</li>
<li> <code>height=1</code> (rectangles)

</li>
<li> <code>lineheight=1</code> (text)

</li>
<li> <code>angle=0</code> (rectangles, but ignored)

</li>
<li> <code>density=-1</code> (rectangles, but ignored)

</li></ul>

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

<code>angle</code> and <code>density</code> are unimplemented. <code>size</code>
determines the width of columns of rectangles and lines in
character widths. <code>type</code> is relevant for lines; <code>"l"</code>
denotes a line, <code>"p"</code> denotes a point, and <code>"b"</code> and
<code>"o"</code> both denote both together. <code>height</code> gives
heights of rectangles as a fraction of the default.

Other possible components of <code>key</code> are:

<dl>
<dt><code>reverse.rows</code></dt><dd>
Logical flag, defaulting to <code>FALSE</code>. If <code>TRUE</code>,
all components are reversed after being replicated
(the details of which may depend on the value of
<code>rep</code>). This is useful in certain situations, e.g.,
with a grouped <code>barchart</code> with <code>stack = TRUE</code> 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 <code>reverse.rows = TRUE</code>. Note that in
this case, unless all columns have the same number or rows,
they will no longer be aligned.

</dd>
<dt><code>between</code></dt><dd>
Numeric vector giving the amount of space (character widths)
surrounding each column (split equally on both sides).

</dd>
<dt><code>title</code></dt><dd>
String or expression giving a title for the key.

</dd>
<dt><code>rep</code></dt><dd>
Logical flag, defaults to <code>TRUE</code>. By default, it is
assumed that all columns in the key (except the
<code>"text"</code>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 <code>rep=FALSE</code>, in which
case the length of each column will be determined by
components of that column alone.

</dd>
<dt><code>cex.title</code></dt><dd>
Zoom factor for the title.

</dd>
<dt><code>lines.title</code></dt><dd>
The amount of vertical space to be occupied by the title in
lines (in multiples of itself). Defaults to 2.

</dd>
<dt><code>padding.text</code></dt><dd>
The amount of space (padding) to be used above and below
each row containing text, in multiples of the default, which
is currently <code>0.2 * "lines"</code>. 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.

</dd>
<dt><code>background</code></dt><dd>
Background color for the legend. Defaults to the global
background color.

</dd>
<dt><code>alpha.background</code></dt><dd>
An alpha transparency value between 0 and 1 for the
background.

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

</dd>
<dt><code>transparent=FALSE</code></dt><dd>
Logical flag, whether legend should have a transparent
background.

</dd>
<dt><code>just</code></dt><dd>
A character or numeric vector of length one or two giving
horizontal and vertical justification for the placement of
the legend. See <code><a href="../../grid/html/grid.layout.html">grid.layout</a></code>
for more precise details.

</dd>
<dt><code>columns</code></dt><dd>
The number of column-blocks (drawn side by side) the legend
is to be divided into.

</dd>
<dt><code>between.columns</code></dt><dd>
Space between column blocks, in addition to <code>between</code>.

</dd>
<dt><code>divide</code></dt><dd>
Number of point symbols to divide each line when <code>type</code> is
<code>"b"</code> or <code>"o"</code> in <code>lines</code>.

</dd>
</dl>

</dd>
<dt><code>legend</code>:</dt><dd>
The legend argument can be useful if one wants to place more
than one key. It also allows the use of arbitrary
<code>"grob"</code>s (grid objects) as legends.

If used, <code>legend</code> must be a list, with an arbitrary number
of components. Each component must be named one of
<code>"left"</code>, <code>"right"</code>, <code>"top"</code>, <code>"bottom"</code>, or
<code>"inside"</code>. The name <code>"inside"</code> can be repeated, but
not the others. This name will be used to determine the
location for that component, and is similar to the <code>space</code>
component of <code>key</code>. If <code>key</code> (or <code>colorkey</code> for
<code><a href="levelplot.html">levelplot</a></code> and <code><a href="cloud.html">wireframe</a></code>) is
specified, their <code>space</code> component must not conflict with
the name of any component of <code>legend</code>.

Each component of <code>legend</code> must have a component called
<code>fun</code>. This can be a <code>"grob"</code>, or a function (or the
name of a function) that produces a <code>"grob"</code> when called.
If this function expects any arguments, they must be supplied as
a list in another component called <code>args</code>. For components
named <code>"inside"</code>, there can be additional components called
<code>x</code>, <code>y</code> and <code>corner</code>, which work in the same way
as for <code>key</code>.

</dd>
<dt><code>page</code>:</dt><dd>
A function of one argument (page number) to be called after
drawing each page. The function must be
&lsquo;grid-compliant&rsquo;, and is called with the whole display
area as the default viewport.

</dd>
<dt><code>xlab.top</code>, <code>ylab.right</code>:</dt><dd>
Labels for the x-axis on top, and y-axis on the right. Similar
to <code>xlab</code> and <code>ylab</code>, but less commonly used.

</dd>
<dt><code>main</code>:</dt><dd>
Typically a character string or expression describing the main
title to be placed on top of each page. Defaults to
<code>NULL</code>.

<code>main</code> (as well as <code>xlab</code>, <code>ylab</code> and <code>sub</code>)
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 <code><a href="../../grDevices/html/plotmath.html">plotmath</a></code>. The label can be a vector,
in which case the components will be spaced out horizontally (or
vertically for <code>ylab</code>). This feature can be used to
provide column or row labels rather than a single axis label.

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

<code>main</code>, <code>sub</code>, <code>xlab</code>, <code>ylab</code>,
<code>xlab.top</code>, and <code>ylab.right</code> can also be arbitrary
<code>"grob"</code>s (grid graphical objects).

</dd>
<dt><code>sub</code>:</dt><dd>
Character string or expression (or a list or <code>"grob"</code>) for
a subtitle to be placed at the bottom of each page. See entry
for <code>main</code> for finer control options.

</dd>
<dt><code>par.strip.text</code>:</dt><dd>
A list of parameters to control the appearance of strip text.
Notable components are <code>col</code>, <code>cex</code>, <code>font</code>, and
<code>lines</code>. 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
<code>"\n"</code>-s) or if the default height seems too small or too
large.

Additionally, the <code>lineheight</code> component can control the
space between multiple lines. The labels can be abbreviated
when shown by specifying <code>abbreviate = TRUE</code>, in which case
the components <code>minlength</code> and <code>dot</code> (passed along to
the <code><a href="../../base/html/abbreviate.html">abbreviate</a></code> function) can be specified to
control the details of how this is done.

</dd>
<dt><code>layout</code>:</dt><dd>
In general, a conditioning plot in Lattice consists of several
panels arranged in a rectangular array, possibly spanning
multiple pages. <code>layout</code> determines this arrangement.

<code>layout</code> is a numeric vector of length 2 or 3 giving the
number of columns, rows, and pages (optional) in a multipanel
display. By default, the number of columns is the number of
levels of the first conditioning variable and the number of rows
is the number of levels of the second conditioning variable. If
there is only one conditioning variable, the default layout
vector is <code>c(0,n)</code>, where <code>n</code> 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 <code><a href="../../graphics/html/par.html">par</a>("din")</code>). If <code>NA</code>
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.

</dd>
<dt><code>skip</code>:</dt><dd>
A logical vector (default <code>FALSE</code>), replicated to be as
long as the number of panels (spanning all pages). For elements
that are <code>TRUE</code>, 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.

</dd>
<dt><code>strip.left</code>:</dt><dd>
<code>strip.left</code> can be used to draw strips on the left of each
panel, which can be useful for wide short panels, as in
time-series (or similar) plots. See the entry for <code>strip</code>
for detailed usage.

</dd>
<dt><code>xlab.default</code>, <code>ylab.default</code>:</dt><dd>
Fallback default for <code>xlab</code> and <code>ylab</code> when they are
not specified. If <code>NULL</code>, 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.

</dd>
<dt><code>xscale.components</code>, <code>yscale.components</code>:</dt><dd>
Functions that determine axis annotation for the x and y axes
respectively. See documentation for
<code><a href="axis.default.html">xscale.components.default</a></code>, the default values of
these arguments, to learn more.

</dd>
<dt><code>axis</code>:</dt><dd>
Function responsible for drawing axis annotation. See
documentation for <code><a href="axis.default.html">axis.default</a></code>, the default value
of this argument, to learn more.

</dd>
<dt><code>perm.cond</code>:</dt><dd>
An integer vector, a permutation of <code>1:n</code>, where <code>n</code>
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.
<code>perm.cond</code> can modify this order. If the trellis display
is thought of as an <code>n</code>-dimensional array, then during
printing, its dimensions are permuted using <code>perm.cond</code> as
the <code>perm</code> argument does in <code><a href="../../base/html/aperm.html">aperm</a></code>.

</dd>
<dt><code>index.cond</code>:</dt><dd>
Whereas <code>perm.cond</code> permutes the dimensions of the
multidimensional array of panels, <code>index.cond</code> can be used
to subset (or reorder) margins of that array. <code>index.cond</code>
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. <code>index.cond</code> can be
used to choose a &lsquo;subset&rsquo; (in the R sense) of these
levels, which is then used as the display order for that
variable. If <code>index.cond</code> is a list, it has to be as long
as the number of conditioning variables, and the <code>i</code>-th
component has to be a valid indexing vector for
<code>levels(g_i)</code>, where <code>g_i</code> is the <code>i</code>-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 <code>subset</code> and <code>drop.unused.levels</code>
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 <code>TRUE</code>.

Note that the components of <code>index.cond</code> are interpreted in
the order of the conditioning variables in the original call,
and is not affected by <code>perm.cond</code>.

Another possibility is to specify <code>index.cond</code> 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 <code>...</code> 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 <code>perm.cond</code> and
<code>index.cond</code> to update an existing <code>"trellis"</code> object,
thus allowing it to be displayed in a different arrangement
without re-calculating the data subsets that go into each panel.
In the <code><a href="update.trellis.html">update.trellis</a></code> method, both can be set to
<code>NULL</code>, which reverts these back to their defaults.

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

</dd>
<dt><code>plot.args</code>:</dt><dd>
A list containing possible arguments to
<code><a href="print.trellis.html">plot.trellis</a></code>, which will be used by the
<code>plot</code> or <code>print</code> 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.

</dd>
</dl>

</td></tr>
</table>

<h3>Details</h3>

The high-level functions documented here, as well as other high-level
Lattice functions, are generic, with the <code>formula</code> 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 <code>g1, g2, ...</code>, a separate
&ldquo;packet&rdquo; is produced, consisting of the points <code>(x,y)</code> 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 <code>layout</code> 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 <code>index.cond</code> 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
<code>as.table = TRUE</code>, 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 <code>as.table=TRUE</code>; this can be done by setting
<code>lattice.options(default.args = list(as.table = TRUE))</code>. Default
values can be set in this manner for the following arguments:
<code>as.table</code>, <code>aspect</code>, <code>between</code>, <code>page</code>,
<code>main</code>, <code>sub</code>, <code>par.strip.text</code>, <code>layout</code>,
<code>skip</code> and <code>strip</code>. 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 <code>g1</code> varying fastest, followed by
<code>g2</code>, 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
<code>index.cond</code> and <code>perm.cond</code> arguments, possibly using the
<code><a href="update.trellis.html">update</a></code> (and other related)
method(s).

<h3>Value</h3>

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

Most of the arguments documented here are also applicable for the
other high-level functions in the lattice package. These are not
described in any detail elsewhere unless relevant, and this should be
considered the canonical documentation for such arguments.

Any arguments passed to these functions and not recognized by them
will be passed to the panel function. Most predefined panel functions
have arguments that customize its output. These arguments are
described only in the help pages for these panel functions, but can
usually be supplied as arguments to the high-level plot.

<h3>Author(s)</h3>

Deepayan Sarkar <a href="mailto:Deepayan.Sarkar@R-project.org">Deepayan.Sarkar@R-project.org</a>

<h3>References</h3>

Sarkar, Deepayan (2008) Lattice: Multivariate Data Visualization
with R, Springer. <a href="http://lmdvr.r-forge.r-project.org/">http://lmdvr.r-forge.r-project.org/</a>

<code><a href="Lattice.html">Lattice</a></code> for an overview of the package, as well as
<code><a href="barchart.table.html">barchart.table</a></code>,
<code><a href="print.trellis.html">print.trellis</a></code>,
<code><a href="shingles.html">shingle</a></code>,
<code><a href="banking.html">banking</a></code>,
<code><a href="../../stats/html/reshape.html">reshape</a></code>,
<code><a href="panel.xyplot.html">panel.xyplot</a></code>,
<code><a href="panel.bwplot.html">panel.bwplot</a></code>,
<code><a href="panel.barchart.html">panel.barchart</a></code>,
<code><a href="panel.dotplot.html">panel.dotplot</a></code>,
<code><a href="panel.stripplot.html">panel.stripplot</a></code>,
<code><a href="panel.superpose.html">panel.superpose</a></code>,
<code><a href="panel.loess.html">panel.loess</a></code>,
<code><a href="panel.functions.html">panel.average</a></code>,
<code><a href="strip.default.html">strip.default</a></code>,
<code><a href="simpleKey.html">simpleKey</a></code>
<code><a href="trellis.par.get.html">trellis.par.set</a></code>

<h3>Examples</h3>

<pre>
require(stats)

## Tonga Trench Earthquakes

Depth &lt;- 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 &lt;- 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 &lt;- data.frame(state.x77,
                     state.name = dimnames(state.x77)[[1]],
                     state.region = state.region)
xyplot(Murder ~ Population | state.region, data = states,
       groups = state.name,
       panel = function(x, y, subscripts, groups) {
           ltext(x = x, y = y, labels = groups[subscripts], cex=1,
                 fontfamily = "HersheySans")
       })

## Stacked bar chart

barchart(yield ~ variety | site, data = barley,
         groups = year, layout = c(1,6), stack = TRUE,
         auto.key = list(space = "right"),
         ylab = "Barley Yield (bushels/acre)",
         scales = list(x = list(rot = 45)))

bwplot(voice.part ~ height, data=singer, xlab="Height (inches)")

dotplot(variety ~ yield | year * site, data=barley)

## Grouped dot plot showing anomaly at Morris

dotplot(variety ~ yield | site, data = barley, groups = year,
        key = simpleKey(levels(barley$year), space = "right"),
        xlab = "Barley Yield (bushels/acre) ",
        aspect=0.5, layout = c(1,6), ylab=NULL)

stripplot(voice.part ~ jitter(height), data = singer, aspect = 1,
          jitter.data = TRUE, xlab = "Height (inches)")

## Interaction Plot

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

## longer version with no x-ticks

## Not run: 
bwplot(decrease ~ treatment, OrchardSprays, groups = rowpos,
       panel = "panel.superpose",
       panel.groups = "panel.linejoin",
       xlab = "treatment",
       key = list(lines = Rows(trellis.par.get("superpose.line"),
                  c(1:7, 1)),
                  text = list(lab = as.character(unique(OrchardSprays$rowpos))),
                  columns = 4, title = "Row position"))

## End(Not run)

</pre>

<hr /><div style="text-align: center;">[Package lattice version 0.20-38 <a href="00Index.html">Index</a>]</div>
</body></html>