lattice (version 0.11-8)

interaction: Functions to Interact with Lattice Plots

Description

The classic Trellis paradigm is to plot the whole object at once, without the possibility of interacting with it afterwards. However, by keeping track of the grid viewports where the panels and strips are drawn, it is possible to go back to them afterwards and enhance them one panel at a time. These functions provide convenient interfaces to help in this. Note that these are still experimental and the exact details may change in future.

Usage

panel.identify(x, y = NULL, labels = seq(along = x),
               n = length(x), offset = 0.5,
               threshold = 18,
               panel.args = trellis.panelArgs(),
               ...)
trellis.vpname(name = c("position", "split", "split.location", "toplevel",
               "panel", "strip", "legend", "main", "sub", "xlab", "ylab", "page"),
               column, row,
               side = c("left", "top", "right", "bottom", "inside"),
               clip.off = FALSE, prefix)
trellis.grobname(name, prefix)
trellis.focus(name, column, row, side, clip.off,
              highlight = interactive(), ...)
trellis.switchFocus(name, side, clip.off, highlight, ...)
trellis.unfocus()
trellis.panelArgs()
trellis.panelArgs(x, panel.number)

Value

panel.identify returns an integer vector containing the indexes of the identified points. The equivalent of identify with pos=TRUE is not yet implemented, but can be considered for addition if requested.

trellis.panelArgs returns a named list of arguments that were avaliable to the panel function for the chosen panel.

trellis.vpname and trellis.grobname return character strings.

synopsis

trellis.panelArgs(x, panel.number) trellis.vpname(name = c("position", "split", "split.location", "toplevel", "panel", "strip", "legend", "main", "sub", "xlab", "ylab", "page"), column = lattice.getStatus("current.focus.column"), row = lattice.getStatus("current.focus.row"), side = c("left", "top", "right", "bottom", "inside"), clip.off = FALSE, prefix = lattice.getStatus("current.prefix"))

Details

panel.identify is similar to identify. When called, it waits for the user to identify points (in the panel being drawn) via mouse clicks. Clicks other than left-clicks terminate the procedure. Although it is possible to call it as part of the panel function, it is more typical to use it to identify points after plotting the whole object, in which case a call to trellis.focus first is necessary.

The process of printing (plotting) a Trellis object builds up a grid layout with named viewports which can then be accessed to modify the plot further. While full flexibility can only be obtained by using grid functions directly, a few lattice functions are available for the more common tasks.

trellis.focus can be used to move to a particular panel or strip, identified by its position in the array of panels. It can also be used to focus on the viewport corresponding to one of the labels or a legend, though such usage would be less useful. The exact viewport is determined by the name along with the other arguments, not all of which are relevant for all names. Note that when more than one object is plotted on a page, trellis.focus will always go to the plot that was created last. For more flexibility, use grid functions directly (see note below).

After a successful call to trellis.focus, the desired viewport (typically panel or strip area) will be made the `current' viewport (plotting area), which can then be enhanced by calls to standard lattice panel functions as well as grid functions.

trellis.unfocus unsets the focus, and makes the top level viewport the current viewport.

trellis.switchFocus is a convenience function to switch from one viewport to another, while preserving the current row and column. Although the rows and columns only make sense for panels and strips, they would be preserved even when the user switches to some other viewport (where row/column is irrelevant) and then switches back. Once a panel or strip is in focus, trellis.panelArgs can be used to retrieve the arguments that were available to the panel function at that position. trellis.panelArgs can also, more generally, retrieve the panel arguments from any ``trellis'' object. Note that for this usage, one needs to specify the panel.number (as described under the panel entry in xyplot) and not the position in the layout, because a layout determines the panel only after the object has been printed.

It is usually not necessary to call trellis.vpname and trellis.grobname directly. However, they can be useful in generating appropriate names in a portable way when using grid functions to interact with the plots directly, as described in the note below.

See Also

identify, Lattice, print.trellis, current.vpTree, viewports

Examples

xyplot(1:10 ~ 1:10)
trellis.focus("panel", 1, 1)
panel.identify()

xyplot(Petal.Length ~ Sepal.Length | Species, iris, layout = c(2, 2))
Sys.sleep(1)

trellis.focus("panel", 1, 1)
do.call("panel.lmline", trellis.panelArgs())
Sys.sleep(0.5)
trellis.unfocus()

trellis.focus("panel", 2, 1)
do.call("panel.lmline", trellis.panelArgs())
Sys.sleep(0.5)
trellis.unfocus()

trellis.focus("panel", 1, 2)
do.call("panel.lmline", trellis.panelArgs())
Sys.sleep(0.5)
trellis.unfocus()