interaction {lattice} | R Documentation |
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.
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", "strip.left", "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(x, panel.number) trellis.panelArgs() trellis.currentLayout()
x, y |
variables defining the contents of the panel |
n |
the number of points to identify by default (overridden by a right click) |
labels |
an optional vector of labels associated with each point. |
offset |
the labels are printed either below, above, to the left or to the
right of the identified point, depending on the relative location of
the mouse click. The offset specifies (in "char" units) how
far from the identified point the labels should be printed.
|
threshold |
threshold in grid's "points" units. Points further than these
from the mouse click position are not considered
|
panel.args |
list that contains components names x (and usually y ),
to be used if x is missing. Typically, when called after
trellis.focus , this would appropriately be the arguments
passed to that panel.
|
name |
character string indicating which viewport or grob we are looking
for. Although these do not necessarily provide access to all
viewports and grobs created by a lattice plot, they cover most that
users might find interesting.
trellis.vpname and trellis.focus deal with viewport
names only, and only accept the values explicitly listed above.
trellis.grobname is meant to create names for grobs, and can
currently accept any value.
|
column, row |
integers, indicating position of the panel or strip that should be
assigned focus in the Trellis layout. Rows are usually calculated
from the bottom up, unless the plot was created with
as.table=TRUE
|
side |
character string, relevant only for legends (i.e. when
name="legend" ), indicating their position. Partial specification
is allowed, as long as it is unambiguous.
|
clip.off |
logical, whether clipping should be off, relevant when name
is "panel" or "strip" . This is necessary if axes are
to be drawn outside the panel or strip. Note that setting
clip.off=FALSE does not necessarily mean that clipping is on;
that is determined by conditions in effect during printing.
|
prefix |
character string acting as a prefix, meant to distinguish otherwise
equivalent viewports in different plots. This only becomes relevant
when a particular page is occupied by more than one plot. Defaults
to the value appropriate for the last "trellis" object printed, as
determined by the prefix argument in
print.trellis . Users should not usually need to
supply a value for this argument (see note below), however, if
supplied explicitly, this has to be a valid R symbol name (briefly,
it must start with a letter or a period followed by a letter) and
must not contain the grid path separator (currently "::" )
|
highlight |
logical, whether the viewport being assigned focus should be
highlighted. For trellis.focus , the default is TRUE
in interactive mode, and trellis.swich.focus by default
preserves the setting currently active.
|
panel.number |
integer, which panel to get data from. See xyplot for
details on how this is calculated
|
... |
graphical parameters. For panel.identify these are used for
labelling. For trellis.focus and trellis.switchFocus ,
these are used (in combination with lattice.options )
for highlighting the chosen viewport if so requested.
|
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.
It is quite common to have the layout of panels chosen when a
"trellis"
object is drawn, and not before then. Information on
the layout (specifically, how many rows and columns, and which packet
belongs in which position in this layout) is retained for the last
"trellis"
object plotted, and is available through
trellis.currentLayout
.
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.
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.currentLayout
returns a matrix with as many rows and
columns as in the layout of panels in the last plot. Entries in the
matrix are integer indices indicating which packet (panel data)
occupies that position, with 0 indicating the absence of a panel.
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.
The viewports created by lattice is accessible to the user only upto a
certain extent, as described above. In particular,
trellis.focus
can only be used to manipulate the last plot
drawn. For full flexibility, use appropriate functions from the grid
package directly. For example,
current.vpTree
can be used to
inspect the current viewport tree and
seekViewport
or
downViewport
can be used to navigate to
these viewports. For such usage, trellis.vpname
and
trellis.grobname
(with a non-default prefix
argument)
provides a portable way to access the appropriate viewports and grobs
by name.
Deepayan Sarkar Deepayan.Sarkar@R-project.org
identify
, Lattice
,
print.trellis
,
current.vpTree
,
viewports
## Not run: xyplot(1:10 ~ 1:10) trellis.focus("panel", 1, 1) panel.identify() ## End(Not run) 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() ## choosing loess smoothing parameter p <- xyplot(dist ~ speed, cars) panel.loessresid <- function(x = panel.args$x, y = panel.args$y, span, panel.args = trellis.panelArgs()) { fm <- loess(y ~ x, span = span) xgrid <- do.breaks(current.panel.limits()$xlim, 50) ygrid <- predict(fm, newdata = data.frame(x = xgrid)) panel.lines(xgrid, ygrid) pred <- predict(fm) ## center residuals so that they fall inside panel resids <- y - pred + mean(y) fm.resid <- loess.smooth(x, resids, span = span) ##panel.points(x, resids, col = 1, pch = 4) panel.lines(fm.resid, col = 1) } spans <- c(0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8) update(p, index.cond = list(rep(1, length(spans)))) panel.locs <- trellis.currentLayout() i <- 1 for (row in 1:nrow(panel.locs)) for (column in 1:ncol(panel.locs)) if (panel.locs[row, column] > 0) { trellis.focus("panel", row = row, column = column, highlight = FALSE) panel.loessresid(span = spans[i]) grid::grid.text(paste("span = ", spans[i]), x = 0.25, y = 0.75, default.units = "npc") trellis.unfocus() i <- i + 1 }