identify              package:graphics              R Documentation

_I_d_e_n_t_i_f_y _P_o_i_n_t_s _i_n _a _S_c_a_t_t_e_r _P_l_o_t

_D_e_s_c_r_i_p_t_i_o_n:

     'identify' reads the position of the graphics pointer when the
     (first) mouse button is pressed.  It then searches the coordinates
     given in 'x' and 'y' for the point closest to the pointer. If this
     point is close enough to the pointer, its index will be returned
     as part of the value of the call.

_U_s_a_g_e:

     identify(x, ...)

     ## Default S3 method:
     identify(x, y = NULL, labels = seq_along(x), pos = FALSE,
              n = length(x), plot = TRUE, atpen = FALSE, offset = 0.5,
              tolerance = 0.25, ...)

_A_r_g_u_m_e_n_t_s:

     x,y: coordinates of points in a scatter plot.  Alternatively, any
          object which defines coordinates (a plotting structure, time
          series etc: see 'xy.coords') can be given as 'x', and 'y'
          left missing.

  labels: an optional character vector giving labels for the points. 
          Will be coerced using 'as.character', and recycled if
          necessary to the length of 'x'.  Excess labels will be
          discarded, with a warning.

     pos: if 'pos' is 'TRUE', a component is added to the return value
          which indicates where text was plotted relative to each
          identified point: see Value.

       n: the maximum number of points to be identified.

    plot: logical: if 'plot' is 'TRUE', the labels are printed near the
          points and if 'FALSE' they are omitted.

   atpen: logical: if 'TRUE' and 'plot = TRUE', the lower-left corners
          of the labels are plotted at the points clicked rather than
          relative to the points.

  offset: the distance (in character widths) which separates the label
          from identified points.  Negative values are allowed.  Not
          used if 'atpen = TRUE'.

tolerance: the maximal distance (in inches) for the pointer to be
          'close enough' to a point.

     ...: further arguments passed to 'par' such as 'cex', 'col' and
          'font'.

_D_e_t_a_i_l_s:

     'identify' is a generic function, and only the default method is
     described here.

     'identify' is only supported on screen devices such as 'X11',
     'windows' and 'quartz'.  On other devices the call will do
     nothing.

     Clicking near (as defined by 'tolerance') a point adds it to the
     list of identified points.  Points can be identified only once,
     and if the point has already been identified or the click is not
     near any of the points a message is printed immediately on the R
     console.

     If 'plot' is 'TRUE', the point is labelled with the corresponding
     element of 'labels'.  If 'atpen' is false (the default) the labels
     are placed below, to the left, above or to the right of the
     identified point, depending on where the pointer was relative to
     the point.  If 'atpen' is true, the labels are placed with the
     bottom left of the string's box at the pointer.

     For the usual 'X11' device the identification process is
     terminated by pressing any mouse button other than the first. For
     the 'quartz' device the process is terminated by pressing either
     the pop-up menu equivalent (usually second mouse button or
     'Ctrl'-click) or the 'ESC' key.

     On most devices which support 'identify', successful selection of
     a point is indicated by a bell sound unless 'options(locatorBell =
     FALSE)' has been set.

     If the window is resized or hidden and then exposed before the
     identification process has terminated, any labels drawn by
     'identify' will disappear.  These will reappear once the
     identification process has  terminated and the window is resized
     or hidden and exposed again. This is because the labels drawn by
     'identify' are not recorded in the device's display list until the
     identification process has terminated.

     If you interrupt the 'identify' call this leaves the graphics
     device in an undefined state, with points labelled but labels not
     recorded in the display list.  Copying a device in that state will
     give unpredictable results.

_V_a_l_u_e:

     If 'pos' is 'FALSE', an integer vector containing the indices of
     the identified points, in the order they were identified.

     If 'pos' is 'TRUE', a list containing a component 'ind',
     indicating which points were identified and a component 'pos',
     indicating where the labels were placed relative to the identified
     points (1=below, 2=left, 3=above, 4=right and 0=no offset, used if
     'atpen = TRUE').

_T_e_c_h_n_i_c_a_l_i_t_i_e_s:

     The algorithm used for placing labels is the same as used by
     'text' if 'pos' is specified there, the difference being that the
     position of the pointer relative the identified point determines
     'pos' in 'identify'.

     For labels placed to the left of a point, the right-hand edge of
     the string's box is placed 'offset' units to the left of the
     point, and analogously for points to the right.  The baseline of
     the text is placed below the point so as to approximately centre
     string vertically. For labels placed above or below a point, the
     string is centered horizontally on the point.  For labels placed
     above, the baseline of the text is placed 'offset' units above the
     point, and for those placed below, the baseline is placed so that
     the top of the string's box is approximately 'offset' units below
     the point.  If you want more precise placement (e.g. centering)
     use 'plot = FALSE' and plot via 'text' or 'points': see the
     examples.

_R_e_f_e_r_e_n_c_e_s:

     Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) _The New S
     Language_. Wadsworth & Brooks/Cole.

_S_e_e _A_l_s_o:

     'locator', 'text'.

_E_x_a_m_p_l_e_s:

     ## A function to use identify to select points, and overplot the
     ## points with another symbol as they are selected
     identifyPch <- function(x, y=NULL, n=length(x), pch=19, ...)
     {
         xy <- xy.coords(x, y); x <- xy$x; y <- xy$y
         sel <- rep(FALSE, length(x)); res <- integer(0)
         while(sum(sel) < n) {
             ans <- identify(x[!sel], y[!sel], n=1, plot=FALSE, ...)
             if(!length(ans)) break
             ans <- which(!sel)[ans]
             points(x[ans], y[ans], pch = pch)
             sel[ans] <- TRUE
             res <- c(res, ans)
         }
         res
     }