Package 'lattice' reference manual

Title:	Trellis Graphics for R
Description:	A powerful and elegant high-level data visualization system inspired by Trellis graphics, with an emphasis on multivariate data. Lattice is sufficient for typical graphics needs, and is also flexible enough to handle most nonstandard requirements. See ?Lattice for an introduction.
Authors:	Deepayan Sarkar [aut, cre] , Felix Andrews [ctb], Kevin Wright [ctb] (documentation), Neil Klepeis [ctb], Johan Larsson [ctb] (miscellaneous improvements), Zhijian (Jason) Wen [cph] (filled contour code), Paul Murrell [ctb], Stefan Eng [ctb] (violin plot improvements), Achim Zeileis [ctb] (modern colors), Alexandre Courtiol [ctb] (generics for larrows, lpolygon, lrect and lsegments)
Maintainer:	Deepayan Sarkar <[email protected]>
License:	GPL (>= 2)
Version:	0.22-6
Built:	2024-03-27 22:42:15 UTC
Source:	CRAN

Common Bivariate Trellis Plots

Description

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.

Usage

xyplot(x, data, ...)
dotplot(x, data, ...)
barchart(x, data, ...)
stripplot(x, data, ...)
bwplot(x, data, ...)

## S3 method for class 'formula'
xyplot(x,
       data,
       allow.multiple = is.null(groups) || outer,
       outer = !is.null(groups),
       auto.key = lattice.getOption("default.args")$auto.key,
       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 'data.frame'
xyplot(x, data = NULL, formula = data, ...)

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

## S3 method for class 'data.frame'
dotplot(x, data = NULL, formula = data, ...)

## 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 'data.frame'
barchart(x, data = NULL, formula = data, ...)

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

## S3 method for class 'data.frame'
stripplot(x, data = NULL, formula = data, ...)

## S3 method for class 'formula'
bwplot(x,
       data,
       allow.multiple = is.null(groups) || outer,
       outer = FALSE,
       auto.key = lattice.getOption("default.args")$auto.key,
       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)

## S3 method for class 'data.frame'
bwplot(x, data = NULL, formula = data, ...)

Arguments

`x`	All high-level function in lattice are generic. `x` is the object on which method dispatch is carried out. For the `"formula"` methods, `x` must be a formula describing the primary variables (used for the per-panel display) and the optional conditioning variables (which define the subsets plotted in different panels) to be used in the plot. Conditioning is described in the “Details” section below. For the functions documented here, the formula is generally of the form `y ~ x \| g1 * g2 * ...` (or equivalently, `y ~ x \| g1 + g2 + ...`), indicating that plots of `y` (on the y-axis) versus `x` (on the x-axis) should be produced conditional on the variables `g1, g2, ...`. Here `x` and `y` are the primary variables, and `g1, g2, ...` are the conditioning variables. The conditioning variables may be omitted to give a formula of the form `y ~ x`, in which case the plot will consist of a single panel with the full dataset. The formula can also involve expressions, e.g., `sqrt()`, `log()`, etc. See the `data` argument below for rules regarding evaluation of the terms in the formula. With the exception of `xyplot`, the functions documented here may also be supplied a formula of the form `~ x \| g1 * g2 * ...`. In that case, `y` defaults to `names(x)` if `x` is named, and a factor with a single level otherwise. Cases where `x` is not a formula is handled by appropriate methods. The `numeric` methods are equivalent to a call with no left hand side and no conditioning variables in the formula. For `barchart` and `dotplot`, non-trivial methods exist for tables and arrays, documented at `barchart.table`. The conditioning variables `g1, g2, ...` must be either factors or shingles. Shingles provide a way of using numeric variables for conditioning; see the help page of `shingle` for details. Like factors, they have a `"levels"` attribute, which is used in producing the conditional plots. If necessary, numeric conditioning variables are converted to shingles using the `shingle` function; however, using `equal.count` may be more appropriate in many cases. Character variables are coerced to factors. Extended formula interface: As a useful extension of the interface described above, the primary variable terms (both the LHS `y` and RHS `x`) may consist of multiple terms separated by a ‘+’ sign, e.g., `y1 + y2 ~ x \| a * b`. This formula would be taken to mean that the user wants to plot both `y1 ~ x \| a * b` and `y2 ~ x \| a * b`, but with the `y1 ~ x` and `y2 ~ x` superposed in each panel. The two groups will be distinguished by different graphical parameters. This is essentially what the `groups` argument (see below) would produce, if `y1` and `y2` were concatenated to produce a longer vector, with the `groups` argument being an indicator of which rows come from which variable. In fact, this is exactly what is done internally using the `reshape` function. This feature cannot be used in conjunction with the `groups` argument. To interpret `y1 + y2` as a sum, one can either set `allow.multiple=FALSE` or use `I(y1+y2)`. A variation on this feature is when the `outer` argument is set to `TRUE`. In that case, the plots are not superposed in each panel, but instead separated into different panels (as if a new conditioning variable had been added). Primary variables: The `x` and `y` variables should both be numeric in `xyplot`, and an attempt is made to coerce them if not. However, if either is a factor, the levels of that factor are used as axis labels. In the other four functions documented here, exactly one of `x` and `y` should be numeric, and the other a factor or shingle. Which of these will happen is determined by the `horizontal` argument — if `horizontal=TRUE`, then `y` will be coerced to be a factor or shingle, otherwise `x`. The default value of `horizontal` is `FALSE` if `x` is a factor or shingle, `TRUE` otherwise. (The functionality provided by `horizontal=FALSE` is not S-compatible.) Note that the `x` argument used to be called `formula` in earlier versions (when the high-level functions were not generic and the formula method was essentially the only method). This is no longer allowed. It is recommended that this argument not be named in any case, but instead be the first (unnamed) argument.
`data`	For the `formula` methods, a data frame (or more precisely, anything that is a valid `envir` argument in `eval`, e.g., a list or an environment) containing values for any variables in the formula, as well as `groups` and `subset` if applicable. If not found in `data`, or if `data` is unspecified, the variables are looked for in the environment of the formula. For other methods (where `x` is not a formula), `data` is usually ignored, often with a warning if it is explicitly specified.
`formula`	The formula to be used for the `"data.frame"` methods. See documentation for argument `x` for details.
`allow.multiple`	Logical flag specifying whether the extended formula interface described above should be in effect. Defaults to `TRUE` whenever sensible.
`outer`	Logical flag controlling what happens with formulas using the extended interface described above (see the entry for `x` for details). Defaults to `FALSE`, except when `groups` is explicitly specified or grouping does not make sense for the default panel function.
`box.ratio`	Applicable to `barchart` and `bwplot`. Specifies the ratio of the width of the rectangles to the inter-rectangle space. See also the `box.width` argument in the respective default panel functions.
`horizontal`	Logical flag applicable to `bwplot`, `dotplot`, `barchart`, and `stripplot`. Determines which of `x` and `y` is to be a factor or shingle (`y` if TRUE, `x` otherwise). Defaults to `FALSE` if `x` is a factor or shingle, `TRUE` otherwise. This argument is used to process the arguments to these high-level functions, but more importantly, it is passed as an argument to the panel function, which is expected to use it as appropriate. A potentially useful component of `scales` in this case may be `abbreviate = TRUE`, in which case long labels which would usually overlap will be abbreviated. `scales` could also contain a `minlength` argument in this case, which would be passed to the `abbreviate` function.

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.

`panel`	Once the subset of rows defined by each unique combination of the levels of the grouping variables are obtained (see “Details”), the corresponding `x` and `y` variables (or other variables, as appropriate, in the case of other high-level functions) are passed on to be plotted in each panel. The actual plotting is done by the function specified by the `panel` argument. The argument may be a function object or a character string giving the name of a predefined function. Each high-level function has its own default panel function, named as “`panel.`” followed by the name of the corresponding high-level function (e.g., `panel.xyplot`, `panel.barchart`, etc). Much of the power of Trellis Graphics comes from the ability to define customized panel functions. A panel function appropriate for the functions described here would usually expect arguments named `x` and `y`, which would be provided by the conditioning process. It can also have other arguments. It is useful to know in this context that all arguments passed to a high-level Lattice function (such as `xyplot`) that are not recognized by it are passed through to the panel function. It is thus generally good practice when defining panel functions to allow a `...` argument. Such extra arguments typically control graphical parameters, but other uses are also common. See documentation for individual panel functions for specifics. Note that unlike in S-PLUS, it is not guaranteed that panel functions will be supplied only numeric vectors for the `x` and `y` arguments; they can be factors as well (but not shingles). Panel functions need to handle this case, which in most cases can be done by simply coercing them to numeric. Technically speaking, panel functions must be written using Grid graphics functions. However, knowledge of Grid is usually not necessary to construct new custom panel functions, as there are several predefined panel functions which can help; for example, `panel.grid`, `panel.loess`, etc. There are also some grid-compatible replacements of commonly used traditional graphics functions useful for this purpose. For example, `lines` can be replaced by `llines` (or equivalently, `panel.lines`). Note that traditional graphics functions like `lines` will not work in a lattice panel function. One case where a bit more is required of the panel function is when the `groups` argument is not `NULL`. In that case, the panel function should also accept arguments named `groups` and `subscripts` (see below for details). A useful panel function predefined for use in such cases is `panel.superpose`, which can be combined with different `panel.groups` functions to determine what is plotted for each group. See the “Examples” section for an interaction plot constructed in this way. Several other panel functions can also handle the `groups` argument, including the default ones for `xyplot`, `barchart`, `dotplot`, and `stripplot`. Even when `groups` is not present, the panel function can have `subscripts` as a formal argument. In either case, the `subscripts` argument passed to the panel function are the indices of the `x` and `y` data for that panel in the original `data`, BEFORE taking into account the effect of the `subset` argument. Note that `groups` remains unaffected by any subsetting operations, so `groups[subscripts]` gives the values of `groups` that correspond to the data in that panel. This interpretation of `subscripts` does not hold when the extended formula interface is in use (i.e., when `allow.multiple` is in effect). A comprehensive description would be too complicated (details can be found in the source code of the function `latticeParseFormula`), but in short, the extended interface works by creating an artificial grouping variable that is longer than the original data frame, and consequently, `subscripts` needs to refer to rows beyond those in the original data. To further complicate matters, the artificial grouping variable is created after any effect of `subset`, in which case `subscripts` may have no relationship with corresponding rows in the original data frame. One can also use functions called `panel.number` and `packet.number`, representing panel order and packet order respectively, inside the panel function (as well as the strip function or while interacting with a lattice display using `trellis.focus` etc). Both provide a simple integer index indicating which panel is currently being drawn, but differ in how the count is calculated. The panel number is a simple incremental counter that starts with 1 and is incremented each time a panel is drawn. The packet number on the other hand indexes the combination of levels of the conditioning variables that is represented by that panel. The two indices coincide unless the order of conditioning variables is permuted and/or the plotting order of levels within one or more conditioning variables is altered (using `perm.cond` and `index.cond` respectively), in which case `packet.number` gives the index corresponding to the ‘natural’ ordering of that combination of levels of the conditioning variables. `panel.xyplot` has an argument called `type` which is worth mentioning here because it is quite frequently used (and as mentioned above, can be passed to `xyplot` directly). In the event that a `groups` variable is used, `panel.xyplot` calls `panel.superpose`, arguments of which can also be passed directly to `xyplot`. Panel functions for `bwplot` and friends should have an argument called `horizontal` to account for the cases when `x` is the factor or shingle.
`aspect`	This argument controls the physical aspect ratio of the panels, which is usually the same for all the panels. It can be specified as a ratio (vertical size/horizontal size) or as a character string. In the latter case, legitimate values are `"fill"` (the default) which tries to make the panels as big as possible to fill the available space; `"xy"`, which computes the aspect ratio based on the 45 degree banking rule (see `banking`); and `"iso"` for isometric scales, where the relation between physical distance on the device and distance in the data scale are forced to be the same for both axes. If a `prepanel` function is specified and it returns components `dx` and `dy`, these are used for banking calculations. Otherwise, values from the default prepanel function are used. Not all default prepanel functions produce sensible banking calculations.
`groups`	A variable or expression to be evaluated in `data`, expected to act as a grouping variable within each panel, typically used to distinguish different groups by varying graphical parameters like color and line type. Formally, if `groups` is specified, then `groups` along with `subscripts` is passed to the panel function, which is expected to handle these arguments. For high level functions where grouping is appropriate, the default panel functions can handle grouping. It is very common to use a key (legend) when a grouping variable is specified. See entries for `key`, `auto.key` and `simpleKey` for how to draw a key.
`auto.key`	A logical, or a list containing components to be used as arguments to `simpleKey`. The default can be set using `lattice.options`. `auto.key = TRUE` is equivalent to `auto.key = list()`, in which case `simpleKey` is called with a set of default arguments (which may depend on the relevant high-level function). Most valid components to the `key` argument can be specified in this manner, as `simpleKey` will simply add unrecognized arguments to the list it produces. `auto.key` is typically used to automatically produce a suitable legend in conjunction with a grouping variable. If `auto.key = TRUE`, a suitable legend will be drawn if a `groups` argument is also provided, and not otherwise. In list form, `auto.key` will modify the default legend thus produced. For example, `auto.key=list(columns = 2)` will create a legend split into two columns (`columns` is documented in the entry for `key`). More precisely, if `auto.key` is not `FALSE`, `groups` is non-null, and there is no `key` or `legend` argument specified in the call, a key is created with `simpleKey` with `levels(groups)` as the first (`text`) argument. (Note: this may not work in all high-level functions, but it does work for the ones where grouping makes sense with the default panel function). If `auto.key` is provided as a list and includes a `text` component, then that is used instead as the text labels in the key, and the key is drawn even if `groups` is not specified. Note that `simpleKey` uses the default settings (see `trellis.par.get`) to determine the graphical parameters in the key, so the resulting legend will be meaningful only if the same settings are used in the plot as well. The `par.settings` argument, possibly in conjunction with `simpleTheme`, may be useful to temporarily modify the default settings for this purpose. One disadvantage to using `key` (or even `simpleKey`) directly is that the graphical parameters used in the key are absolutely determined at the time when the `"trellis"` object is created. Consequently, if a plot once created is re-`plot`-ted with different settings, the original parameter settings will be used for the key even though the new settings are used for the actual display. However, with `auto.key`, the key is actually created at plotting time, so the settings will match.
`prepanel`	A function that takes the same arguments as the `panel` function and returns a list, possibly containing components named `xlim`, `ylim`, `dx`, and `dy` (and less frequently, `xat` and `yat`). The return value of a user-supplied prepanel function need not contain all these components; in case some are missing, they are replaced by the component-wise defaults. The `xlim` and `ylim` components are similar to the high level `xlim` and `ylim` arguments (i.e., they are usually a numeric vector of length 2 defining a range, or a character vector representing levels of a factor). If the `xlim` and `ylim` arguments are not explicitly specified (possibly as components in `scales`) in the high-level call, then the actual limits of the panels are guaranteed to include the limits returned by the prepanel function. This happens globally if the `relation` component of `scales` is `"same"`, and on a per-panel basis otherwise. The `dx` and `dy` components are used for banking computations in case `aspect` is specified as `"xy"`. See documentation of `banking` for details. If `xlim` or `ylim` is a character vector (which is appropriate when the corresponding variable is a factor), this implicitly indicates that the scale should include the first `n` integers, where `n` is the length of `xlim` or `ylim`, as the case may be. The elements of the character vector are used as the default labels for these `n` integers. Thus, to make this information consistent between panels, the `xlim` or `ylim` values should represent all the levels of the corresponding factor, even if some are not used within that particular panel. In such cases, an additional component `xat` or `yat` may be returned by the `prepanel` function, which should be a subset of `1:n`, indicating which of the `n` values (levels) are actually represented in the panel. This is useful when calculating the limits with `relation="free"` or `relation="sliced"` in `scales`. The prepanel function is responsible for providing a meaningful return value when the `x`, `y` (etc.) variables are zero-length vectors. When nothing else is appropriate, values of NA should be returned for the `xlim` and `ylim` components.
`strip`	A logical flag or function. If `FALSE`, strips are not drawn. Otherwise, strips are drawn using the `strip` function, which defaults to `strip.default`. See documentation of `strip.default` to see the arguments that are available to the strip function. This description also applies to the `strip.left` argument (see `...` below), which can be used to draw strips on the left of each panel (useful for wide short panels, e.g., in time-series plots).
`xlab`	Character or expression (or a `"grob"`) giving label(s) for the x-axis. Generally defaults to the expression for `x` in the formula defining the plot. Can be specified as `NULL` to omit the label altogether. Finer control is possible, as described in the entry for `main`, with the modification that if the `label` component is omitted from the list, it is replaced by the default `xlab`.
`ylab`	Character or expression (or `"grob"`) giving label for the y-axis. Generally defaults to the expression for `y` in the formula defining the plot. Finer control is possible, see entries for `main` and `xlab`.
`scales`	Generally a list determining how the x- and y-axes (tick marks and labels) are drawn. The list contains parameters in `name=value` form, and may also contain two other lists called `x` and `y` of the same form (described below). Components of `x` and `y` affect the respective axes only, while those in `scales` affect both. When parameters are specified in both lists, the values in `x` or `y` are used. Note that certain high-level functions have defaults that are specific to a particular axis (e.g., `bwplot` has `alternating=FALSE` for the categorical axis only); these can only be overridden by an entry in the corresponding component of `scales`. As a special exception, `scales` (or its `x` and `y` components) can also be a character string, in which case it is interpreted as the `relation` component. The possible components are : `relation` A character string that determines how axis limits are calculated for each panel. Possible values are `"same"` (default), `"free"` and `"sliced"`. For `relation="same"`, the same limits, usually large enough to encompass all the data, are used for all the panels. For `relation="free"`, limits for each panel is determined by just the points in that panel. Behavior for `relation="sliced"` is similar, except that the length (max - min) of the scales are constrained to remain the same across panels. The determination of what axis limits are suitable for each panel can be controlled by the `prepanel` function, which can be overridden by `xlim`, `ylim` or `scales$limits` (except when `relation="sliced"`, in which case explicitly specified limits are ignored with a warning). When `relation` is `"free"`, `xlim` or `ylim` can be a list, in which case it is treated as if its components were the limit values obtained from the prepanel calculations for each panel (after being replicated if necessary). `tick.number` An integer, giving the suggested number of intervals between ticks. This is ignored for a factor, shingle, or character vector, for in these cases there is no natural rule for leaving out some of the labels. But see `xlim`. `draw` A logical flag, defaulting to `TRUE`, that determines whether to draw the axis (i.e., tick marks and labels) at all. `alternating` Usually a logical flag specifying whether axis labels should alternate from one side of the group of panels to the other. For finer control, `alternating` can also be a vector (replicated to be as long as the number of rows or columns per page) consisting of the following numbers 0: do not draw tick labels 1: bottom/left 2: top/right 3: both. `alternating` applies only when `relation="same"`. The default is `TRUE`, or equivalently, `c(1, 2)` `limits` Same as `xlim` and `ylim`. `at` The location of tick marks along the axis (in native coordinates), or a list as long as the number of panels describing tick locations for each panel. `labels` Vector of labels (characters or expressions) to go along with `at`. Can also be a list like `at`. `cex` A numeric multiplier to control character sizes for axis labels. Can be a vector of length 2, to control left/bottom and right/top labels separately. `font`, `fontface`, `fontfamily` Specifies the font to be used for axis labels. `lineheight` Specifies the line height parameter (height of line as a multiple of the size of text); relevant for multi-line labels. (This is currently ignored for `cloud`.) `tck` Usually a numeric scalar controlling the length of tick marks. Can also be a vector of length 2, to control the length of left/bottom and right/top tick marks separately. `col` Color of tick marks and labels. `rot` Angle (in degrees) by which the axis labels are to be rotated. Can be a vector of length 2, to control left/bottom and right/top axes separately. `abbreviate` A logical flag, indicating whether to abbreviate the labels using the `abbreviate` function. Can be useful for long labels (e.g., in factors), especially on the x-axis. `minlength` Argument passed to `abbreviate` if `abbreviate=TRUE`. `log` Controls whether the corresponding variable (`x` or `y`) will be log transformed before being passed to the panel function. Defaults to `FALSE`, in which case the data are not transformed. Other possible values are any number that works as a base for taking logarithm, `TRUE` (which is equivalent to 10), and `"e"` (for the natural logarithm). As a side effect, the corresponding axis is labeled differently. Note that this is in reality a transformation of the data, not the axes. Other than the axis labeling, using this feature is no different than transforming the data in the formula; e.g., `scales=list(x = list(log = 2))` is equivalent to `y ~ log2(x)`. See entry for `equispaced.log` below for details on how to control axis labeling. `equispaced.log` A logical flag indicating whether tick mark locations should be equispaced when ‘log scales’ are in use. Defaults to `TRUE`. Tick marks are always labeled in the original (untransformed) scale, but this makes the choice of tick mark locations nontrivial. If `equispaced.log` is `FALSE`, the choice made is similar to how log scales are annotated in traditional graphics. If `TRUE`, tick mark locations are chosen as ‘pretty’ equispaced values in the transformed scale, and labeled in the form `"base^loc"`, where `base` is the base of the logarithm transformation, and `loc` are the locations in the transformed scale. See also `xscale.components.logpower` in the latticeExtra package. `format` The `format` to use for POSIXct variables. See `strptime` for description of valid values. `axs` A character string, `"r"` (default) or `"i"`. In the latter case, the axis limits are calculated as the exact data range, instead of being padded on either side. (May not always work as expected.) Note that much of the function of `scales` is accomplished by `pscales` in `splom`.
`subscripts`	A logical flag specifying whether or not a vector named `subscripts` should be passed to the panel function. Defaults to `FALSE`, unless `groups` is specified, or if the panel function accepts an argument named `subscripts`. This argument is useful if one wants the subscripts to be passed on even if these conditions do not hold; a typical example is when one wishes to augment a Lattice plot after it has been drawn, e.g., using `panel.identify`.
`subset`	An expression that evaluates to a logical or integer indexing vector. Like `groups`, it is evaluated in `data`. Only the resulting rows of `data` are used for the plot. If `subscripts` is `TRUE`, the subscripts provided to the panel function will be indices referring to the rows of `data` prior to the subsetting. Whether levels of factors in the data frame that are unused after the subsetting will be dropped depends on the `drop.unused.levels` argument.
`xlim`	Normally a numeric vector (or a DateTime object) of length 2 giving left and right limits for the x-axis, or a character vector, expected to denote the levels of `x`. The latter form is interpreted as a range containing c(1, length(xlim)), with the character vector determining labels at tick positions `1:length(xlim)`. `xlim` could also be a list, with as many components as the number of panels (recycled if necessary), with each component as described above. This is meaningful only when `scales$x$relation` is `"free"`, in which case these are treated as if they were the corresponding limit components returned by prepanel calculations.
`ylim`	Similar to `xlim`, applied to the y-axis.
`drop.unused.levels`	A logical flag indicating whether the unused levels of factors will be dropped, usually relevant when a subsetting operation is performed or an `interaction` is created. Unused levels are usually dropped, but it is sometimes appropriate to suppress dropping to preserve a useful layout. For finer control, this argument could also be list containing components `cond` and `data`, both logical, indicating desired behavior for conditioning variables and primary variables respectively. The default is given by `lattice.getOption("drop.unused.levels")`, which is initially set to `TRUE` for both components. Note that this argument does not control dropping of levels of the `groups` argument.
`default.scales`	A list giving the default values of `scales` for a particular high-level function. This is rarely of interest to the end-user, but may be helpful when defining other functions that act as a wrapper to one of the high-level Lattice functions.
`default.prepanel`	A function or character string giving the name of a function that serves as the (component-wise) fallback prepanel function when the `prepanel` argument is not specified, or does not return all necessary components. The main purpose of this argument is to enable the defaults to be overridden through the use of `lattice.options`.
`lattice.options`	A list that could be supplied to `lattice.options`. These options are applied temporarily for the duration of the call, after which the settings revert back to what they were before. The options are retained along with the object and reused during plotting. This enables the user to attach options settings to the trellis object itself rather than change the settings globally. See also the `par.settings` argument described below for a similar treatment of graphical settings.
`...`	Further arguments, usually not directly processed by the high-level functions documented here, but instead passed on to other functions. Such arguments can be broadly categorized into two types: those that affect all high-level Lattice functions in a similar manner, and those that are meant for the specific panel function being used. The first group of arguments are processed by a common, unexported function called `trellis.skeleton`. These arguments affect all high-level functions, but are only documented here (except to override the behaviour described here). All other arguments specified in a high-level call, specifically those neither described here nor in the help page of the relevant high-level function, are passed unchanged to the panel function used. By convention, the default panel function used for any high-level function is named as “`panel.`” followed by the name of the high-level function; for example, the default panel function for `bwplot` is `panel.bwplot`. In practical terms, this means that in addition to the help page of the high-level function being used, the user should also consult the help page of the corresponding panel function for arguments that may be specified in the high-level call. The effect of the first group of common arguments are as follows: `as.table`: A logical flag that controls the order in which panels should be displayed: if `FALSE` (the default), panels are drawn left to right, bottom to top (as in a graph); if `TRUE`, left to right, top to bottom (as in a table). `between`: A list with components `x` and `y` (both usually 0 by default), numeric vectors specifying the space between the panels (units are character heights). `x` and `y` are repeated to account for all panels in a page and any extra components are ignored. The result is used for all pages in a multi page display. In other words, it is not possible to use different `between` values for different pages. `key`: A list that defines a legend to be drawn on the plot. This list is used as an argument to the `draw.key` function, which produces a `"grob"` (grid object) eventually plotted by the print method for `"trellis"` objects. The structure of the legend is constrained in the ways described below. Although such a list can be and often is created explicitly, it is also possible to generate such a list using the `simpleKey` function; the latter is more convenient but less flexible. The `auto.key` argument can be even more convenient for the most common situation where legends are used, namely, in conjunction with a grouping variable. To use more than one legend, or to have arbitrary legends not constrained by the structure imposed by `key`, use the `legend` argument. The position of the key can be controlled in either of two possible ways. If a component called `space` is present, the key is positioned outside the plot region, in one of the four sides, determined by the value of `space`, which can be one of `"top"`, `"bottom"`, `"left"` and `"right"`. Alternatively, the key can be positioned inside the plot region by specifying components `x`, `y` and `corner`. `x` and `y` determine the location of the corner of the key given by `corner`, which is usually one of `c(0,0)`, `c(1,0)`, `c(1,1)` and `c(0,1)`, which denote the corners of the unit square. Fractional values are also allowed, in which case `x` and `y` determine the position of an arbitrary point inside (or outside for values outside the unit interval) the key. `x` and `y` should be numbers between 0 and 1, giving coordinates with respect to the “display area”. Depending on the value of the `"legend.bbox"` option (see `lattice.getOption`), this can be either the full figure region (`"full"`), or just the region that bounds the panels and strips (`"panel"`). The key essentially consists of a number of columns, possibly divided into blocks, each containing some rows. The contents of the key are determined by (possibly repeated) components named `"rectangles"`, `"lines"`, `"points"` or `"text"`. Each of these must be lists with relevant graphical parameters (see later) controlling their appearance. The `key` list itself can contain graphical parameters, these would be used if relevant graphical components are omitted from the other components. The length (number of rows) of each such column (except `"text"`s) is taken to be the largest of the lengths of the graphical components, including the ones specified outside (see the entry for `rep` below for details on this). The `"text"` component must have a character or expression vector as its first component, to be used as labels. The length of this vector determines the number of rows. The graphical components that can be included in `key` and also in the components named `"text"`, `"lines"`, `"points"` and `"rectangles"` (as appropriate) are: `cex=1` (text, lines, points) `col="black"` (text, rectangles, lines, points) `alpha=1` (text, rectangles, lines, points) `fill="transparent"` (lines, points) `lty=1` (lines) `lwd=1` (lines, points) `font=1` (text, points) `fontface` (text, points) `fontfamily` (text, points) `pch=8` (lines, points) `adj=0` (text) `type="l"` (lines) `size=5` (rectangles, lines) `height=1` (rectangles) `lineheight=1` (text) `angle=0` (rectangles, but ignored) `density=-1` (rectangles, but ignored) In addition, the component `border` can be included inside the `"rect"` component to control the border color of the rectangles; when specified at the top level, `border` controls the border of the entire key (see below). `angle` and `density` are unimplemented. `size` determines the width of columns of rectangles and lines in character widths. `type` is relevant for lines; `"l"` denotes a line, `"p"` denotes a point, and `"b"` and `"o"` both denote both together. `height` gives heights of rectangles as a fraction of the default. Other possible components of `key` are: `reverse.rows` Logical flag, defaulting to `FALSE`. If `TRUE`, all components are reversed after being replicated (the details of which may depend on the value of `rep`). This is useful in certain situations, e.g., with a grouped `barchart` with `stack = TRUE` with the categorical variable on the vertical axis, where the bars in the plot will usually be ordered from bottom to top, but the corresponding legend will have the levels from top to bottom unless `reverse.rows = TRUE`. Note that in this case, unless all columns have the same number or rows, they will no longer be aligned. `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 specifying `rep=FALSE`, in which case the length of each column will be determined by components of that column alone. `cex.title` Zoom factor for the title. `lines.title` The amount of vertical space to be occupied by the title in lines (in multiples of itself). Defaults to 2. `padding.text` The amount of space (padding) to be used above and below each row containing text, in multiples of the default, which is currently `0.2 * "lines"`. This padding is in addition to the normal height of any row that contains text, which is the minimum amount necessary to contain all the text entries. `background` Background color for the legend. Defaults to the global background color. `alpha.background` An alpha transparency value between 0 and 1 for the background. `border` Either a color for the border, or a logical flag. In the latter case, the border color is black if `border` is `TRUE`, and no border is drawn if it is `FALSE` (the default). `transparent=FALSE` Logical flag, whether legend should have a transparent background. `just` A character or numeric vector of length one or two giving horizontal and vertical justification for the placement of the legend. See `grid.layout` for more precise details. `columns` The number of column-blocks (drawn side by side) the legend is to be divided into. `between.columns` Space between column blocks, in addition to `between`. `divide` Number of point symbols to divide each line when `type` is `"b"` or `"o"` in `lines`. `legend`: The legend argument can be useful if one wants to place more than one key. It also allows the use of arbitrary `"grob"`s (grid objects) as legends. If used, `legend` must be a list, with an arbitrary number of components. Each component must be named one of `"left"`, `"right"`, `"top"`, `"bottom"`, or `"inside"`. The name `"inside"` can be repeated, but not the others. This name will be used to determine the location for that component, and is similar to the `space` component of `key`. If `key` (or `colorkey` for `levelplot` and `wireframe`) is specified, their `space` component must not conflict with the name of any component of `legend`. Each component of `legend` must have a component called `fun`. This can be a `"grob"`, or a function (or the name of a function) that produces a `"grob"` when called. If this function expects any arguments, they must be supplied as a list in another component called `args`. For components named `"inside"`, there can be additional components called `x`, `y` and `corner`, which work in the same way as for `key`. `page`: A function of one argument (page number) to be called after drawing each page. The function must be ‘grid-compliant’, and is called with the whole display area as the default viewport. `xlab.top`, `ylab.right`: Labels for the x-axis on top, and y-axis on the right. Similar to `xlab` and `ylab`, but less commonly used. `main`: Typically a character string or expression describing the main title to be placed on top of each page. Defaults to `NULL`. `main` (as well as `xlab`, `ylab` and `sub`) is usually a character string or an expression that gets used as the label, but can also be a list that controls further details. Expressions are treated as specification of LaTeX-like markup as described in `plotmath`. The label can be a vector, in which case the components will be spaced out horizontally (or vertically for `ylab`). This feature can be used to provide column or row labels rather than a single axis label. When `main` (etc.) is a list, the actual label should be specified as the `label` component (which may be unnamed if it is the first component). The label can be missing, in which case the default will be used (`xlab` and `ylab` usually have defaults, but `main` and `sub` do not). Further named arguments are passed on to `textGrob`; this can include arguments controlling positioning like `just` and `rot` as well as graphical parameters such as `col` and `font` (see `gpar` for a full list). `main`, `sub`, `xlab`, `ylab`, `xlab.top`, and `ylab.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 for `main` for finer control options. `par.strip.text`: A list of parameters to control the appearance of strip text. Notable components are `col`, `cex`, `font`, and `lines`. The first three control graphical parameters while the last is a means of altering the height of the strips. This can be useful, for example, if the strip labels (derived from factor levels, say) are double height (i.e., contains `"\n"`-s) or if the default height seems too small or too large. Additionally, the `lineheight` component can control the space between multiple lines. The labels can be abbreviated when shown by specifying `abbreviate = TRUE`, in which case the components `minlength` and `dot` (passed along to the `abbreviate` function) can be specified to control the details of how this is done. `layout`: In general, a conditioning plot in Lattice consists of several panels arranged in a rectangular array, possibly spanning multiple pages. `layout` determines this arrangement. `layout` is a numeric vector of length 2 or 3 giving the number of columns, rows, and pages (optional) in a multipanel display. By default, the number of columns is the number of levels of the first conditioning variable and the number of rows is the number of levels of the second conditioning variable. If there is only one conditioning variable, the default layout vector is `c(0,n)`, where `n` is the number of levels of the given vector. Any time the first value in the layout vector is 0, the second value is used as the desired number of panels per page and the actual layout is computed from this, taking into account the aspect ratio of the panels and the device dimensions (via `par("din")`). If `NA` is specified for the number of rows or columns (but not both), that dimension will be filled out according to the number of panels. The number of pages is by default set to as many as is required to plot all the panels, and so rarely needs to be specified. However, in certain situations the default calculation may be incorrect, and in that case the number of pages needs to be specified explicitly. `skip`: A logical vector (default `FALSE`), replicated to be as long as the number of panels (spanning all pages). For elements that are `TRUE`, the corresponding panel position is skipped; i.e., nothing is plotted in that position. The panel that was supposed to be drawn there is now drawn in the next available panel position, and the positions of all the subsequent panels are bumped up accordingly. This may be useful for arranging plots in an informative manner. `strip.left`: `strip.left` can be used to draw strips on the left of each panel, which can be useful for wide short panels, as in time-series (or similar) plots. See the entry for `strip` for detailed usage. `xlab.default`, `ylab.default`: Fallback default for `xlab` and `ylab` when they are not specified. If `NULL`, the defaults are parsed from the Trellis formula. This is rarely useful for the end-user, but can be helpful when developing new Lattice functions. `xscale.components`, `yscale.components`: Functions that determine axis annotation for the x and y axes respectively. See documentation for `xscale.components.default`, the default values of these arguments, to learn more. `axis`: Function responsible for drawing axis annotation. See documentation for `axis.default`, the default value of this argument, to learn more. `perm.cond`: An integer vector, a permutation of `1:n`, where `n` is the number of conditioning variables. By default, the order in which panels are drawn depends on the order of the conditioning variables specified in the formula. `perm.cond` can modify this order. If the trellis display is thought of as an `n`-dimensional array, then during printing, its dimensions are permuted using `perm.cond` as the `perm` argument does in `aperm`. `index.cond`: Whereas `perm.cond` permutes the dimensions of the multidimensional array of panels, `index.cond` can be used to subset (or reorder) margins of that array. `index.cond` can be a list or a function, with behavior in each case described below. The panel display order within each conditioning variable depends on the order of their levels. `index.cond` can be used to choose a ‘subset’ (in the R sense) of these levels, which is then used as the display order for that variable. If `index.cond` is a list, it has to be as long as the number of conditioning variables, and the `i`-th component has to be a valid indexing vector for `levels(g_i)`, where `g_i` is the `i`-th conditioning variable in the plot (note that these levels may not contain all levels of the original variable, depending on the effects of the `subset` and `drop.unused.levels` arguments). In particular, this indexing may repeat levels, or drop some altogether. The result of this indexing determines the order of panels within that conditioning variable. To keep the order of a particular variable unchanged, the corresponding component must be set to `TRUE`. Note that the components of `index.cond` are interpreted in the order of the conditioning variables in the original call, and is not affected by `perm.cond`. Another possibility is to specify `index.cond` as a function. In this case, this function is called once for each panel, potentially with all arguments that are passed to the panel function for that panel. (More specifically, if this function has a `...` argument, then all panel arguments are passed, otherwise, only named arguments that match are passed.) If there is only one conditioning variable, the levels of that variable are then sorted so that these values are in ascending order. For multiple conditioning variables, the order for each variable is determined by first taking the average over all other conditioning variables. Although they can be supplied in high-level function calls directly, it is more typical to use `perm.cond` and `index.cond` to update an existing `"trellis"` object, thus allowing it to be displayed in a different arrangement without re-calculating the data subsets that go into each panel. In the `update.trellis` method, both can be set to `NULL`, which reverts these back to their defaults. `par.settings`: A list that could be supplied to `trellis.par.set`. When the resulting object is plotted, these options are applied temporarily for the duration of the plotting, after which the settings revert back to what they were before. This enables the user to attach some display settings to the trellis object itself rather than change the settings globally. See also the `lattice.options` argument described above for a similar treatment of non-graphical options. `plot.args`: A list containing possible arguments to `plot.trellis`, which will be used by the `plot` or `print` methods when drawing the object, unless overridden explicitly. This enables the user to attach such arguments to the trellis object itself. Partial matching is not performed.

Details

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

The coordinate system used by lattice by default is like a graph, with the origin at the bottom left, with axes increasing to the right and top. In particular, panels are by default drawn starting from the bottom left corner, going right and then up, unless as.table = TRUE, in which case panels are drawn from the top left corner, going right and then down. It is possible to set a global preference for the table-like arrangement by changing the default to as.table=TRUE; this can be done by setting lattice.options(default.args = list(as.table = TRUE)). Default values can be set in this manner for the following arguments: as.table, aspect, between, page, main, sub, par.strip.text, layout, skip and strip. Note that these global defaults are sometimes overridden by individual functions.

The order of the panels depends on the order in which the conditioning variables are specified, with g1 varying fastest, followed by g2, and so on. Within a conditioning variable, the order depends on the order of the levels (which for factors is usually in alphabetical order). Both of these orders can be modified using the index.cond and perm.cond arguments, possibly using the update (and other related) method(s).

Value

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

Note

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

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

Author(s)

Deepayan Sarkar [email protected]

References

Sarkar, Deepayan (2008) Lattice: Multivariate Data Visualization with R, Springer. http://lmdvr.r-forge.r-project.org/

Examples

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")

## 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 = .75, y = .75, corner = c(0.5, 0.5)))

## 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,
       snames = states$state.name,
       panel = function(x, y, subscripts, snames) {
           panel.text(x = x, y = y, labels = snames[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)

Functions to Interact with Lattice Plots

Description

The classic Trellis paradigm is to plot the whole object at once, without the possibility of interacting with it afterwards. However, by keeping track of the grid viewports where the panels and strips are drawn, it is possible to go back to them afterwards and enhance them one panel at a time. These functions provide convenient interfaces to help in this. Note that these are still experimental and the exact details may change in future.

Usage

panel.identify(x, y = NULL,
               subscripts = seq_along(x),
               labels = subscripts, 
               n = length(x), offset = 0.5,
               threshold = 18, ## in points, roughly 0.25 inches
               panel.args = trellis.panelArgs(),
               ...)
panel.identify.qqmath(x, distribution, groups, subscripts, labels,
                      panel.args = trellis.panelArgs(),
                      ...)
panel.identify.cloud(x, y, z, subscripts,
                     perspective, distance, 
                     xlim, ylim, zlim,
                     screen, R.mat, aspect, scales.3d,
                     ...,
                     panel.3d.identify,
                     n = length(subscripts),
                     offset = 0.5,
                     threshold = 18,
                     labels = subscripts,
                     panel.args = trellis.panelArgs())
panel.link.splom(threshold = 18, verbose = getOption("verbose"), ...)
panel.brush.splom(threshold = 18, verbose = getOption("verbose"), ...)


trellis.vpname(name = c("position", "split", "split.location", "toplevel",
                        "figure", "panel", "strip", "strip.left",
                        "legend", "legend.region", "main", "sub",
                        "xlab", "ylab", "xlab.top", "ylab.right", "page"),
               column, row,
               side = c("left", "top", "right", "bottom", "inside"),
               clip.off = FALSE, prefix)
trellis.grobname(name,
                 type = c("", "panel", "strip", "strip.left",
                          "key", "colorkey"),
                 group = 0,
                 which.given = lattice.getStatus("current.which.given",
                                                 prefix = prefix),
                 which.panel = lattice.getStatus("current.which.panel",
                                                 prefix = prefix),
                 column = lattice.getStatus("current.focus.column",
                                            prefix = prefix),
                 row = lattice.getStatus("current.focus.row",
                                         prefix = prefix),
                 prefix = lattice.getStatus("current.prefix"))
trellis.focus(name, column, row, side, clip.off,
              highlight = interactive(), ..., prefix,
              guess = TRUE, verbose = getOption("verbose"))
trellis.switchFocus(name, side, clip.off, highlight, ..., prefix)
trellis.unfocus()
trellis.panelArgs(x, packet.number)

Arguments

`x`, `y`, `z`	variables defining the contents of the panel. In the case of `trellis.panelArgs`, a `"trellis"` object.
`n`	the number of points to identify by default (overridden by a right click)
`subscripts`	an optional vector of integer indices associated with each point. See details below.
`labels`	an optional vector of labels associated with each point. Defaults to `subscripts`
`distribution`, `groups`	typical panel arguments of `panel.qqmath`. These will usually be obtained from `panel.args`
`offset`	the labels are printed either below, above, to the left or to the right of the identified point, depending on the relative location of the mouse click. The `offset` specifies (in "char" units) how far from the identified point the labels should be printed.
`threshold`	threshold in grid's `"points"` units. Points further than these from the mouse click position are not considered
`panel.args`	list that contains components names `x` (and usually `y`), to be used if `x` is missing. Typically, when called after `trellis.focus`, this would appropriately be the arguments passed to that panel.
`perspective`, `distance`, `xlim`, `ylim`, `zlim`, `screen`, `R.mat`, `aspect`, `scales.3d`	arguments as passed to `panel.cloud`. These are required to recompute the relevant three-dimensional projections in `panel.identify.cloud`.
`panel.3d.identify`	the function that is responsible for the actual interaction once the data rescaling and rotation computations have been done. By default, an internal function similar to `panel.identify` is used.
`name`	A character string indicating which viewport or grob we are looking for. Although these do not necessarily provide access to all viewports and grobs created by a lattice plot, they cover most of the ones that end-users may find interesting. `trellis.vpname` and `trellis.focus` deal with viewport names only, and only accept the values explicitly listed above. `trellis.grobname` is meant to create names for grobs, and can currently accept any value. If `name`, as well as `column` and `row` is missing in a call to `trellis.focus`, the user can click inside a panel (or an associated strip) to focus on that panel. Note however that this assumes equal width and height for each panel, and may not work when this is not true. When `name` is `"panel"`, `"strip"`, or `"strip.left"`, `column` and `row` must also be specified. When `name` is `"legend"`, `side` must also be specified.
`column`, `row`	integers, indicating position of the panel or strip that should be assigned focus in the Trellis layout. Rows are usually calculated from the bottom up, unless the plot was created with `as.table=TRUE`
`guess`	logical. If `TRUE`, and the display has only one panel, that panel will be automatically selected by a call to `trellis.focus`.
`side`	character string, relevant only for legends (i.e., when `name="legend"`), indicating their position. Partial specification is allowed, as long as it is unambiguous.
`clip.off`	logical, whether clipping should be off, relevant when `name` is `"panel"` or `"strip"`. This is necessary if axes are to be drawn outside the panel or strip. Note that setting `clip.off=FALSE` does not necessarily mean that clipping is on; that is determined by conditions in effect during printing.
`type`	A character string specifying whether the grob is specific to a particular panel or strip. When `type` is `"panel"`, `"strip"`, or `"strip.left"`, information about the panel is added to the grob name.
`group`	An integer specifying whether the grob is specific to a particular group within the plot. When `group` is greater than zero, information about the group is added to the grob name.
`which.given`, `which.panel`	integers, indicating which conditional variable is being represented (within a strip) and the current levels of the conditional variables. When `which.panel` has length greater than 1, and the `type` is `"strip"` or `"strip.left"`, information about the conditional variable is added to the grob name.
`prefix`	A character string acting as a prefix identifying the plot of a `"trellis"` object, primarily used to distinguish otherwise equivalent viewports in different plots. This only becomes relevant when a particular page is occupied by more than one plot. Defaults to the value appropriate for the last `"trellis"` object printed, as determined by the `prefix` argument in `print.trellis`. Users should not usually need to supply a value for this argument except to interact with an existing plot other than the one plotted last. For `switchFocus`, ignored except when it does not match the prefix of the currently active plot, in which case an error occurs.
`highlight`	logical, whether the viewport being assigned focus should be highlighted. For `trellis.focus`, the default is `TRUE` in interactive mode, and `trellis.switchFocus` by default preserves the setting currently active.
`packet.number`	integer, which panel to get data from. See `packet.number` for details on how this is calculated
`verbose`	whether details will be printed
`...`	For `panel.identify.qqmath`, extra parameters are passed on to `panel.identify`. For `panel.identify`, extra arguments are treated as graphical parameters and are used for labelling. For `trellis.focus` and `trellis.switchFocus`, these are used (in combination with `lattice.options`) for highlighting the chosen viewport if so requested. Graphical parameters can be supplied for `panel.link.splom`.

Details

panel.identify is similar to identify. When called, it waits for the user to identify points (in the panel being drawn) via mouse clicks. Clicks other than left-clicks terminate the procedure. Although it is possible to call it as part of the panel function, it is more typical to use it to identify points after plotting the whole object, in which case a call to trellis.focus first is necessary.

panel.link.splom is meant for use with splom, and requires a panel to be chosen using trellis.focus before it is called. Clicking on a point causes that and the corresponding proections in other pairwise scatter plots to be highlighted. panel.brush.splom is a (misnamed) alias for panel.link.splom, retained for back-compatibility.

panel.identify.qqmath is a specialized wrapper meant for use with the display produced by qqmath. panel.identify.qqmath is a specialized wrapper meant for use with the display produced by cloud. It would be unusual to call them except in a context where default panel function arguments are available through trellis.panelArgs (see below).

One way in which panel.identify etc. are different from identify is in how it uses the subscripts argument. In general, when one identifies points in a panel, one wants to identify the origin in the data frame used to produce the plot, and not within that particular panel. This information is available to the panel function, but only in certain situations. One way to ensure that subscripts is available is to specify subscripts = TRUE in the high level call such as xyplot. If subscripts is not explicitly specified in the call to panel.identify, but is available in panel.args, then those values will be used. Otherwise, they default to seq_along(x). In either case, the final return value will be the subscripts that were marked.

The process of printing (plotting) a Trellis object builds up a grid layout with named viewports which can then be accessed to modify the plot further. While full flexibility can only be obtained by using grid functions directly, a few lattice functions are available for the more common tasks.

trellis.focus can be used to move to a particular panel or strip, identified by its position in the array of panels. It can also be used to focus on the viewport corresponding to one of the labels or a legend, though such usage would be less useful. The exact viewport is determined by the name along with the other arguments, not all of which are relevant for all names. Note that when more than one object is plotted on a page, trellis.focus will always go to the plot that was created last. For more flexibility, use grid functions directly (see note below).

After a successful call to trellis.focus, the desired viewport (typically panel or strip area) will be made the ‘current’ viewport (plotting area), which can then be enhanced by calls to standard lattice panel functions as well as grid functions.

It is quite common to have the layout of panels chosen when a "trellis" object is drawn, and not before then. Information on the layout (specifically, how many rows and columns, and which packet belongs in which position in this layout) is retained for the last "trellis" object plotted, and is available through trellis.currentLayout.

trellis.unfocus unsets the focus, and makes the top level viewport the current viewport.

trellis.switchFocus is a convenience function to switch from one viewport to another, while preserving the current row and column. Although the rows and columns only make sense for panels and strips, they would be preserved even when the user switches to some other viewport (where row/column is irrelevant) and then switches back.

Once a panel or strip is in focus, trellis.panelArgs can be used to retrieve the arguments that were available to the panel function at that position. In this case, it can be called without arguments as

trellis.panelArgs()

This usage is also allowed when a "trellis" object is being printed, e.g. inside the panel functions or the axis function (but not inside the prepanel function). trellis.panelArgs can also retrieve the panel arguments from any "trellis" object. Note that for this usage, one needs to specify the packet.number (as described under the panel entry in xyplot) and not the position in the layout, because a layout determines the panel only after the object has been printed.

It is usually not necessary to call trellis.vpname and trellis.grobname directly. However, they can be useful in generating appropriate names in a portable way when using grid functions to interact with the plots directly, as described in the note below.

Value

panel.identify returns an integer vector containing the subscripts of the identified points (see details above). The equivalent of identify with pos=TRUE is not yet implemented, but can be considered for addition if requested.

trellis.panelArgs returns a named list of arguments that were available to the panel function for the chosen panel.

trellis.vpname and trellis.grobname return character strings.

trellis.focus has a meaningful return value only if it has been used to focus on a panel interactively, in which case the return value is a list with components col and row giving the column and row positions respectively of the chosen panel, unless the choice was cancelled (by a right click), in which case the return value is NULL. If click was outside a panel, both col and row are set to 0.

Note

The viewports created by lattice are accessible to the user through trellis.focus as described above. Functions from the grid package can also be used directly. For example, current.vpTree can be used to inspect the current viewport tree and seekViewport or downViewport can be used to navigate to these viewports. For such usage, trellis.vpname and trellis.grobname provides a portable way to access the appropriate viewports and grobs by name.

Author(s)

Deepayan Sarkar [email protected]. Felix Andrews provided initial implementations of panel.identify.qqmath and support for focusing on panels interctively.

Examples

## Not run: 
xyplot(1:10 ~ 1:10)
trellis.focus("panel", 1, 1)
panel.identify()

## End(Not run)

xyplot(Petal.Length ~ Sepal.Length | Species, iris, layout = c(2, 2))
Sys.sleep(1)

trellis.focus("panel", 1, 1)
do.call("panel.lmline", trellis.panelArgs())
Sys.sleep(0.5)
trellis.unfocus()

trellis.focus("panel", 2, 1)
do.call("panel.lmline", trellis.panelArgs())
Sys.sleep(0.5)
trellis.unfocus()

trellis.focus("panel", 1, 2)
do.call("panel.lmline", trellis.panelArgs())
Sys.sleep(0.5)
trellis.unfocus()


## choosing loess smoothing parameter

p <- xyplot(dist ~ speed, cars)

panel.loessresid <-
    function(x = panel.args$x,
             y = panel.args$y,
             span,
             panel.args = trellis.panelArgs())
{
    fm <- loess(y ~ x, span = span)
    xgrid <- do.breaks(current.panel.limits()$xlim, 50)
    ygrid <- predict(fm, newdata = data.frame(x = xgrid))
    panel.lines(xgrid, ygrid)
    pred <- predict(fm)
    ## center residuals so that they fall inside panel
    resids <- y - pred + mean(y)
    fm.resid <- loess.smooth(x, resids, span = span)
    ##panel.points(x, resids, col = 1, pch = 4)
    panel.lines(fm.resid, col = 1)
}


spans <- c(0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8)
update(p, index.cond = list(rep(1, length(spans))))
panel.locs <- trellis.currentLayout()

i <- 1

for (row in 1:nrow(panel.locs))
    for (column in 1:ncol(panel.locs))
    if (panel.locs[row, column] > 0)
{
    trellis.focus("panel", row = row, column = column,
                  highlight = FALSE)
    panel.loessresid(span = spans[i])
    grid::grid.text(paste("span = ", spans[i]),
                    x = 0.25,
                    y = 0.75,
                    default.units = "npc")
    trellis.unfocus()
    i <- i + 1
}

`x`	an object of class `ts`, which may be multi-variate, i.e. have a matrix structure with multiple columns.
`data`	not used, and must be left as `NULL`.
`...`	additional arguments passed to `xyplot`, which may pass them on to `panel.xyplot`.
`screens`	factor (or coerced to factor) whose levels specify which panel each series is to be plotted in. `screens = c(1, 2, 1)` would plot series 1, 2 and 3 in panels 1, 2 and 1. May also be a named list, see Details below.
`superpose`	overlays all series in one panel (via `screens = 1`) and uses grouped style settings (from `trellis.par.get("superpose.line")`, etc). Note that this is just a convenience argument: its only action is to change the default values of other arguments.
`cut`	defines a cut-and-stack plot. `cut` can be a `list` of arguments to the function `equal.count`, i.e. `number` (number of intervals to divide into) and `overlap` (the fraction of overlap between cuts, default 0.5). If `cut` is numeric this is passed as the `number` argument. `cut = TRUE` tries to choose an appropriate number of cuts (up to a maximum of 6), using `banking`, and assuming a square plot region. This should have the effect of minimising wasted space when `aspect = "xy"`.
`type`, `col`, `lty`, `lwd`, `pch`, `cex`, `fill`	graphical arguments, which are processed and eventually passed to `panel.xyplot`. These arguments can also be vectors or (named) lists, see Details for more information.
`auto.key`	a logical, or a list describing how to draw a key. See the `auto.key` entry in `xyplot`. The default here is to draw lines, not points, and any specified style arguments should show up automatically.
`panel`	the panel function. It is recommended to leave this alone, but one can pass a `panel.groups` argument which is handled by `panel.superpose` for each series.
`par.settings`	style settings beyond the standard `col`, `lty`, `lwd`, etc; see `trellis.par.set` and `simpleTheme`.
`layout`	numeric vector of length 2 specifying number of columns and rows in the plot. The default is to fill columns with up to 6 rows.
`as.table`	to draw panels from top to bottom. The order is determined by the order of columns in `x`.
`xlab`, `ylab`	X axis and Y axis labels; see `xyplot`. Note in particular that `ylab` may be a character vector, in which case the labels are spaced out equally, to correspond to the panels; but NOTE in this case the vector should be reversed OR the argument `as.table` set to `FALSE`.
`default.scales`	`scales` specification. The default is set to have `"free"` Y axis scales unless `cut` is given. Note, users should pass the `scales` argument rather than `default.scales`.

`x`	A `table`, `array` or `matrix` object.
`data`	Should not be specified. If specified, will be ignored with a warning.
`groups`	A logical flag, indicating whether to use the last dimension as a grouping variable in the display.
`origin`, `stack`	Arguments to `panel.barchart`. The defaults for the `table` method are different.
`horizontal`	Logical flag, indicating whether the plot should be horizontal (with the categorical variable on the y-axis) or vertical.
`...`	Other arguments, passed to the underlying `formula` method.

`x`	The object on which method dispatch is carried out. For the `formula` method, `x` can be a formula of the form `~ x \| g1 * g2 * ...`, indicating that histograms or kernel density estimates of the `x` variable should be produced conditioned on the levels of the (optional) variables `g1`, `g2`, .... `x` should be numeric (or possibly a factor in the case of `histogram`), and each of `g1`, `g2`, ... should be either factors or shingles. As a special case, the right hand side of the formula can contain more than one term separated by ‘+’ signs (e.g., `~ x1 + x2 \| g1 * g2`). What happens in this case is described in the documentation for `xyplot`. Note that in either form, all the terms in the formula must have the same length after evaluation. For the `numeric` and `factor` methods, `x` is the variable whose histogram or Kernel density estimate is drawn. Conditioning is not allowed in these cases.
`data`	For the `formula` method, an optional data source (usually a data frame) in which variables are to be evaluated (see `xyplot` for details). `data` should not be specified for the other methods, and is ignored with a warning if it is.
`formula`	The formula to be used for the `"data.frame"` methods. See documentation for argument `x` for details.
`type`	A character string indicating the type of histogram that is to be drawn. `"percent"` and `"count"` give relative frequency and frequency histograms respectively, and can be misleading when breakpoints are not equally spaced. `"density"` produces a density histogram. `type` defaults to `"density"` when the breakpoints are unequally spaced, and when `breaks` is `NULL` or a function, and to `"percent"` otherwise.
`nint`	An integer specifying the number of histogram bins, applicable only when `breaks` is unspecified or `NULL` in the call. Ignored when the variable being plotted is a factor.
`endpoints`	A numeric vector of length 2 indicating the range of x-values that is to be covered by the histogram. This applies only when `breaks` is unspecified and the variable being plotted is not a factor. In `do.breaks`, this specifies the interval that is to be divided up.
`breaks`	Usually a numeric vector of length (number of bins + 1) defining the breakpoints of the bins. Note that when breakpoints are not equally spaced, the only value of `type` that makes sense is density. When `breaks` is unspecified, the value of `lattice.getOption("histogram.breaks")` is first checked. If this value is `NULL`, then the default is to use breaks = seq_len(1 + nlevels(x)) - 0.5 when `x` is a factor, and breaks = do.breaks(endpoints, nint) otherwise. Breakpoints calculated in such a manner are used in all panels. If the retrieved value is not `NULL`, or if `breaks` is explicitly specified, it affects the display in each panel independently. Valid values are those accepted as the `breaks` argument in `hist`. In particular, this allows specification of `breaks` as an integer giving the number of bins (similar to `nint`), as a character string denoting a method, or as a function. When specified explicitly, a special value of `breaks` is `NULL`, in which case the number of bins is determined by `nint` and then breakpoints are chosen according to the value of `equal.widths`.
`equal.widths`	A logical flag, relevant only when `breaks=NULL`. If `TRUE`, equally spaced bins will be selected, otherwise, approximately equal area bins will be selected (typically producing unequally spaced breakpoints).
`n`	Integer, giving the number of points at which the kernel density is to be evaluated. Passed on as an argument to `density`.
`panel`	A function, called once for each panel, that uses the packet (subset of panel variables) corresponding to the panel to create a display. The default panel functions `panel.histogram` and `panel.densityplot` are documented separately, and have arguments that can be used to customize its output in various ways. Such arguments can usually be directly supplied to the high-level function.
`allow.multiple`, `outer`	See `xyplot`.
`auto.key`	See `xyplot`.
`aspect`	See `xyplot`.
`prepanel`	See `xyplot`.
`scales`	See `xyplot`.
`strip`	See `xyplot`.
`groups`	See `xyplot`. Note that the default panel function for `histogram` does not support grouped displays, whereas the one for `densityplot` does.
`xlab`, `ylab`	See `xyplot`.
`xlim`, `ylim`	See `xyplot`.
`drop.unused.levels`	See `xyplot`.
`lattice.options`	See `xyplot`.
`default.scales`	See `xyplot`.
`subscripts`	See `xyplot`.
`subset`	See `xyplot`.
`default.prepanel`	Fallback prepanel function. See `xyplot`.
`weights`	numeric vector of weights for the density calculations, evaluated in the non-standard manner used for `groups` and terms in the formula, if any. If this is specified, it is subsetted using `subscripts` inside the panel function to match it to the corresponding `x` values. At the time of writing, `weights` do not work in conjunction with an extended formula specification (this is not too hard to fix, so just bug the maintainer if you need this feature).
`bw`, `adjust`, `width`	Arguments controlling bandwidth. Passed on as arguments to `density`.
`kernel`, `window`	The choice of kernel. Passed on as arguments to `density`.
`give.Rkern`	Logical flag, passed on as argument to `density`. This argument is made available only for ease of implementation, and will produce an error if `TRUE`.
`from`, `to`, `cut`	Controls range over which density is evaluated. Passed on as arguments to `density`.
`na.rm`	Logical flag specifying whether `NA` values should be ignored. Passed on as argument to `density`, but unlike in `density`, the default is `TRUE`.
`...`	Further arguments. See corresponding entry in `xyplot` for non-trivial details.

`x`	The object on which method dispatch is carried out. For the `"formula"` method, `x` should be a formula of the form `~ x \| g1 * g2 * ...`, where `x` should be a numeric variable. For the `"numeric"` method, `x` should be a numeric vector.
`data`	For the `formula` method, an optional data source (usually a data frame) in which variables are to be evaluated (see `xyplot` for details). `data` should not be specified for the other methods, and is ignored with a warning if it is.
`formula`	The formula to be used for the `"data.frame"` methods. See documentation for argument `x` for details.
`distribution`	A quantile function that takes a vector of probabilities as argument and produces the corresponding quantiles from a theoretical distribution. Possible values are `qnorm`, `qunif`, etc. Distributions with other required arguments need to be provided as user-defined functions (see example with `qt`).
`f.value`	An optional numeric vector of probabilities, quantiles corresponding to which should be plotted. This can also be a function of a single integer (representing sample size) that returns such a numeric vector. A typical value for this argument is the function `ppoints`, which is also the S-PLUS default. If specified, the probabilities generated by this function is used for the plotted quantiles, through the `quantile` function for the sample, and the function specified as the `distribution` argument for the theoretical distribution. `f.value` defaults to `NULL`, which has the effect of using `ppoints` for the quantiles of the theoretical distribution, but the exact data values for the sample. This is similar to what happens for `qqnorm`, but different from the S-PLUS default of `f.value=ppoints`. For large `x`, this argument can be used to restrict the number of points plotted. See also the `tails.n` argument in `panel.qqmath`.
`panel`	A function, called once for each panel, that uses the packet (subset of panel variables) corresponding to the panel to create a display. The default panel function `panel.qqmath` is documented separately, and has arguments that can be used to customize its output in various ways. Such arguments can usually be directly supplied to the high-level function.
`allow.multiple`, `outer`	See `xyplot`.
`auto.key`	See `xyplot`.
`aspect`	See `xyplot`.
`prepanel`	See `xyplot`.
`scales`	See `xyplot`.
`strip`	See `xyplot`.
`groups`	See `xyplot`.
`xlab`, `ylab`	See `xyplot`.
`xlim`, `ylim`	See `xyplot`.
`drop.unused.levels`	See `xyplot`.
`lattice.options`	See `xyplot`.
`default.scales`	See `xyplot`.
`subscripts`	See `xyplot`.
`subset`	See `xyplot`.
`default.prepanel`	Fallback prepanel function. See `xyplot`.
`...`	Further arguments. See corresponding entry in `xyplot` for non-trivial details.

`x`	The object on which method dispatch is carried out. For the `"formula"` method, `x` should be a formula of the form `y ~ x \| g1 * g2 * ...`, where `x` should be a numeric variable, and `y` a factor, shingle, character, or numeric variable, with the restriction that there must be exactly two levels of `y`, which divide the values of `x` into two groups. Quantiles for these groups will be plotted against each other along the two axes.
`data`	For the `formula` method, an optional data source (usually a data frame) in which variables are to be evaluated (see `xyplot` for details).
`formula`	The formula to be used for the `"data.frame"` method. See documentation for argument `x` for details.
`f.value`	An optional numeric vector of probabilities, quantiles corresponding to which should be plotted. This can also be a function of a single integer (representing sample size) that returns such a numeric vector. A typical value for this argument is the function `ppoints`, which is also the S-PLUS default. If specified, the probabilities generated by this function is used for the plotted quantiles, through the `quantile` function. `f.value` defaults to `NULL`, which is equivalent to f.value = function(n) ppoints(n, a = 1) This has the effect of including the minimum and maximum data values in the computed quantiles. This is similar to what happens for `qqplot` but different from the default behaviour of `qq` in S-PLUS. For large `x`, this argument can be used to restrict the number of quantiles plotted.
`panel`	A function, called once for each panel, that uses the packet (subset of panel variables) corresponding to the panel to create a display. The default panel function `panel.qq` is documented separately, and has arguments that can be used to customize its output in various ways. Such arguments can usually be directly supplied to the high-level function.
`qtype`	The `type` argument for `quantile`.
`aspect`	See `xyplot`.
`prepanel`	See `xyplot`.
`scales`	See `xyplot`.
`strip`	See `xyplot`.
`groups`	See `xyplot`.
`xlab`, `ylab`	See `xyplot`.
`xlim`, `ylim`	See `xyplot`.
`drop.unused.levels`	See `xyplot`.
`lattice.options`	See `xyplot`.
`default.scales`	See `xyplot`.
`subscripts`	See `xyplot`.
`subset`	See `xyplot`.
`default.prepanel`	Fallback prepanel function. See `xyplot`.
`...`	Further arguments. See corresponding entry in `xyplot` for non-trivial details.

`x`	for the `formula` method, a formula of the form `z ~ x * y \| g1 * g2 * ...`, where `z` is a numeric response, and `x`, `y` are numeric values evaluated on a rectangular grid. `g1, g2, ...` are optional conditional variables, and must be either factors or shingles if present. Calculations are based on the assumption that all x and y values are evaluated on a grid (defined by their unique values). The function will not return an error if this is not true, but the display might not be meaningful. However, the x and y values need not be equally spaced. Both `levelplot` and `wireframe` have methods for `matrix`, `array`, and `table` objects, in which case `x` provides the `z` vector described above, while its rows and columns are interpreted as the `x` and `y` vectors respectively. This is similar to the form used in `filled.contour` and `image`. For higher-dimensional arrays and tables, further dimensions are used as conditioning variables. Note that the dimnames may be duplicated; this is handled by calling `make.unique` to make the names unique (although the original labels are used for the x- and y-axes).
`data`	For the `formula` methods, an optional data frame in which variables in the formula (as well as `groups` and `subset`, if any) are to be evaluated. Usually ignored with a warning in other cases.
`formula`	The formula to be used for the `"data.frame"` methods. See documentation for argument `x` for details.
`row.values`, `column.values`	Optional vectors of values that define the grid when `x` is a matrix. `row.values` and `column.values` must have the same lengths as `nrow(x)` and `ncol(x)` respectively. By default, row and column numbers.
`panel`	panel function used to create the display, as described in `xyplot`
`aspect`	For the `matrix` methods, the default aspect ratio is chosen to make each cell square. The usual default is `aspect="fill"`, as described in `xyplot`.
`at`	A numeric vector giving breakpoints along the range of `z`. Contours (if any) will be drawn at these heights, and the regions in between would be colored using `col.regions`. In the latter case, values outside the range of `at` will not be drawn at all. This serves as a way to limit the range of the data shown, similar to what a `zlim` argument might have been used for. However, this also means that when supplying `at` explicitly, one has to be careful to include values outside the range of `z` to ensure that all the data are shown. `at` can have length one only if `region=FALSE`.
`col.regions`	color vector to be used if regions is TRUE. The general idea is that this should be a color vector of moderately large length (longer than the number of regions. By default this is 100). It is expected that this vector would be gradually varying in color (so that nearby colors would be similar). When the colors are actually chosen, they are chosen to be equally spaced along this vector. When there are more regions than colors in `col.regions`, the colors are recycled. The actual color assignment is performed by `level.colors`, which is documented separately.
`alpha.regions`	Numeric, specifying alpha transparency (works only on some devices)
`colorkey`	A logical flag specifying whether a colorkey is to be drawn alongside the plot, or a list describing the colorkey. The list may contain the following components: `space`: location of the colorkey, can be one of `"left"`, `"right"`, `"top"` and `"bottom"`. Defaults to `"right"`. `x`, `y`: location, currently unused `col`: A color ramp specification, as in the `col.regions` argument in `level.colors` `at`: A numeric vector specifying where the colors change. must be of length 1 more than the col vector. `tri.lower`, `tri.upper`: Logical or numeric controlling whether the first and last intervals should be triangular instead of rectangular. With the default value (`NA`), this happens only if the corresponding extreme `at` values are `-Inf` or `Inf` respectively, and the triangles occupy 5% of the total length of the color key. If numeric and between 0 and 0.25, these give the corresponding fraction, which is again 5% when specified as `TRUE`. `labels`: A character vector for labelling the `at` values, or more commonly, a list describing characteristics of the labels. This list may include components `labels`, `at`, `cex`, `col`, `rot`, `font`, `fontface` and `fontfamily`. `title`: Usually a character vector or expression providing a title for the colorkey, or a list controlling the title in further detail, or an arbitrary `"grob"`. For details of how the list form is interpreted, see the entry for `main` in `xyplot`; generally speaking, the actual label should be specified as the `label` component (which may be unnamed if it is the first component), and the remaining arguments are used as appropriate in a call to `textGrob`. Further control of the placement of the title is possible through the component `title.control`. In particular, if a `rot` component is not specified, its default depends on the value of `title.control$side` (0 for top or bottom, and 90 for left or right). `title` defaults to `NULL`, which means no title is drawn. `title.control`: A list providing control over the placement of a title, if specified. Currently two components are honoured: `side` can take values `"top"`, `"bottom"`, `"left"`, and `"right"`, and specifies the side of the colorkey on which the title is to be placed. Defaults to the value of the `"space"` component. `padding` is a multiplier for the default amount of padding between the title and the colorkey. `tick.number`: The approximate number of ticks desired. `tck`: A (scalar) multipler for tick lengths. `corner`: Interacts with x, y; currently unimplemented `width`: The width of the key `height`: The length of key as a fraction of the appropriate side of plot. `raster`: A logical flag indicating whether the colorkey should be rendered as a raster image using `grid.raster`. See also `panel.levelplot.raster`. `interpolate`: Logical flag, passed to `rasterGrob` when `raster=TRUE`. `axis.line`: A list giving graphical parameters for the color key boundary and tick marks. Defaults to `trellis.par.get("axis.line")`. `axis.text`: A list giving graphical parameters for the tick mark labels on the color key. Defaults to `trellis.par.get("axis.text")`.
`contour`	A logical flag, indicating whether to draw contour lines.
`cuts`	The number of levels the range of `z` would be divided into.
`labels`	Typically a logical indicating whether contour lines should be labelled, but other possibilities for more sophisticated control exists. Details are documented in the help page for `panel.levelplot`, to which this argument is passed on unchanged. That help page also documents the `label.style` argument, which affects how the labels are rendered.
`pretty`	A logical flag, indicating whether to use pretty cut locations and labels.
`region`	A logical flag, indicating whether regions between contour lines should be filled as in a level plot.
`allow.multiple`, `outer`, `prepanel`, `scales`, `strip`, `groups`, `xlab`, `xlim`, `ylab`, `ylim`, `drop.unused.levels`, `lattice.options`, `default.scales`, `subset`	These arguments are described in the help page for `xyplot`.
`default.prepanel`	Fallback prepanel function. See `xyplot`.
`...`	Further arguments may be supplied. Some are processed by `levelplot` or `contourplot`, and those that are unrecognized are passed on to the panel function.
`useRaster`	A logical flag indicating whether raster representations should be used, both for the false color image and the color key (if present). Effectively, setting this to `TRUE` changes the default panel function from `panel.levelplot` to `panel.levelplot.raster`, and sets the default value of `colorkey$raster` to `TRUE`. Note that `panel.levelplot.raster` provides only a subset of the features of `panel.levelplot`, but setting `useRaster=TRUE` will not check whether any of the additional features have been requested. Not all devices support raster images. For devices that appear to lack support, `useRaster=TRUE` will be ignored with a warning.

`x`	The object on which method dispatch is carried out. For the `"formula"` methods, a formula of the form `z ~ x * y \| g1 * g2 * ...`, where `z` is a numeric response, and `x`, `y` are numeric values. `g1, g2, ...`, if present, are conditioning variables used for conditioning, and must be either factors or shingles. In the case of `wireframe`, calculations are based on the assumption that the `x` and `y` values are evaluated on a rectangular grid defined by their unique values. The grid points need not be equally spaced. For `wireframe`, `x`, `y` and `z` may also be matrices (of the same dimension), in which case they are taken to represent a 3-D surface parametrized on a 2-D grid (e.g., a sphere). Conditioning is not possible with this feature. See details below. Missing values are allowed, either as `NA` values in the `z` vector, or missing rows in the data frame (note however that in that case the X and Y grids will be determined only by the available values). For a grouped display (producing multiple surfaces), missing rows are not allowed, but `NA`-s in `z` are. Both `wireframe` and `cloud` have methods for `matrix` objects, in which case `x` provides the `z` vector described above, while its rows and columns are interpreted as the `x` and `y` vectors respectively. This is similar to the form used in `persp`.
`data`	For the `"formula"` methods, an optional data frame in which variables in the formula (as well as `groups` and `subset`, if any) are to be evaluated. `data` should not be specified except when using the `"formula"` method.
`formula`	The formula to be used for the `"data.frame"` methods. See documentation for argument `x` for details.
`row.values`, `column.values`	Optional vectors of values that define the grid when `x` is a matrix. `row.values` and `column.values` must have the same lengths as `nrow(x)` and `ncol(x)` respectively. By default, row and column numbers.
`allow.multiple`, `outer`, `auto.key`, `prepanel`, `strip`, `groups`, `xlab`, `xlim`, `ylab`, `ylim`, `drop.unused.levels`, `lattice.options`, `default.scales`, `subset`	These arguments are documented in the help page for `xyplot`. For the `cloud.table` method, `groups` must be a logical indicating whether the last dimension should be used as a grouping variable as opposed to a conditioning variable. This is only relevant if the table has more than 2 dimensions.
`type`	type of display in `cloud` (see `panel.3dscatter` for details). Defaults to `"h"` for the `matrix` method.
`aspect`, `panel.aspect`	Unlike other high level functions, `aspect` is taken to be a numeric vector of length 2, giving the relative aspects of the y-size/x-size and z-size/x-size of the enclosing cube. The usual role of the `aspect` argument in determining the aspect ratio of the panel (see `xyplot` for details) is played by `panel.aspect`, except that it can only be a numeric value. For the `matrix` methods, the default y/x aspect is `ncol(x) / nrow(x)` and the z/x aspect is the smaller of the y/x aspect and 1.
`panel`	panel function used to create the display. See `panel.cloud` for (non-trivial) details.
`default.prepanel`	Fallback prepanel function. See `xyplot`.
`scales`	a list describing the scales. As with other high level functions (see `xyplot` for details), this list can contain parameters in name=value form. It can also contain components with the special names `x`, `y` and `z`, which can be similar lists with axis-specific values overriding the ones specified in `scales`. The most common use for this argument is to set `arrows=FALSE`, which causes tick marks and labels to be used instead of arrows being drawn (the default). Both can be suppressed by `draw=FALSE`. Another special component is `distance`, which specifies the relative distance of the axis label from the bounding box. If specified as a component of `scales` (as opposed to one of `scales$z` etc), this can be (and is recycled if not) a vector of length 3, specifying distances for the x, y and z labels respectively. Other components that work in the `scales` argument of `xyplot` etc. should also work here (as long as they make sense), including explicit specification of tick mark locations and labels. (Not everything is implemented yet, but if you find something that should work but does not, feel free to bug the maintainer.) Note, however, that for these functions `scales` cannot contain information that is specific to particular panels. If you really need that, consider using the `scales.3d` argument of `panel.cloud`.
`axs.default`	Unlike 2-D display functions, `cloud` does not expand the bounding box to slightly beyound the range of the data, even though it should. This is primarily because this is the natural behaviour in `wireframe`, which uses the same code. `axs.default` is intended to provide a different default for `cloud`. However, this feature has not yet been implemented.
`zlab`	Specifies a label describing the z variable in ways similar to `xlab` and `ylab` (i.e. “grob”, character string, expression or list) in other high level functions. Additionally, if `zlab` (and `xlab` and `ylab`) is a list, it can contain a component called `rot`, controlling the rotation for the label
`zlim`	limits for the z-axis. Similar to `xlim` and `ylim` in other high level functions
`drape`	logical, whether the wireframe is to be draped in color. If `TRUE`, the height of a facet is used to determine its color in a manner similar to the coloring scheme used in `levelplot`. Otherwise, the background color is used to color the facets. This argument is ignored if `shade = TRUE` (see `panel.3dwire`).
`at`, `col.regions`, `alpha.regions`	these arguments are analogous to those in `levelplot`. if `drape=TRUE`, `at` gives the vector of cutpoints where the colors change, and `col.regions` the vector of colors to be used in that case. `alpha.regions` determines the alpha-transparency on supporting devices. These are passed down to the panel function, and also used in the colorkey if appropriate. The default for `col.regions` and `alpha.regions` is derived from the Trellis setting `"regions"`
`cuts`	if `at` is unspecified, the approximate number of cutpoints if `drape=TRUE`
`pretty`	whether automatic choice of cutpoints should be prettfied
`colorkey`	logical indicating whether a color key should be drawn alongside, or a list describing such a key. See `levelplot` for details.
`...`	Any number of other arguments can be specified, and are passed to the panel function. In particular, the arguments `distance`, `perspective`, `screen` and `R.mat` are very important in determining the 3-D display. The argument `shade` can be useful for `wireframe` calls, and controls shading of the rendered surface. These arguments are described in detail in the help page for `panel.cloud`. Additionally, an argument called `zoom` may be specified, which should be a numeric scalar to be interpreted as a scale factor by which the projection is magnified. This can be useful to get the variable names into the plot. This argument is actually only used by the default prepanel function.

`object`	An object of class `"trellis"` returned by `xyplot`, `qq` or `qqmath`.
`xlab`	x label
`ylab`	y label
`panel`	panel function to be used. See details below.
`prepanel`	prepanel function. See details below.
`f.value`, `distribution`, `qtype`	see `panel.qqmath`.
`groups`, `subscripts`	see `xyplot`.
`x`, `y`	data as passed to panel functions in original call.
`...`	other arguments
`identifier`	A character string that is prepended to the names of grobs that are created by this panel function.

`model`	a fitted model object with methods `fitted.values` and `residuals`. Can be the value returned by `oneway`
`layout`	default layout is c(2,1)
`xlab`	defaults to `"f.value"`
`distribution`	the distribution function to be used for `qqmath`
`ylab`, `panel`, `prepanel`, `strip`	See `xyplot`
`...`	other arguments, passed on to `qqmath`.

`formula`	formula of the form `y ~ x` where `y` is the numeric response and `x` is the grouping factor
`data`	data frame in which the model is to be evaluated
`location`	function or numeric giving the location statistic to be used for centering the observations, e.g. `median`, 0 (to avoid centering).
`spread`	function or numeric giving the spread statistic to be used for scaling the observations, e.g. `sd`, 1 (to avoid scaling).

`device`	function (or the name of one as a character string) that starts a device. Admissible values depend on the platform and how R was compiled (see `Devices`), but usually `"pdf"`, `"postscript"`, `"png"`, `"jpeg"` and at least one of `"X11"`, `"windows"` and `"quartz"` will be available.
`color`	logical, whether the initial settings should be color or black and white. Defaults to `FALSE` for postscript devices, `TRUE` otherwise. Note that this only applies to the initial choice of colors, which can be overridden using `theme` or subsequent calls to `trellis.par.set` (and by arguments supplied directly in high level calls for some settings).
`theme`	list of components that changes the settings of the device opened, or, a function that when called produces such a list. The function name can be supplied as a quoted string. These settings are only used to modify the default settings (determined by other arguments), and need not contain all possible parameters. A possible use of this argument is to change the default settings by specifying `lattice.options(default.theme = "col.whitebg")`. For back-compatibility, this is initially (when lattice is loaded) set to `getOption(lattice.theme)`. If `theme` is a function, it will not be supplied any arguments, however, it is guaranteed that a device will already be open when it is called, so one may use `.Device` inside the function to ascertain what device has been opened.
`new`	logical flag indicating whether a new device should be started. If `FALSE`, the options for the current device are changed to the defaults determined by the other arguments.
`retain`	logical. If `TRUE` and a setting for this device already exists, then that is used instead of the defaults for this device. By default, pre-existing settings are overwritten (and lost).
`name`	name of the device for which the setting is required, as returned by `.Device`
`...`	additional parameters to be passed to the `device` function, most commonly `file` for non-screen devices, as well as `height`, `width`, etc. See the help file for individual devices for admissible arguments.

`name`	character string giving the name of the device for which the setting is required, as returned by `.Device`. This is only used by `classic.theme` to allow device-specific setting. It is retained in `standard.theme` for back-compatibilty, but its use is not recommended.
`color`	logical, whether the initial settings should be color or black and white.
`symbol`	vector of colors to be used for symbols and lines.
`fill`	vector of colors to be used as fill colors, e.g., in bar charts and histograms. The default of `NULL` in `standard.theme` results in lightened versions of the symbol colors to be used.
`region`	vector of colors to be used to create a color ramp, typically used by `levelplot`
`reference`	color, to be used for reference lines.
`fg`	color, to be used for foreground elements such as axes and labels.
`bg`	color, to be used as background.
`strip.bg`	color, to be used as strip background.
`strip.fg`	color, to be used as strip foreground.
`...`	additional arguments, passed on to other functions as appropriate. In particular, additional arguments provided to `standard.theme` will be passed on to `custom_theme`, and these may include non-color parameters that will be used to modify the resulting theme via `simpleTheme`.

`name`	A character string giving the name of a component. If unspecified in `trellis.par.get()`, the return value is a named list containing all the current settings (this can be used to get the valid values for `name`).
`value`	a list giving the desired value of the component. Components that are already defined as part of the current settings but are not mentioned in `value` will remain unchanged.
`theme`	a list decribing how to change the settings, similar to what is returned by `trellis.par.get()`. This is purely for convenience, allowing multiple calls to `trellis.par.set` to be condensed into one. The name of each component must be a valid `name` as described above, with the corresponding value a valid `value` as described above. As in `trellis.device`, `theme` can also be a function that produces such a list when called. The function name can be supplied as a quoted string.
`...`	Multiple settings can be specified in `name = value` form. Equivalent to calling with `theme = list(...)`
`warn`	A logical flag, indicating whether a warning should be issued when `trellis.par.get` is called when no graphics device is open.
`strict`	Usually a logical flag, indicating whether the `value` should be interpreted strictly. Usually, assignment of value to the corresponding named component is fuzzy in the sense that sub-components that are absent from `value` but not currently `NULL` are retained. By specifying `strict = TRUE`, such values will be removed. An even stricter interpretation is allowed by specifying `strict` as a numeric value larger than `1`. In that case, top-level components not specified in the call will also be removed. This is primarily for internal use.
`x`	optional list of components that change the settings (any valid value of `theme`). These are used to modify the current settings (obtained by `trellis.par.get`) before they are displayed.

`col`, `col.points`, `col.line`	A color specification. `col` is used for components `"plot.symbol"`, `"plot.line"`, `"plot.polygon"`, `"superpose.symbol"`, `"superpose.line"`, and `"superpose.polygon"`. `col.points` overrides `col`, but is used only for `"plot.symbol"` and `"superpose.symbol"`. Similarly, `col.line` overrides `col` for `"plot.line"` and `"superpose.line"`. The arguments can be vectors, but only the first component is used for scalar targets (i.e., the ones without `"superpose"` in their name).
`alpha`, `alpha.points`, `alpha.line`	A numeric alpha transparency specification. The same rules as `col`, etc., apply.
`cex`, `pch`, `font`	Parameters for points. Applicable for components `plot.symbol` (for which only the first component is used) and `superpose.symbol` (for which the arguments can be vectors).
`lty`, `lwd`	Parameters for lines. Applicable for components `plot.line` (for which only the first component is used) and `superpose.line` (for which the arguments can be vectors).
`fill`	fill color, applicable for components `plot.symbol`, `plot.polygon`, `superpose.symbol`, and `superpose.polygon`.
`border`	border color, applicable for components `plot.polygon` and `superpose.polygon`.

`name`	character giving the name of a setting
`...`	new options can be defined, or existing ones modified, using one or more arguments of the form `name = value` or by passing a list of such tagged values. Existing values can be retrieved by supplying the names (as character strings) of the components as unnamed arguments.

`x`, `object`	an object of class `"trellis"`
`position`	a vector of 4 numbers, typically c(xmin, ymin, xmax, ymax) that give the lower-left and upper-right corners of a rectangle in which the Trellis plot of x is to be positioned. The coordinate system for this rectangle is [0-1] in both the x and y directions.
`split`	a vector of 4 integers, c(x,y,nx,ny) , that says to position the current plot at the x,y position in a regular array of nx by ny plots. (Note: this has origin at top left)
`more`	A logical specifying whether more plots will follow on this page.
`newpage`	A logical specifying whether the plot should be on a new page. This option is specific to lattice, and is useful for including lattice plots in an arbitrary grid viewport (see the details section).
`packet.panel`	a function that determines which packet (data subset) is plotted in which panel. Panels are always drawn in an order such that columns vary the fastest, then rows and then pages. This function determines, given the column, row and page and other relevant information, the packet (if any) which should be used in that panel. By default, the association is determnined by matching panel order with packet order, which is determined by varying the first conditioning variable the fastest, then the second, and so on. This association rule is encoded in the default, namely the function `packet.panel.default`, whose help page details the arguments supplied to whichever function is specified as the `packet.panel` argument.
`draw.in`	An optional (grid) viewport (used as the `name` argument in `downViewport`) in which the plot is to be drawn. If specified, the `newpage` argument is ignored. This feature is not well-tested.
`panel.width`, `panel.height`	lists with 2 components, that should be valid `x` and `units` arguments to `unit()` (the `data` argument cannot be specified currently, but can be considered for addition if needed). The resulting `unit` object will be the width/height of each panel in the Lattice plot. These arguments can be used to explicitly control the dimensions of the panel, rather than letting them expand to maximize available space. Vector widths are allowed, and can specify unequal lengths across rows or columns. Note that this option should not be used in conjunction with non-default values of the `aspect` argument in the original high level call (no error will be produced, but the resulting behaviour is undefined).
`save.object`	logical, specifying whether the object being printed is to be saved. The last object thus saved can be subsequently retrieved. This is an experimental feature that should allow access to a panel's data after the plot is done, making it possible to enhance the plot after the fact. This also allows the user to invoke the `update` method on the current plot, even if it was not assigned to a variable explicitly. For more details, see `trellis.focus`.
`panel.error`	a function, or a character string naming a function, that is to be executed when an error occurs during the execution of the panel function. The error is caught (using `tryCatch`) and supplied as the only argument to `panel.error`. The default behaviour (implemented as the `panel.error` function) is to print the corresponding error message in the panel and continue. To stop execution on error, use `panel.error = stop`. Normal error recovery and debugging tools are unhelpful when `tryCatch` is used. `tryCatch` can be completely bypassed by setting `panel.error` to NULL.
`prefix`	A character string acting as a prefix identifying the plot of a `"trellis"` object, primarily used in constructing viewport and grob names, to distinguish similar viewports if a page contains multiple plots. The default is based on the serial number of the current plot on the current page (specifically, `"plot_01"`, `"plot_02"`, etc.). If supplied explicitly, this must be a valid R symbol name (briefly, it must start with a letter or a period followed by a letter) and must not contain the grid path separator (currently `"::"`).
`e`	an error condition caught by `tryCatch`
`...`	extra arguments, ignored by the `print` method. All arguments to the `plot` method are passed on to the `print` method.

`object`, `x`	The object to be updated, of class `"trellis"`.
`i`, `j`	indices to be used. Names are not currently allowed.
`drop`	logical, whether dimensions with only one level are to be dropped. Currently ignored, behaves as if it were `FALSE`.
`panel`, `aspect`, `as.table`, `between`, `key`, `auto.key`, `legend`, `layout`, `main`, `page`, `par.strip.text`, `prepanel`, `scales`, `skip`, `strip`, `strip.left`, `sub`, `xlab`, `ylab`, `xlab.top`, `ylab.right`, `xlim`, `ylim`, `xscale.components`, `yscale.components`, `axis`, `par.settings`, `plot.args`, `lattice.options`, `index.cond`, `perm.cond`, `...`	arguments that will be used to update `object`. See details below.
`prefix`	A character string acting as a prefix identifying the plot of a `"trellis"` object. Only relevant when a particular page is occupied by more than one plot. Defaults to the value appropriate for the last `"trellis"` object printed. See `trellis.focus`.

`x`	numeric variable or R object, shingle in `plot.shingle` and `x[]`. An object (list of intervals) of class "shingleLevel" in `print.shingleLevel`
`object`	shingle object to be summarized
`showValues`	logical, whether to print the numeric part. If FALSE, only the intervals are printed
`intervals`	numeric vector or matrix with 2 columns
`subset`	logical vector
`drop`	whether redundant shingle levels are to be dropped
`panel`, `xlab`, `ylab`	standard Trellis arguments (see `xyplot` )
`...`	other arguments, passed down as appropriate. For example, extra arguments to `equal.count` are passed on to `co.intervals`. graphical parameters can be passed as arguments to the `plot` method.

`key`	A list determining the key. See documentation for `levelplot`, in particular the section describing the `colorkey` argument, for details.
`draw`	A scalar logical, indicating whether the grob is to be drawn.
`vp`	The viewport in which to draw the grob, if applicable.

`x`	A numeric or `factor` variable.
`at`	A numeric variable of breakpoints defining intervals along the range of `x`.
`col.regions`	A specification of the colors to be assigned to each interval defined by `at`. This could be either a vector of colors, or a function that produces a vector of colors when called with a single argument giving the number of colors. See details below.
`colors`	logical indicating whether colors should be computed and returned. If `FALSE`, only the indices representing which interval (among those defined by `at`) each value in `x` falls into is returned.
`...`	Extra arguments, ignored.

`text`	character or expression vector, to be used as labels for levels of the grouping variable
`points`	logical
`rectangles`	logical
`lines`	logical
`col`, `cex`, `alpha`, `font`, `fontface`, `fontfamily`, `lineheight`	Used as top-level components of the list produced, to be used for the text labels. Defaults to the values in `trellis.par.get("add.text")`
`...`	further arguments added to the list, eventually passed to `draw.key`

`which.given`	integer index specifying which of the conditioning variables this strip corresponds to.
`which.panel`	vector of integers as long as the number of conditioning variables. The contents are indices specifying the current levels of each of the conditioning variables (thus, this would be unique for each distinct packet). This is identical to the return value of `which.packet`, which is a more accurate name.
`var.name`	vector of character strings or expressions as long as the number of conditioning variables. The contents are interpreted as names for the conditioning variables. Whether they are shown on the strip depends on the values of `strip.names` and `style` (see below). By default, the names are shown for shingles, but not for factors.
`factor.levels`	vector of character strings or expressions giving the levels of the conditioning variable currently being drawn. For more than one conditioning variable, this will vary with `which.given`. Whether these levels are shown on the strip depends on the values of `strip.levels` and `style` (see below). `factor.levels` may be specified for both factors and shingles (despite the name), but by default they are shown only for factors. If shown, the labels may optionally be abbreviated by specifying suitable components in `par.strip.text` (see `xyplot`)
`shingle.intervals`	if the current strip corresponds to a shingle, this should be a 2-column matrix giving the levels of the shingle. (of the form that would be produced by printing `levels(shingle)`). Otherwise, it should be `NULL`
`strip.names`	a logical vector of length 2, indicating whether or not the name of the conditioning variable that corresponds to the strip being drawn is to be written on the strip. The two components give the values for factors and shingles respectively. This argument is ignored for a factor when `style` is not one of 1 and 3.
`strip.levels`	a logical vector of length 2, indicating whether or not the level of the conditioning variable that corresponds to the strip being drawn is to be written on the strip. The two components give the values for factors and shingles respectively.
`sep`	character or expression, serving as a separator if the name and level are both to be shown.
`style`	integer, with values 1, 2, 3, 4 and 5 currently supported, controlling how the current level of a factor is encoded. Ignored for shingles (actually, when `shingle.intervals` is non-null. The best way to find out what effect the value of `style` has is to try them out. Here is a short description: for a style value of 1, the strip is colored in the background color with the strip text (as determined by other arguments) centered on it. A value of 3 is the same, except that a part of the strip is colored in the foreground color, indicating the current level of the factor. For styles 2 and 4, the part corresponding to the current level remains colored in the foreground color, however, for style = 2, the remaining part is not colored at all, whereas for 4, it is colored with the background color. For both these, the names of all the levels of the factor are placed on the strip from left to right. Styles 5 and 6 produce the same effect (they are subtly different in S, this implementation corresponds to 5), they are similar to style 1, except that the strip text is not centered, it is instead positioned according to the current level. Note that unlike S-PLUS, the default value of `style` is 1. `strip.names` and `strip.levels` have no effect if `style` is not 1 or 3.
`horizontal`	logical, specifying whether the labels etc should be horizontal. `horizontal=FALSE` is useful for strips on the left of panels using `strip.left=TRUE`
`par.strip.text`	list with parameters controlling the text on each strip, with components `col`, `cex`, `font`, etc.
`bg`	strip background color.
`fg`	strip foreground color.
`...`	arguments to be passed on to `strip.default`, overriding whatever value it would have normally assumed

`x`	Extent of Bars. By default, bars start at left of panel, unless `origin` is specified, in which case they start there.
`y`	Horizontal location of bars. Possibly a factor.
`box.ratio`	Ratio of bar width to inter-bar space.
`box.width`	Thickness of bars in absolute units; overrides `box.ratio`. Useful for specifying thickness when the categorical variable is not a factor, as use of `box.ratio` alone cannot achieve a thickness greater than 1.
`horizontal`	Logical flag. If FALSE, the plot is ‘transposed’ in the sense that the behaviours of x and y are switched. x is now the ‘factor’. Interpretation of other arguments change accordingly. See documentation of `bwplot` for a fuller explanation.
`origin`	The origin for the bars. For grouped displays with `stack = TRUE`, this argument is ignored and the origin set to 0. Otherwise, defaults to `NULL`, in which case bars start at the left (or bottom) end of a panel. This choice is somewhat unfortuntate, as it can be misleading, but is the default for historical reasons. For tabular (or similar) data, `origin = 0` is usually more appropriate; if not, one should reconsider the use of a bar chart in the first place (dot plots are often a good alternative).
`reference`	Logical, whether a reference line is to be drawn at the origin.
`stack`	logical, relevant when groups is non-null. If `FALSE` (the default), bars for different values of the grouping variable are drawn side by side, otherwise they are stacked.
`groups`	Optional grouping variable.
`col`, `border`, `lty`, `lwd`	Graphical parameters for the bars. By default, the trellis parameter `plot.polygon` is used if there is no grouping variable, otherwise `superpose.polygon` is used. `col` gives the fill color, `border` the border color, and `lty` and `lwd` the line type and width of the borders.
`...`	Extra arguments will be accepted but ignored.
`identifier`	A character string that is prepended to the names of grobs that are created by this panel function.

`x`, `y`	numeric vector or factor. Boxplots drawn for each unique value of `y` (`x`) if `horizontal` is `TRUE` (`FALSE`)
`box.ratio`	ratio of box thickness to inter box space
`box.width`	thickness of box in absolute units; overrides `box.ratio`. Useful for specifying thickness when the categorical variable is not a factor, as use of `box.ratio` alone cannot achieve a thickness greater than 1.
`horizontal`	logical. If FALSE, the plot is ‘transposed’ in the sense that the behaviours of x and y are switched. x is now the ‘factor’. Interpretation of other arguments change accordingly. See documentation of `bwplot` for a fuller explanation.
`pch`, `col`, `alpha`, `cex`, `font`, `fontfamily`, `fontface`	graphical parameters controlling the dot. `pch="\|"` is treated specially, by replacing the dot with a line (similar to `boxplot`)
`fill`	color to fill the boxplot
`varwidth`	logical. If TRUE, widths of boxplots are proportional to the number of points used in creating it.
`notch`	if `notch` is `TRUE`, a notch is drawn in each side of the boxes. If the notches of two plots do not overlap this is ‘strong evidence’ that the two medians differ (Chambers et al., 1983, p. 62). See `boxplot.stats` for the calculations used.
`notch.frac`	numeric in (0,1). When `notch=TRUE`, the fraction of the box width that the notches should use.
`stats`	a function, defaulting to `boxplot.stats`, that accepts a numeric vector and returns a list similar to the return value of `boxplot.stats`. The function must accept arguments `coef` and `do.out` even if they do not use them (a `...` argument is good enough). This function is used to determine the box and whisker plot.
`coef`, `do.out`	passed to `stats`
`levels.fos`	numeric values corresponding to positions of the factor or shingle variable. For internal use.
`...`	further arguments, ignored.
`identifier`	A character string that is prepended to the names of grobs that are created by this panel function.

`x`, `y`, `z`	numeric (or possibly factors) vectors representing the data to be displayed. The interpretation depends on the context. For `panel.cloud` these are essentially the same as the data passed to the high level plot (except if `formula` was a matrix, the appropriate `x` and `y` vectors are generated). By the time they are passed to `panel.3dscatter` and `panel.3dwire`, they have been appropriately subsetted (using `subscripts`) and scaled (to lie inside a bounding box, usually the [-0.5, 0.5] cube). Further, for `panel.3dwire`, `x` and `y` are shorter than `z` and represent the sorted locations defining a rectangular grid. Also in this case, `z` may be a matrix if the display is grouped, with each column representing one surface. In `panel.cloud` (called from `wireframe`) and `panel.3dwire`, `x`, `y` and `z` could also be matrices (of the same dimension) when they represent a 3-D surface parametrized on a 2-D grid.
`subscripts`	index specifying which points to draw. The same `x`, `y` and `z` values (representing the whole data) are passed to `panel.cloud` for each panel. `subscripts` specifies the subset of rows to be used for the particular panel.
`groups`	specification of a grouping variable, passed down from the high level functions.
`perspective`	logical, whether to plot a perspective view. Setting this to `FALSE` is equivalent to setting `distance` to 0
`distance`	numeric, between 0 and 1, controls amount of perspective. The distance of the viewing point from the origin (in the transformed coordinate system) is `1 / distance`. This is described in a little more detail in the documentation for `cloud`
`screen`	A list determining the sequence of rotations to be applied to the data before being plotted. The initial position starts with the viewing point along the positive z-axis, and the x and y axes in the usual position. Each component of the list should be named one of `"x"`, `"y"` or `"z"` (repetitions are allowed), with their values indicating the amount of rotation about that axis in degrees.
`R.mat`	initial rotation matrix in homogeneous coordinates, to be applied to the data before `screen` rotates the view further.
`par.box`	graphical parameters for box, namely, col, lty and lwd. By default obtained from the parameter `box.3d`.
`xlim`, `ylim`, `zlim`	limits for the respective axes. As with other lattice functions, these could each be a numeric 2-vector or a character vector indicating levels of a factor.
`panel.3d.cloud`, `panel.3d.wireframe`	functions that draw the data-driven part of the plot (as opposed to the bounding box and scales) in `cloud` and `wireframe`. This function is called after the ‘back’ of the bounding box is drawn, but before the ‘front’ is drawn. Any user-defined custom display would probably want to change these functions. The intention is to pass as much information to this function as might be useful (not all of which are used by the defaults). In particular, these functions can expect arguments called `xlim`, `ylim`, `zlim` which give the bounding box ranges in the original data scale and `xlim.scaled`, `ylim.scaled`, `zlim.scaled` which give the bounding box ranges in the transformed scale. More arguments can be considered on request.
`aspect`	aspect as in `cloud`
`xlab`, `ylab`, `zlab`	Labels, have to be lists. Typically the user will not manipulate these, but instead control this via arguments to `cloud` directly.
`xlab.default`	for internal use
`ylab.default`	for internal use
`zlab.default`	for internal use
`scales.3d`	list defining the scales
`proportion`	numeric scalar, gives the length of arrows as a proportion of the sides
`scpos`	A list with three components x, y and z (each a scalar integer), describing which of the 12 sides of the cube the scales should be drawn. The defaults should be OK. Valid values are x: 1, 3, 9, 11; y: 8, 5, 7, 6 and z: 4, 2, 10, 12. (See comments in the source code of `panel.cloud` to see the details of this enumeration.)
`wireframe`	logical, indicating whether this is a wireframe plot
`drape`	logical, whether the facets will be colored by height, in a manner similar to `levelplot`. This is ignored if `shade=TRUE`.
`at`	When `drape = TRUE` in `wireframe`, the facets defining the surface are colored as a function of (average) height, similar to `levelplot`. `at` is a numeric vector giving the breakpoints along the z-axis where colors change.
`col.regions`	vector of colors to be used in conjunction with `at` when `drape = TRUE`. In `makeShadePalette`, which can be used to define a shading palette (see below), `col.regions` is an initial vector defining the base color (as a function of height) that is then adjusted according to irradiance and reflectance.
`alpha.regions`	numeric scalar controlling transparency when `drape = TRUE`.
`rot.mat`	4x4 transformation matrix in homogeneous coordinates. This gives the rotation matrix combining the `screen` and `R.mat` arguments to `panel.cloud`
`type`	Character vector, specifying type of cloud plot. Can include one or more of `"p"`, `"l"`, `"h"` or `"b"`. `"p"` and `"l"` mean ‘points’ and ‘lines’ respectively, and `"b"` means ‘both’. `"h"` stands for ‘histogram’, and causes a line to be drawn from each point to the X-Y plane (i.e., the plane representing `z = 0`), or the lower (or upper) bounding box face, whichever is closer.
`xlim.scaled`, `ylim.scaled`, `zlim.scaled`	axis limits (after being scaled to the bounding box)
`zero.scaled`	z-axis location (after being scaled to the bounding box) of the X-Y plane in the original data scale, to which lines will be dropped (if within range) from each point when `type = "h"`
`cross`	logical, defaults to `TRUE` if `pch = "+"`. `panel.3dscatter` can represent each point by a 3d ‘cross’ of sorts (it's much easier to understand looking at an example than from a description). This is different from the usual `pch` argument, and reflects the depth of the points and the orientation of the axes. This argument indicates whether this feature will be used. This is useful for two reasons. It can be set to `FALSE` to use `"+"` as the plotting character in the regular sense. It can also be used to force this feature in grouped displays.
`shade`	logical, indicating whether the surface is to be colored using an illumination model with a single light source
`shade.colors.palette`	a function (or the name of one) that is supposed to calculate the color of a facet when shading is being used. Three pieces of information are available to the function: first, the cosine of the angle between the incident light ray and the normal to the surface (representing foreshortening); second, the cosine of half the angle between the reflected ray and the viewing direction (useful for non-Lambertian surfaces); and third, the scaled (average) height of that particular facet with respect to the total plot z-axis limits. All three numbers should be between 0 and 1. The `shade.colors.palette` function should return a valid color. The default function is obtained from the trellis settings using `makeShadePalette`.
`min`	numeric, between 0 and 1, giving a minimum saturation in `makeShadePalette`
`pref`	numeric, giving a power that is applied to reflectance value before it is used to ‘darken’ the colors.
`light.source`	a 3-vector representing (in cartesian coordinates) the light source. This is relative to the viewing point being (0, 0, 1/distance) (along the positive z-axis), keeping in mind that all observations are bounded within the [-0.5, 0.5] cube
`polynum`	quadrilateral faces are drawn in batches of `polynum` at a time. Drawing too few at a time increases the total number of calls to the underlying `grid.polygon` function, which affects speed. Trying to draw too many at once may be unnecessarily memory intensive. This argument controls the trade-off.
`col.groups`	colors for different groups
`col`, `col.point`, `col.line`, `lty`, `lwd`, `cex`, `pch`, `fill`, `alpha`	Graphical parameters. Some other arguments (such as `lex` for line width) may also be passed through the `...` argument.
`...`	other parameters, passed down when appropriate
`.scale`	Logical flag, indicating whether `x`, `y`, and `z` should be assumed to be in the original data scale and hence scaled before being plotted. `x`, `y`, and `z` are usually already scaled. However, setting `.scale=TRUE` may be helpful for calls to `panel.3dscatter` and `panel.3dwire` in user-supplied panel functions.
`identifier`	A character string that is prepended to the names of grobs that are created by this panel function.

Package 'lattice'

Help Index

Lattice Graphics

Description

Details

Note

Author(s)

References

See Also

Examples

Common Bivariate Trellis Plots

Description

Usage

Arguments

Details

Value

Note

Author(s)

References

See Also

Examples

Time series plotting methods

Description

Usage

Arguments

Details

Value

Author(s)

References

See Also

Examples

table methods for barchart and dotplot

Description

Usage

Arguments

Details

Value

Author(s)

See Also

Examples

Histograms and Kernel Density Plots

Description

Usage

Arguments

Details

Value

Note

Author(s)

References

See Also

Examples

Q-Q Plot with Theoretical Distribution

Description

Usage

Arguments

Details

Value

Author(s)

See Also

Examples

Quantile-Quantile Plots of Two Samples

Description

Usage

Arguments

Details

Value

Author(s)

See Also

Examples

Level plots and contour plots

Description

Usage

Arguments

Details

Value

Author(s)

References

See Also

Examples

3d Scatter Plot and Wireframe Surface Plot

`x`	data points for which density is to be estimated
`darg`	list of arguments to be passed to the `density` function. Typically, this should be a list with zero or more of the following components : `bw`, `adjust`, `kernel`, `window`, `width`, `give.Rkern`, `n`, `from`, `to`, `cut`, `na.rm` (see `density` for details)
`plot.points`	logical specifying whether or not the data points should be plotted along with the estimated density. Alternatively, a character string specifying how the points should be plotted. Meaningful values are `"rug"`, in which case `panel.rug` is used to plot a ‘rug’, and `"jitter"`, in which case the points are jittered vertically to better distinguish overlapping points.
`ref`	logical, whether to draw x-axis
`groups`	an optional grouping variable. If present, `panel.superpose` will be used instead to display each subgroup
`weights`	numeric vector of weights for the density calculations. If this is specified, the `...` part must also include a `subscripts` argument that matches the weights to `x`.
`jitter.amount`	when `plot.points="jitter"`, the value to use as the `amount` argument to `jitter`.
`type`	`type` argument used to plot points, if requested. This is not expected to be useful, it is available mostly to protect a `type` argument, if specified, from affecting the density curve.
`...`	extra graphical parameters. Note that additional arguments to `panel.rug` cannot be passed on through `panel.densityplot`.
`grid`	A logical flag, character string, or list specifying whether and how a background grid should be drawn. In its general form, `grid` can be a list of arguments to be supplied to `panel.grid`, which is called with those arguments. Three shortcuts are available: `TRUE`: roughly equivalent to `list(h = -1, v = -1)` `"h"`: roughly equivalent to `list(h = -1, v = 0)` `"v"`: roughly equivalent to `list(h = 0, v = -1)` No grid is drawn if `grid = FALSE`.
`identifier`	A character string that is prepended to the names of grobs that are created by this panel function.

`x`, `y`	variables to be plotted in the panel. Typically y is the ‘factor’
`horizontal`	logical. If FALSE, the plot is ‘transposed’ in the sense that the behaviours of x and y are switched. x is now the ‘factor’. Interpretation of other arguments change accordingly. See documentation of `bwplot` for a fuller explanation.
`pch`, `col`, `lty`, `lwd`, `col.line`	graphical parameters
`levels.fos`	locations where reference lines will be drawn
`groups`	grouping variable (affects graphical parameters)
`...`	extra parameters, passed to `panel.xyplot` which is responsible for drawing the foreground points (`panel.dotplot` only draws the background reference lines).
`grid`	A logical flag, or list specifying whether and how a background grid should be drawn. In its general form `grid` can be a list of arguments to be supplied to `panel.grid`, which is called with those arguments. If `FALSE`, no grid lines are drawn. `grid = TRUE` is roughly equivalent to `list(h = 0, v = -1)` if `horizontal = TRUE` and `list(h = -1, v = 0)` if `horizontal = FALSE`. In other words, grid lines are drawn only for the numeric axis, as reference lines for the categorical axis are drawn regardless of the value of `grid`.
`identifier`	A character string that is prepended to the names of grobs that are created by this panel function.

`x`	The data points for which the histogram is to be drawn
`breaks`	The breakpoints for the histogram
`equal.widths`	logical used when `breaks==NULL`
`type`	Type of histogram, possible values being `"percent"`, `"density"` and `"count"`
`nint`	Number of bins for the histogram
`alpha`, `col`, `border`, `lty`, `lwd`	graphical parameters for bars; defaults are obtained from the `plot.polygon` settings.
`...`	other arguments, passed to `hist` when deemed appropriate
`identifier`	A character string that is prepended to the names of grobs that are created by this panel function.

`x`, `y`, `z`	Variables defining the plot.
`subscripts`	Integer vector indicating what subset of `x`, `y` and `z` to draw.
`at`	Numeric vector giving breakpoints along the range of `z`. See `levelplot` for details.
`shrink`	Either a numeric vector of length 2 (meant to work as both x and y components), or a list with components x and y which are numeric vectors of length 2. This allows the rectangles to be scaled proportional to the z-value. The specification can be made separately for widths (x) and heights (y). The elements of the length 2 numeric vector gives the minimum and maximum proportion of shrinkage (corresponding to min and max of z).
`labels`	Either a logical scalar indicating whether the labels are to be drawn, or a character or expression vector giving the labels associated with the `at` values. Alternatively, `labels` can be a list with the following components: `labels`: a character or expression vector giving the labels. This can be omitted, in which case the defaults will be used. `col, cex, alpha`: graphical parameters for label texts `fontfamily, fontface, font`: font used for the labels
`label.style`	Controls how label positions and rotation are determined. A value of `"flat"` causes the label to be positioned where the contour is flattest, and the label is not rotated. A value of `"align"` causes the label to be drawn as far from the boundaries as possible, and the label is rotated to align with the contour at that point. The default is to mix these approaches, preferring the flattest location unless it is too close to the boundaries.
`contour`	A logical flag, specifying whether contour lines should be drawn.
`region`	A logical flag, specifying whether inter-contour regions should be filled with appropriately colored rectangles.
`col`, `lty`, `lwd`	Graphical parameters for contour lines.
`border`	Border color for rectangles used when `region=TRUE`.
`border.lty`, `border.lwd`	Graphical parameters for the border
`...`	Extra parameters.
`region.type`	A character string, one of `"grid"` and `"contour"`. The former (the default) uses a grid of rectangles to display the colors for the level plot; the latter uses a grid of polygons, mimicking the behavior of `filled.contour`, which gives a smoother appearance at the cost of increased processing time. The `"contour"` option requires `x` and `y` to be complete, in the sense that it must include all possible combinations in the underlying grid. However, `z` values are allowed to be missing.
`col.regions`	A vector of colors, or a function to produce a vecor of colors, to be used if `region=TRUE`. Each interval defined by `at` is assigned a color, so the number of colors actually used is one less than the length of `at`. See `level.colors` for details on how the color assignment is done.
`alpha.regions`	numeric scalar controlling transparency of facets
`interpolate`	logical, passed to `grid.raster`.
`identifier`	A character string that is prepended to the names of grobs that are created by this panel function.

`z`	The data frame used for the plot.
`panel`, `lower.panel`, `upper.panel`	The panel function used to display each pair of variables. If specified, `lower.panel` and `upper.panel` are used for panels below and above the diagonal respectively. In addition to extra arguments not recognized by `panel.pairs`, the list of arguments passed to the panel function also includes arguments named `i` and `j`, with values indicating the row and column of the scatterplot matrix being plotted.
`diag.panel`	The panel function used for the diagonals. See arguments to `diag.panel.splom` to know what arguments this function is passed when called. Use `diag.panel=NULL` to suppress plotting on the diagonal panels.
`as.matrix`	logical. If `TRUE`, the layout of the panels will have origin on the top left instead of bottom left (similar to `pairs`). This is in essence the same functionality as provided by `as.table` for the panel layout
`groups`	Grouping variable, if any
`panel.subscripts`	logical specifying whether the panel function accepts an argument named `subscripts`.
`subscripts`	The indices of the rows of `z` that are to be displayed in this (super)panel.
`pscales`	Controls axis labels, passed down from `splom`. If `pscales` is a single number, it indicates the approximate number of equally-spaced ticks that should appear on each axis. If `pscales` is a list, it should have one component for each column in `z`, each of which itself a list with the following valid components: `at`: a numeric vector specifying tick locations `labels`: character vector labels to go with at `limits`: numeric 2-vector specifying axis limits (should be made more flexible at some point to handle factors) These are specifications on a per-variable basis, and used on all four sides in the diagonal cells used for labelling. Factor variables are labelled with the factor names. Use `pscales=0` to supress the axes entirely.
`prepanel.limits`	A function to calculate suitable axis limits given a single argument `x` containing a data vector. The return value of the function should be similar to the `xlim` or `ylim` argument documented in `xyplot`; that is, it should be a numeric or DateTime vector of length 2 defining a range, or a character vector representing levels of a factor. Most high-level lattice plots (such as `xyplot`) use the `prepanel` function for deciding on axis limits from data. This function serves a similar function by calculating the per-variable limits. These limits can be overridden by the corresponding `limits` component in the `pscales` list.
`x`	data vector corresponding to that row / column (which will be the same for diagonal ‘panels’).
`varname`	(scalar) character string or expression that is to be written centred within the panel
`limits`	numeric of length 2, or, vector of characters, specifying the scale for that panel (used to calculate tick locations when missing)
`at`	locations of tick marks
`labels`	optional labels for tick marks
`draw`	A logical flag specifying whether to draw the tick marks and labels. If `FALSE`, variable names are shown but axis annotation is omitted.
`tick.number`	A Numeric scalar giving the suggested number of tick marks.
`varnames`	A character or expression vector or giving names to be used for the variables in `x`. By default, the column names of `x`.
`varname.col`	Color for the variable name in each diagonal panel. See `gpar` for details on this and the other graphical parameters listed below.
`varname.cex`	Size multiplier for the variable name in each diagonal panel.
`varname.lineheight`	Line height for the variable name in each diagonal panel.
`varname.font`, `varname.fontfamily`, `varname.fontface`	Font specification for the variable name in each diagonal panel.
`axis.text.col`	Color for axis label text.
`axis.text.cex`	Size multiplier for axis label text.
`axis.text.font`, `axis.text.fontfamily`, `axis.text.fontface`	Font specification for axis label text.
`axis.text.lineheight`	Line height for axis label text.
`axis.text.alpha`	Alpha-transparency for axis label text.
`axis.line.col`	Color for the axes.
`axis.line.lty`	Line type for the axes.
`axis.line.lwd`	Line width for the axes.
`axis.line.alpha`	Alpha-transparency for the axes.
`axis.line.tck`	A numeric multiplier for the length of tick marks in diagonal panels.
`...`	Further arguments, passed on to `panel`, `lower.panel`, `upper.panel`, and `diag.panel` from `panel.pairs`. Currently ignored by `diag.panel.splom`.

`x`, `y`	dummy variables, ignored.
`z`	The data frame used for the plot. Each column will be coerced to numeric before being plotted, and an error will be issued if this fails.
`subscripts`	The indices of the rows of `z` that are to be displyed in this panel.
`groups`	An optional grouping variable. If specified, different groups are distinguished by use of different graphical parameters (i.e., rows of `z` in the same group share parameters).
`col`, `lwd`, `lty`, `alpha`	graphical parameters (defaults to the settings for `superpose.line`). If `groups` is non-null, these parameters used one for each group. Otherwise, they are recycled and used to distinguish between rows of the data frame `z`.
`common.scale`	logical, whether a common scale should be used columns of `z`. Defaults to `FALSE`, in which case the horizontal range for each column is different (as determined by `lower` and `upper`).
`lower`, `upper`	numeric vectors replicated to be as long as the number of columns in `z`. Determines the lower and upper bounds to be used for scaling the corresponding columns of `z` after coercing them to numeric. Defaults to the minimum and maximum of each column. Alternatively, these could be functions (to be applied on each column) that return a scalar.
`...`	other arguments (ignored)
`horizontal.axis`	logical indicating whether the parallel axes should be laid out horizontally (`TRUE`) or vertically (`FALSE`).
`identifier`	A character string that is prepended to the names of grobs that are created by this panel function.

`x`	vector (typically numeric, coerced if not) of data values to be used in the panel.
`f.value`, `distribution`	Defines how quantiles are calculated. See `qqmath` for details.
`qtype`	The `type` argument to be used in `quantile`
`groups`	An optional grouping variable. Within each panel, one Q-Q plot is produced for every level of this grouping variable, differentiated by different graphical parameters.
`...`	Further arguments, often graphical parameters, eventually passed on to `panel.xyplot`. Arguments `grid` and `abline` of `panel.xyplot` may be particularly useful.
`tails.n`	number of data points to represent exactly on each tail of the distribution. This reproduces the effect of `f.value = NULL` for the extreme data values, while approximating the remaining data. It has no effect if `f.value = NULL`. If `tails.n` is given, `qtype` is forced to be 1.
`identifier`	A character string that is prepended to the names of grobs that are created by this panel function.

`x`, `y`	coordinates of points to be plotted
`jitter.data`	whether points should be jittered to avoid overplotting. The actual jittering is performed inside `panel.xyplot`, using its `jitter.x` or `jitter.y` argument (depending on the value of `horizontal`).
`factor`, `amount`	amount of jittering, see `jitter`
`horizontal`	logical. If FALSE, the plot is ‘transposed’ in the sense that the behaviours of x and y are switched. x is now the ‘factor’. Interpretation of other arguments change accordingly. See documentation of `bwplot` for a fuller explanation.
`groups`	optional grouping variable
`...`	additional arguments, passed on to `panel.xyplot`
`grid`	A logical flag, character string, or list specifying whether and how a background grid should be drawn. In its general form, `grid` can be a list of arguments to be supplied to `panel.grid`, which is called with those arguments. Three shortcuts are available: `TRUE`: roughly equivalent to `list(h = -1, v = -1)` `"h"`: roughly equivalent to `list(h = -1, v = 0)` `"v"`: roughly equivalent to `list(h = 0, v = -1)` No grid is drawn if `grid = FALSE`.
`identifier`	A character string that is prepended to the names of grobs that are created by this panel function.

`x`, `y`	variables to be plotted in the scatterplot
`type`	character vector controlling how `x` and `y` are to be plotted. Can consist of one or more of the following: `"p"`, `"l"`, `"h"`, `"b"`, `"o"`, `"s"`, `"S"`, `"g"`, `"r"`, `"a"`, `"smooth"`, and `"spline"`. If `type` has more than one element, an attempt is made to combine the effect of each of the components. The behaviour if any of the first five are included in `type` is similar to the effect of the corresponding `type` in `plot`: `"p"` and `"l"` stand for points and lines respectively; `"b"` and `"o"` (for ‘overlay’) plot both; `"h"` draws vertical (or horizontal if `horizontal = TRUE`) line segments from the points to the origin. Types `"s"` and `"S"` are like `"l"` in the sense that they join consecutive points, but instead of being joined by a straight line, points are connected by a vertical and a horizontal segment forming a ‘step’, with the vertical segment coming first for `"s"`, and the horizontal segment coming first for `"S"`. Types `"s"` and `"S"` sort the values along one of the axes (depending on `horizontal`); this is unlike the behavior in `plot`. For the latter behavior, use `type = "s"` with `panel = panel.points`. Type `"g"` adds a reference grid using `panel.grid` in the background, but using the `grid` argument is now the preferred way to do so. The remaining values of `type` lead to various types of smoothing. This can also be achieved using the `smooth` argument, or by calling the relevant panel functions directly. The panel functions provide finer control over graphical and other parameters, but using `smooth` or `type` is convenient for simple usage. Using `smooth` is recommended, but `type` is also supported for backwards compatibility. Type `"r"` adds a linear regression line, `"smooth"` adds a loess fit, `"spline"` adds a cubic smoothing spline fit, and `"a"` draws line segments joining the average `y` value for each distinct `x` value. See `smooth` for details. See `example(xyplot)` and `demo(lattice)` for examples.
`groups`	an optional grouping variable. If present, `panel.superpose` will be used instead to display each subgroup
`col`, `col.line`, `col.symbol`	default colours are obtained from `plot.symbol` and `plot.line` using `trellis.par.get`.
`font`, `fontface`, `fontfamily`	font used when `pch` is a character
`pch`, `lty`, `cex`, `lwd`, `fill`	other graphical parameters. `fill` serves the purpose of `bg` in `points` for certain values of `pch`
`horizontal`	A logical flag controlling the orientation for certain `type`'s, e.g., `"h"`, `"s"`, ans `"S"` and the result of smoothing.
`...`	Extra arguments, if any, for `panel.xyplot`. Usually passed on as graphical parameters to low level plotting functions, or to the panel functions performing smoothing, if applicable.
`smooth`	If specificied, indicates the type of smooth to be added. Can be a character vector containing one or more values from `"lm"`, `"loess"`, `"spline"`, and `"average"`. Can also be a logical flag; `TRUE` is interpreted as `"loess"`. Each of these result in calling a corresponding panel function as described below; the `smooth` argument simply provides a convenient shortcut. `"lm"` adds a linear regression line (same as `panel.lmline`, except for default graphical parameters). `"loess"` adds a loess fit (same as `panel.loess`). `"spline"` adds a cubic smoothing spline fit (same as `panel.spline`). `"average"` has the effect of calling `panel.average`, which in conjunction with a `groups` argument can be useful for creating interaction plots. Normally, smoothing is performed with the `y` variable as the response and the `x` variable as the predictor. However, the roles of `x` and `y` are reversed if `horizontal = TRUE`.
`grid`	A logical flag, character string, or list specifying whether and how a background grid should be drawn. This provides the same functionality as `type="g"`, but is the preferred alternative as the effect `type="g"` is conceptually different from that of other `type` values (which are all data-dependent). Using the `grid` argument also allows more flexibility. Most generally, `grid` can be a list of arguments to be supplied to `panel.grid`, which is called with those arguments. Three shortcuts are available: `TRUE`: roughly equivalent to `list(h = -1, v = -1)` `"h"`: roughly equivalent to `list(h = -1, v = 0)` `"v"`: roughly equivalent to `list(h = 0, v = -1)` No grid is drawn if `grid = FALSE`.
`abline`	A numeric vector or more generally a list containing arguments that are used to call `panel.abline`. If specified as a numeric vector, `abline` is used as the first unnamed argument to `panel.abline`. This allows arguments of the form `abline = c(0, 1)`, which adds the diagonal line, or `abline = coef(fm)` to fit the regression line from a fitted mode. Use the list form for finer control; e.g., `abline = list(h = 0, v = 0, col = "grey")`. For more flexibility, use `panel.abline` directly.
`jitter.x`, `jitter.y`	logical, whether the data should be jittered before being plotted.
`factor`, `amount`	controls amount of jittering.
`identifier`	A character string that is prepended to the names of grobs that are created by this panel function.

`x`, `y`, `x0`, `y0`, `x1`, `y1`, `x2`, `y2`, `xy`	locations. `x2` and `y2` are available for for S compatibility.
`length`, `unit`	determines extent of arrow head. `length` specifies the length in terms of `unit`, which can be any valid grid unit as long as it doesn't need a `data` argument. `unit` defaults to inches, which is the only option in the base version of the function, `arrows`.
`angle`, `code`, `type`, `labels`, `srt`, `adj`, `pos`, `offset`	arguments controlling behaviour. See respective base functions for details. For `larrows` and `panel.larrows`, `type` is either `"open"` or `"closed"`, indicating the type of arrowhead.
`ends`	serves the same function as `code`, using descriptive names rather than integer codes. If specified, this overrides `code`
`col`, `alpha`, `lty`, `lwd`, `fill`, `pch`, `cex`, `lineheight`, `font`, `fontfamily`, `fontface`, `col.line`, `col.symbol`, `border`	graphical parameters. `fill` applies to points when `pch` is in `21:25` and specifies the fill color, similar to the `bg` argument in the base graphics function `points`. For devices that support alpha-transparency, a numeric argument `alpha` between 0 and 1 can controls transparency. Be careful with this, since for devices that do not support alpha-transparency, nothing will be drawn at all if this is set to anything other than 0. `fill`, `font` and `fontface` are included in `lrect`, `larrows`, `lpolygon`, and `lsegments` only to ensure that they are not passed down (as `gpar` does not like them).
`origin`	for `type="h"` or `type="H"`, the value to which lines drop down.
`xleft`, `ybottom`, `xright`, `ytop`	see `rect`
`width`, `height`, `just`, `hjust`, `vjust`	finer control over rectangles, see `grid.rect`
`...`	extra arguments, passed on to lower level functions as appropriate.
`rule`	character string specifying how `NA` values are interpreted for polygons and paths. This is mainly intended for paths (via `grid.path`), but can also be specified for polygons for convenience. For polygons, the default rule is `"none"`, which treats `NA`-separated segments as separate polygons. This value is only valid for polygons. For the other rules (`"winding"` or `"evenodd"`) these segments are interpreted as subpaths, possibly representing holes, of a single path, and are rendered using `grid.path`. Support and rendering speed may depend on the device being used.
`identifier`	A character string that is prepended to the name of the grob that is created.
`name.type`	A character value indicating whether the name of the grob should have panel or strip information added to it. Typically either `"panel"`, `"strip"`, `"strip.left"`, or `""` (for no extra information).