update.trellis            package:lattice            R Documentation

Retrieve and Update Trellis Object

Description:

     Update method for objects of class '"trellis"', and a way to
     retrieve the last printed trellis object (that was saved).

Usage:

     ## S3 method for class 'trellis':
     update(object,
            panel,
            aspect,
            as.table,
            between,
            key,
            auto.key,
            legend,
            layout,
            main,
            page,
            par.strip.text,
            prepanel,
            scales,
            skip,
            strip,
            strip.left,
            sub,
            xlab,
            xlim,
            ylab,
            ylim,
            par.settings,
            plot.args,
            lattice.options,
            index.cond,
            perm.cond,
            ...)

     ## S3 method for class 'trellis':
     t(x)

     ## S3 method for class 'trellis':
     x[i, j, ..., drop = FALSE]

     trellis.last.object(warn = TRUE, ...)

Arguments:

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

    warn: logical, whether to warn when no plot is saved. 

panel, aspect, as.table, between, key, auto.key, legend, layout,
main, page, par.strip.text, prepanel, scales, skip, strip,
strip.left, sub, xlab, xlim, ylab, ylim, par.settings, plot.args,
lattice.options, index.cond, perm.cond, ...: 
          arguments that will be used to update 'object'. See details
          below.  

Details:

     All high level lattice functions such as 'xyplot' produce an
     object of (S3) class '"trellis"', which is usually displayed by
     its 'print' method. However, the object itself can be manipulated
     and modified to a large extent using the 'update' method, and then
     re-displayed as needed.

     Most arguments to high level functions can also be supplied to the
     'update' method as well, with some exceptions. Generally speaking,
     anything that would needs to change the data within each panel is
     a no-no (this includes the 'formula, data, groups, subscripts' and
     'subset'). Everything else is technically game, though might not
     be implemented yet. If you find something missing that you wish to
     have, feel free to make a request.

     Not all arguments accepted by a Lattice function are processed by
     'update', but the ones listed above should work.  The purpose of
     these arguments are described in the help page for 'xyplot'.  Any
     other argument is added to the list of arguments to be passed to
     the 'panel' function. Because of their somewhat special nature,
     updates to objects produced by 'cloud' and 'wireframe' do not work
     very well yet.

     The '"["' method is a convenient shortcut for updating
     'index.cond'.  The 't' method is a convenient shortcut for
     updating 'perm.cond' in the special (but frequent) case where
     there are exactly two conditioning variables, when it has the
     effect of switching ('transposing') their order.

     The print method for '"trellis"' objects optionally saves the
     object after printing it.  If this feature is enabled,
     'trellis.last.object' can retrieve it.  Note that at most one
     object can be saved at a time.  If 'trellis.last.object' is called
     with arguments, these are used to update the retrieved object
     before returning it.

Value:

     An object of class 'trellis', by default plotted by
     'print.trellis'.  'trellis.last.object' returns 'NULL' is no saved
     object is available.

Author(s):

     Deepayan Sarkar Deepayan.Sarkar@R-project.org

See Also:

     'trellis.object', 'Lattice', 'xyplot'

Examples:

     spots <- by(sunspots, gl(235, 12, lab = 1749:1983), mean)
     old.options <- lattice.options(save.object = TRUE)
     xyplot(spots ~ 1749:1983, xlab = "", type = "l",
            scales = list(x = list(alternating = 2)),
            main = "Average Yearly Sunspots")
     update(trellis.last.object(), aspect = "xy")
     trellis.last.object(xlab = "Year")
     lattice.options(old.options)

