---

USAGE:

trellis.function(
   formula,
   aspect = "fill",
   as.table = FALSE,
   between = ,
   data = ,
   key = ,
   layout = ,
   main = ,
   page = ,
   panel = panel.trellis.function,
   par.strip.text = ,
   prepanel = ,
   scales = ,
   skip = ,
   strip = strip.default,
   sub = ,
   subscripts = ,
   subset = ,
   xlab = ,
   xlim = ,
   ylab = ,
   ylim = ,
   ...
)

These arguments are common to all Trellis display functions. See the documentation for any particular function to read about any special restrictions or default values involving these arguments. The formula argument is typically given positionally, i.e., as the first argument to the function; all other arguments are given in name=value form.

aspect:

aspect ratio control. A numeric value controls each panel's physical aspect ratio (vertical size/horizontal size). The character string "xy" causes the 45-degree banking rule to be used on the x and y data for all panels. The string "fill" (the default) adjusts the aspect ratio so that the panels fill the page or screen. Note that the aspect argument is different for the 3D functions cloud and wireframe; see trellis.3d.args.

as.table:

logical flag that controls whether the panel order is done as a table or as a graph. By default, as.table is FALSE, specifying the standard panel order from left to right, bottom to top. If as.table is TRUE, the panel order is left to right, top to bottom. For an example of when this order may be useful, see example.calendar.

between:

a list with components named x and y, numeric vectors that specify the space between the columns and rows of the displayed panels. The units for between are in character heights.

data:

an optional data frame or list in which to find the objects mentioned in formula. When the data= argument is included, objects in formula are not searched for in the frame of the caller. Thus, if you write a function that calls a trellis routine and gives a data= argument, no objects defined in your function will be accessible, nor will arguments to your function be accessible. Regardless of the data= argument, objects are always accessible if they are on the database search list.

formula:

formula defining the response and the predictors. In general, its form is: y ~ x | g1 * g2 * ... however the given variables g1, g2, ... may be omitted. The y variable is plotted on the y axis and x plotted on the x axis. The x and y variables are generally numeric and define the data on each panel The given variables determine how many panels are produced. Given variables can be either factors or shingles; numeric given variables are turned into shingles, character variables into factors. All variables in the formula must of vectors of equal length. The formula may also contain expressions for the variables, e.g. sqrt(count) or log(age+1). If a character vector is a given variable, it is converted to a factor; a numeric given vector is converted to a shingle.

Missing values (NA) are allowed. Any points containing missing values will be omitted from the plot.

key:

a list of arguments to be passed to the key function. If the list is non-null, a key is placed on each page. If key contains a component named space, the software will reserve space for the legend on the appropriate side of the array of panels; values for space are "top" (default), "bottom", "left", and "right". See documentation for key for a full description of the other components of the key= list.

layout:

numeric vector giving number of panels in columns, rows, and pages (note particularly the order of these numbers: columns before rows). By default, the number of columns is determined by the number of levels in the first given variable; the number of rows is the number of levels of the second given variable. If there is one given 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, the aspect ratio of the panels and size of labels in order to maximize the space devoted to displaying the data. The pages value can be used to plot only a limited number of pages, where the rows, columns, and given values might imply more. By default, the pages value is unlimited.

main:

character string for a main title to be placed at the top of each page. This may be a list containing a character string along with graphical parameters to control size (cex), color (col), and font (font) of the title.

page:

A function of one argument that is called at the end of each page drawn by trellis. The argument gives the page number for this display. The function can display page numbers, add text or graphics to each page, etc. The default page function does nothing.

panel:

A function of two arguments, x and y, that draws the data display in each panel. Prior to calling the panel function, the x- and y- coordinate system is set up to accommodate the range of the x and y values in formula and takes into account the information in the scales argument. If the panel function is defined with an argument named subscripts, then the panel function is called with a third (numeric) argument that tells where the x and y values come from in the entire set of data.

par.strip.text:

A list giving graphical parameters to be applied to the text in strip labels. Most important is the cex= parameter, that not only controls character size, but also adjusts the height of the strip labels so that the text fits inside.

prepanel:

optional function that is called prior to plotting in order to set up appropriate axis scales and aspect ratios. A prepanel function gets two arguments, x and y, and is expected to return a list containing one or more of the following components: xlim, ylim, dx and dy. When axes are set up, they are guaranteed to include the xlim and ylim values (unless the limits are overridden by arguments to the high-level routine of the same names). The dx and dy vectors are used to compute an aspect ratio by banking to 45-degrees, in conjunction with the aspect="xy" argument.

scales:

A list that determines how the x- and y-axes (tick marks and tick labels) are scaled and drawn. The list contains parameters in name=value form, and may also contain two other lists of the same type, named x and y. Parameters specified in the x or y components affect only that axis; those specified at the top level of scales affect both axes. The most important scales component is relation, controlling the relationship between axes on various panels. The default value, relation="same", ensures that the horizontal or vertical axes on each panel will be identical. relation="sliced" gives the same number of data units to corresponding axes on each panel, ensuring that the number of units per cm. is identical. Using relation="free" results in each panel having an axis that accommodates just the data in that panel. For "sliced" and "free", axes will be drawn for each panel, using more space on the display. The numeric value tick.number controls the approximate number of tick marks and labels that appear on the axis. The logical value draw determines whether the axis as a whole will be drawn. The logical value alternating determines whether axes alternate from one side of the group of panels to the other. (Using alternating=FALSE can save space if long tick labels are used.) For more precise control, alternating can be a vector that specifies the side of the plot on which each axis is drawn with 1=bottom/left, 2=top/right, 0=do not draw: alternating=TRUE for a y-axis is identical to alternating=c(1,2). The value limits specifies limits for the coordinate system; arguments xlim, and ylim are a shorthand way of specifying the limits value. The value 'log' controls logarithmic axes. Standard base-10 logs are used for log=T or log=10; log=2 gives base-2 logs which may also be useful. Other parameters that are allowed in scales are those appropriate to the axis function: at, labels (see documentation for axis), as well as graphical parameters to control the axis rendering (col, cex). This argument is different for the 3D functions (cloud and wireframe); see trellis.3d.args.

skip:

logical vector. This vector is replicated to be as long as the total number of panels on the pages specified by layout. For each panel, the corresponding value of skip determines whether anything will be plotted on the panel. This is useful for leaving blanks so that the number of plottable panels matches the number of levels of one or more given variables. By default, all panels are used.

strip:

logical flag or a function. If strip is FALSE, no strip labels are drawn and no room is left for them. If strip is TRUE, the function strip.default is used to draw strip labels. Otherwise, the value of strip can be a function that draws strip labels. See documentation for strip.default for more details.

sub:

character string for a subtitle, to be placed at the bottom of each page. This may be a list containing a character string along with graphical parameters to control size (cex), color (col), and font (font) of the subtitle.

subscripts:

logical value; if TRUE, a 3rd argument named subscripts is passed to the panel function.

subset:

a subscript vector appropriate for subscripting the x, y and given vectors. This can be a numeric vector with positive integers, one with negative integers indicating which observations should be omitted, or a logical vector.

xlab:

character string giving a label for the x-axis. By default, the expression given for x in formula. This may be a list containing a character string along with graphical parameters to control size (cex), color (col), and font (font) of the x-label.

xlim:

numeric vector of length 2 giving minimum and maximum values for the x-axes.

ylab:

character string giving a label for the y-axis. By default, the expression given for y in formula. This may be a list containing a character string along with graphical parameters to control size (cex), color (col), and font (font) of the y-label.

ylim:

numeric vector of length 2 giving minimum and maximum values for the y-axes.

...:

other arguments are passed down to the function panel.

Graphical parameters may also be supplied as arguments to this function (see par). In addition, the high-level graphics arguments described under par and the arguments to title may be supplied to this function. Most of these arguments, when specified, affect all panels in the plot.