interaction             package:lattice             R Documentation

_F_u_n_c_t_i_o_n_s _t_o _I_n_t_e_r_a_c_t _w_i_t_h _L_a_t_t_i_c_e _P_l_o_t_s

_D_e_s_c_r_i_p_t_i_o_n:

     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.

_U_s_a_g_e:

     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, packet.number)
     trellis.panelArgs()
     trellis.currentLayout()

_A_r_g_u_m_e_n_t_s:

    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.switchFocus' by default
          preserves the setting currently active. 

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

_D_e_t_a_i_l_s:

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

_V_a_l_u_e:

     '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
     available to the panel function for the chosen panel.

     'trellis.vpname' and 'trellis.grobname' return character strings.

_N_o_t_e:

     The viewports created by lattice is accessible to the user only up
     to 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.

_A_u_t_h_o_r(_s):

     Deepayan Sarkar Deepayan.Sarkar@R-project.org

_S_e_e _A_l_s_o:

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

_E_x_a_m_p_l_e_s:

     ## 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
     }

