R: Retrieve and Update Trellis Object

C_06_update.trellis {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,
           ylab,
           xlab.top,
           ylab.right,
           xlim,
           ylim,
           xscale.components,
           yscale.components,
           axis,
           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(..., prefix)

### 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`.

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

### 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. By default, the last object plotted is retrieved, but if multiple objects are plotted on the current page, then others can be retrieved using the appropriate `prefix` argument. 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, labels = 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)

[Package lattice version 0.20-29 Index]