xyplot                package:lattice                R Documentation

_C_o_m_m_o_n _B_i_v_a_r_i_a_t_e _T_r_e_l_l_i_s _P_l_o_t_s

_D_e_s_c_r_i_p_t_i_o_n:

     These are the most commonly used high level Trellis functions to
     plot pairs of variables. By far the most common is 'xyplot',
     designed mainly for two continuous variates (though factors can be
     supplied as well, in which case they will simply be coerced to
     numeric), which produces Conditional Scatter plots. The others are
     useful when one of the variates is a factor or a shingle.  Most of
     these arguments are also applicable to other high level functions
     in the lattice package, but are only documented here.

_U_s_a_g_e:

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

     ## S3 method for class 'formula':
     xyplot(x,
            data = parent.frame(),
            panel = if (is.null(groups)) "panel.xyplot"
                    else "panel.superpose",
            allow.multiple,
            outer,
            aspect = "fill", 
            as.table = FALSE,
            between,
            groups,
            key,
            auto.key = FALSE,
            legend,
            layout,
            main,
            page,
            par.strip.text,
            prepanel,
            scales,
            skip,
            strip = "strip.default",
            strip.left = FALSE,
            sub,
            xlab,
            xlim,
            ylab,
            ylim,
            drop.unused.levels,
            par.settings,
            perm.cond,
            index.cond,
            ...,
            default.scales,
            panel.groups = "panel.xyplot",
            subscripts,
            subset)

     ## S3 method for class 'formula':
     dotplot(x,
             data,
             panel = "panel.dotplot",
             ...)

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

     ## S3 method for class 'formula':
     stripplot(x,
               data,
               panel = "panel.stripplot",
               jitter.data = FALSE,
               factor = .5,
               ...)

     ## S3 method for class 'formula':
     bwplot(x,
            data,
            panel = "panel.bwplot",
            box.ratio = 1,
            ...,
            horizontal,
            subset = TRUE)

_A_r_g_u_m_e_n_t_s:

       x: The object on which method dispatch is carried out.

          For the '"formula"' methods, a formula describing the form of
          conditioning plot. The formula is generally of the form '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, ...'. However, the
          conditioning variables 'g1,g2,...' may be omitted. The
          formula can also be supplied as 'y ~ x | g1 + g2 + ...'.

          For all of these functions, with the exception of 'xyplot', a
          formula of the form ' ~ x | g1 * g2 * ...' is also allowed.
          In that case, 'y' defaults to 'names(x)' if 'x' is named, and
          a factor with a single level otherwise.

          Other usage of the form 'dotplot(x)' is handled by method
          dispatch as appropriate.  The 'numeric' method is 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
          under 'barchart.table'.

          The conditioning variables 'g1, g2, ...' must be either
          factors or shingles.  Shingles are a way of processing
          numeric variables for use in conditioning. See documentation
          of 'shingle' for details. Like factors, they have a
          '"levels"' attribute, which is used in producing the
          conditional plots.

          Numeric conditioning variables are converted to shingles by
          the function 'shingle' (however, using 'equal.count' might be
          more appropriate in many cases) and character vectors are
          coerced to factors.

          The formula can involve expressions, e.g. 'sqrt()', 'log()'.

          A special case is when the left and/or right sides of the
          formula (before the conditioning variables) contain 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 (this is slightly more complicated in 'barchart'). The
          two parts would be distinguished by different graphical
          parameters. This is essentially what the 'groups' argument
          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' as well as 'allow.multiple'. 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).

          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 this 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 still allowed, with a warning, but will no
          longer be allowed from the next major release.  It is
          recommended that this argument not be named in any case, but
          rather be the first (unnamed) argument.

    data: For the 'formula' method, a data frame containing values for
          any variables in the formula, as well as 'groups' and
          'subset' if applicable.  By default the environment where the
          function was called from is used.   

allow.multiple, outer: logical flags to control what happens with
          formulas like 'y1 + y2 ~ x'. See the entry for 'formula' for
          details. 'allow.multiple' defaults to 'TRUE' whenever it
          makes sense, and 'outer' defaults to 'FALSE' except when
          'groups' is explicitly specified or grouping doesn't make
          sense for the default panel function 

box.ratio: applicable to 'bwplot', 'barchart' and 'stripplot',
          specifies the ratio of the width of the rectangles to the
          inter rectangle space. 

horizontal: logical, 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 supposed to use it
          as appropriate.

          A potentially useful component of 'scales' in this case might
          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. 

jitter.data: logical specifying whether the values should be jittered
          by adding a random noise in stripplot.  This is actually an
          argument of 'panel.stripplot'. 

  factor: numeric controlling amount of jitter as in 'jitter'. 

   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.  Each high level function has its own
          default panel function, which could depend on whether the
          'groups' argument was supplied.

          The panel function can be a function object or a character
          string giving the name of a predefined function.

          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 might be useful to know in this context that
          all arguments passed to a high level Trellis 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, 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 base R graphics functions useful for this purpose.  For
          example, 'lines' can be replaced by 'llines' (or
          equivalently, 'panel.lines'). Note that base R 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 determining 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 '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.
           The value of 'subscripts' becomes slightly more complicated
          when 'allow.multiple' is in effect.  Details can be found in
          the source code of the function 'latticeParseFormula'.

          A panel function can have two other optional arguments for
          convenience, namely 'panel.number' and 'packet.number',
          representing panel order and packet order respectively.  Both
          provide a simple integer index indicating which panel is
          currently being drawn, but differ in how the count is
          calculated. 'panel.number' is a simple incremental counter
          that starts with 1 and is incremented each time a panel is
          drawn. '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).  panel
          functions for 'bwplot' and friends should have an argument
          called 'horizontal' to account for the cases when 'x' is the
          factor or shingle. 

panel.groups: useful mostly for 'xyplot' and 'densityplot'. Applies
          when 'panel' is 'panel.superpose' (which happens by default
          in these cases if 'groups' is non-null) 

  aspect: controls physical aspect ratio of the panels (same for all
          the panels). It can be specified as a ratio (vertical
          size/horizontal size) or as a character string. Legitimate 
          values are '"fill"' (the default) which tries to make the
          panels as big as possible to fill the available space;
          '"xy"', which *tries* to compute the aspect based on the 45
          degree banking rule (see _Visualizing Data_ by William S.
          Cleveland for details); 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. Currently, only the default prepanel
          function for 'xyplot' can be expected to produce sensible
          banking calculations.  See 'banking' for details on the
          implementation of banking . 

as.table: logical that controls the order in which panels should be
          plotted: 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. 

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

  groups: a variable or expression to be evaluated in the data frame
          specified by '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.  Not all pre-defined
          panel functions know how to, but for high level functions
          where grouping is appropriate, the default panel functions
          are chosen so that they do.

          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 (indicating whether a key is to be drawn
          automatically when a grouping variable is present in the
          plot), or a list of parameters that would be valid arguments
          to 'simpleKey'. 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 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)

          'simpleKey' uses the trellis settings to determine the
          graphical parameters in the key, so this will be meaningful
          only if the settings are used in the plot as well.

          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-'print'ed with different settings, the parameter settings
          for the original device will be used. However, with
          'auto.key', the key is actually created at printing time, so
          the key settings will match the device settings. 

     key: A list of arguments that define a legend to be drawn on the
          plot. This list is used as an argument to the 'draw.key'
          function, which produces a grid object eventually plotted by
          the print method for '"trellis"' objects.

          There is also a less flexible but usually sufficient shortcut
          function 'simpleKey' that can generate such a list, as well
          as the argument 'auto.key' that can be convenient in the most
          common situation where legends are used, namely when there is
          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 can be one of 'c(0,0)', 'c(1,0)', 'c(1,1)'
          and 'c(0,1)', which denote the corners of the unit square. 
          'x' and 'y' must be numbers between 0 and 1, giving
          coordinates with respect to the whole display area.

          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 has to have a character or expression
          vector as its first component, and 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'

             *  'col="black"'

             *  'lty=1'

             *  'lwd=1'

             *  'font=1'

             *  'fontface'

             *  'fontfamily'

             *  'pch=8'

             *  'adj=0'

             *  'type="l"'

             *  'size=5'

             *  'angle=0'

             *  'density=-1'

          'adj', 'angle' and 'density' are currently 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.

          Other possible components of 'key' are:

          '_b_e_t_w_e_e_n' numeric vector giving the amount of space
               (character widths) surrounding each column (split
               equally on both sides),

          '_t_i_t_l_e' string or expression giving a title for the key

          '_r_e_p' logical, defaults to 'TRUE'.  By default, it's 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.

          '_c_e_x._t_i_t_l_e' cex for the title

          '_l_i_n_e_s._t_i_t_l_e' how many lines the title should occupy (in
               multiples of itself).  Defaults to 2.

          '_b_a_c_k_g_r_o_u_n_d' background color, defaults to default background

          '_b_o_r_d_e_r' either a color for the border, or a logical.  In the
               latter case, the border color is black if 'border' is
               'TRUE', and no border is drawn if it is 'FALSE' (the
               default)

          '_t_r_a_n_s_p_a_r_e_n_t=_F_A_L_S_E' logical, whether key area should have a
               transparent background

          '_c_o_l_u_m_n_s' the number of columns column-blocks the key is to
               be divided into, which are drawn side by side.

          '_b_e_t_w_e_e_n._c_o_l_u_m_n_s' Space between column blocks, in addition to
               'between'.

          '_d_i_v_i_d_e' 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 one to use 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 it does for
          'key'. 

  layout: In general, a Trellis conditioning plot consists of several
          panels arranged in a rectangular array, possibly spanning
          multiple pages. 'layout' determines this arrangement.

          'layout' is a numeric vector giving the number of columns,
          rows and pages in a multi panel 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")').  The number of pages is by
          default set to as many as is required to plot all the panels.
           In general, giving a high value of 'layout[3]' is not
          wasteful because blank pages are never created. 

    main: typically a character string or expression or list describing
          the main title to be placed on top of each page. Defaults to
          'NULL'.  Can be a character string or expression, or a list
          with components 'label', 'cex', 'col' and 'font'.  The
          'label' tag can be omitted if it is the first element of the
          list.  Expressions are treated as specification of LaTeX-like
          markup as in 'plotmath'.

          'main' can also be an arbitrary '"grob"' (grid graphical
          object). 

    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. 

par.strip.text: list of graphical parameters to control the strip text,
          possible 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. 

prepanel: 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 '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 of values, or a
          character vector representing levels of a factor).  If the
          'xlim' and 'ylim' arguments are not explicitly specified
          (possibly as components in 'scales'), 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 panel
          by panel basis otherwise. See 'xlim' to see what forms of the
          components 'xlim' and 'ylim' are allowed.

          The 'dx' and 'dy' components are used for banking
          computations in case 'aspect' is specified as '"xy"'.  See
          documentation for the function 'banking' for details
          regarding how this is done.

          The return value of the prepanel function need not have all
          the components named above; in case some are missing, they
          are replaced by the usual component-wise defaults.

          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 is appropriate, values
          of NA should be returned for the 'xlim' and 'ylim'
          components. 

  scales: 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 y-axis only); these can be
          overridden only by an entry in the corresponding component of
          'scales'.

          The possible components are :

          '_r_e_l_a_t_i_o_n' 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'.  If relation is not '"same"', the value
               of 'xlim' etc is normally ignored, except when it is a
               list, in which case it is treated as if its components
               were the limit values obtained from the prepanel
               calculations for each panel.

          '_t_i_c_k._n_u_m_b_e_r' Suggested number of ticks (ignored for a
               factor, shingle or character vector, in which case there
               is no natural rule for leaving out some of the labels.
               But see 'xlim').

          '_d_r_a_w' logical, defaults to 'TRUE', whether to draw the axis
               at all.

          '_a_l_t_e_r_n_a_t_i_n_g' logical specifying whether axis labels should
               alternate from one side of the group of panels to the
               other.  For finer control, alternating can 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)'

          '_l_i_m_i_t_s' same as xlim and ylim.

          '_a_t' 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.

          '_l_a_b_e_l_s' Labels (strings or expressions) to go along with
               'at'. Can be a list like 'at' as well.

          '_c_e_x' numeric multiplier to control character sizes for axis
               labels. Can be a vector of length 2, to control
               left/bottom and right/top separately.

          '_f_o_n_t', '_f_o_n_t_f_a_c_e', '_f_o_n_t_f_a_m_i_l_y' specifies font for axis
               labels.

          '_t_c_k' numeric to control length of tick marks. Can be a
               vector of length 2, to control left/bottom and right/top
               separately.

          '_c_o_l' color of ticks and labels.

          '_r_o_t' Angle by which the axis labels are to be rotated. Can
               be a vector of length 2, to control left/bottom and
               right/top separately.

          '_a_b_b_r_e_v_i_a_t_e' logical, whether to abbreviate the labels using
               'abbreviate'.  Can be useful for long labels (e.g., in
               factors), especially on the x-axis.

          '_m_i_n_l_e_n_g_t_h' argument passed to 'abbreviate' if
               'abbreviate=TRUE'.

          '_l_o_g' whether to use a log scale. Defaults to 'FALSE', other
               possible values are any number that works as a base for
               taking logarithm, 'TRUE', equivalent to 10, and '"e"'
               (for natural logarithm).  Note that in this case the
               values passed to the panel function are already
               transformed, so all computations done inside the panel
               function will be affected accordingly. For example,
               'panel.lmline' will fit a line to the transformed
               values.

          '_f_o_r_m_a_t' the 'format' to use for POSIXct variables. See
               'strptime' for description of valid values.

          '_a_x_s' character, '"r"' 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'. 

    skip: 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 is often
          useful for arranging plots in an informative manner. 

strip, strip.left: logical flag or function.  If 'FALSE', strips are
          not drawn. Otherwise, strips are drawn using the 'strip' (or
          'strip.left') function, which defaults to 'strip.default'.
          See documentation of 'strip.default' to see the arguments
          that are available to the strip function.  '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. 

     sub: character string or expression (or a '"grob"') for a subtitle
          to be placed at the bottom of each page.  See entry for
          'main' for finer control options. 

subscripts: logical 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'. (One
          should be careful when defining the panel function
          on-the-fly.) 

  subset: logical or integer indexing vector (can be specified in terms
          of variables in 'data').  Only these rows of 'data' will be
          used for the plot.  If 'subscripts' is 'TRUE', the subscripts
          will provide indices to the rows of data before the
          subsetting is done.  Whether levels of factors in the data
          frame that are unused after the subsetting will be dropped
          depends on the 'drop.unused.levels' argument. 

    xlab: character string or expression (or a '"grob"') giving label
          for the x-axis.  Defaults to the expression for 'x' in
          'formula'.  Can be specified as 'NULL' to omit the label
          altogether.  Finer control is possible, as described in the
          entry for 'main', with the additional feature that if the
          'label' component is omitted from the list, it is replaced by
          the default 'xlab'. 

    xlim: Normally a numeric vector of length 2 (possibly a DateTime
          object) giving minimum and maximum 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"' or '"sliced"', in which case
          these are treated as if they were the corresponding limit
          components returned by prepanel calculations.

    ylab: character string or expression (or '"grob"') giving label for
          the y-axis.  Defaults to the expression for 'y' in 'formula'.
           Fine control is possible, see entry for 'xlab'. 

    ylim: similar to 'xlim', applied to the y-axis. 

drop.unused.levels: logical indicating whether the unused levels of
          factors will be dropped.  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 data variables respectively.  The default is
          given by 'lattice.getOption("drop.unused.levels")' , which is
          initially set to 'TRUE' for both components. 

par.settings: a list that could be supplied to 'trellis.par.set'. This
          enables the user to attach some display settings to the
          trellis object itself rather than change the settings
          globally.  When the object is printed, these settings are
          temporarily in effect for the duration of the plot, after
          which the settings revert back to whatever it was before. 

perm.cond: numeric 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 to 'aperm'. 

index.cond: While '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 the integer vector
          '1:nlevels(g_i)' (which can, among other things, repeat some
          of the 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 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.) For a
          single 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' method, both can be set to 'NULL',
          which reverts these back to their defaults. 

 default.scales : list giving the default values of 'scales' for a
          particular high level function.  This should not be of any
          interest to the normal user, but may be helpful when defining
          other functions that act as a wrapper to one of the high
          level lattice functions. 

     ...: other arguments, passed to the panel function.

          The arguments 'horizontal' and 'panel.groups' are documented
          here to avoid confusion, but they are actually not recognized
          by these high level functions.  Instead, they are passed
          along to the panel function, as are any other unrecognized
          arguments.

_D_e_t_a_i_l_s:

     All the functions documented here are generic, with the 'formula'
     method usually doing the actual work.  The structure of the plot
     that is produced is mostly controlled by the formula.  For each
     unique combination of the levels of the conditioning variables
     'g1, g2, ...', a separate panel is produced using the points
     '(x,y)' for the subset of the data (also called packet) defined by
     that combination.  The display can be though of as a 3-dimensional
     array of panels, consisting of one 2-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 panel.

     The coordinate system used by lattice by default is like a graph,
     with the origin at the bottom left, with axes increasing to left
     and up. 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.  One might wish to set a global
     preference for a 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))'.  In fact,
     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.
     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).

_V_a_l_u_e:

     An object of class '"trellis"'. The 'update' method can be used to
     update components of the object and the 'print' method (usually
     called by default) will plot it on an appropriate plotting device.

_N_o_t_e:

     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.

_A_u_t_h_o_r(_s):

     Deepayan Sarkar Deepayan.Sarkar@R-project.org

_S_e_e _A_l_s_o:

     'barchart.table', 'Lattice', 'print.trellis', 'shingle',
     'banking', 'reshape', 'panel.xyplot', 'panel.bwplot',
     'panel.barchart', 'panel.dotplot', 'panel.stripplot',
     'panel.superpose', 'panel.loess', 'panel.linejoin',
     'strip.default', 'simpleKey' 'trellis.par.set'

_E_x_a_m_p_l_e_s:

     require(stats)
     ## Tonga Trench Earthquakes
     Depth <- equal.count(quakes$depth, number=8, overlap=.1)
     xyplot(lat ~ long | Depth, data = quakes)
     update(trellis.last.object(), aspect = "iso")

     ## Examples with data from `Visualizing Data' (Cleveland)
     ## (obtained from Bill Cleveland's Homepage :
     ## http://cm.bell-labs.com/cm/ms/departments/sia/wsc/, also
     ## available at statlib)

     EE <- equal.count(ethanol$E, number=9, overlap=1/4)
     ## Constructing panel functions on the fly; prepanel
     xyplot(NOx ~ C | EE, data = ethanol,
            prepanel = function(x, y) prepanel.loess(x, y, span = 1),
            xlab = "Compression Ratio", ylab = "NOx (micrograms/J)",
            panel = function(x, y) {
                panel.grid(h=-1, v= 2)
                panel.xyplot(x, y)
                panel.loess(x,y, span=1)
            },
            aspect = "xy")


     ## with and without banking

     plot <- xyplot(sunspot.year ~ 1700:1988, xlab = "", type = "l",
                    scales = list(x = list(alternating = 2)),
                    main = "Yearly Sunspots")
     print(plot, position = c(0, .3, 1, .9), more = TRUE)
     print(update(plot, aspect = "xy", main = "", xlab = "Year"),
           position = c(0, 0, 1, .3))



     ## Multiple variables in formula for grouped displays

     xyplot(Sepal.Length + Sepal.Width ~ Petal.Length + Petal.Width | Species, 
            data = iris, scales = "free", layout = c(2, 2),
            auto.key = list(x = .6, y = .7, corner = c(0, 0)))

     ## user defined panel functions

     states <- data.frame(state.x77,
                          state.name = dimnames(state.x77)[[1]], 
                          state.region = state.region) 
     xyplot(Murder ~ Population | state.region, data = states, 
            groups = state.name, 
            panel = function(x, y, subscripts, groups)  
            ltext(x = x, y = y, label = groups[subscripts], cex=1,
                  fontfamily = "HersheySans"))

     barchart(yield ~ variety | site, data = barley,
              groups = year, layout = c(1,6),
              ylab = "Barley Yield (bushels/acre)",
              scales = list(x = list(abbreviate = TRUE,
                            minlength = 5)))
     barchart(yield ~ variety | site, data = barley,
              groups = year, layout = c(1,6), stack = TRUE, 
              auto.key = list(points = FALSE, rectangles = TRUE, 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)

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

