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.
ARGUMENTS:
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, list or bdFrame in which to find the objects mentioned
in
formula.
If is argument is a bdFrame then a bigdata version of the function is called.
In some cases this may result in a different style plot being drawn
e.g. a hexbin plot instead of an ordinary scatterplot.
See the specific Trellis function help file for details.
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.
nobox
specifies whether to draw a box around a Trellis graph.
If
FALSE (the default), a
box is drawn.
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
).
In addition,
the high-level graphics arguments described
under
and the arguments to
may be supplied to this function.
Most of these arguments, when specified, affect all panels in the plot.