identify              package:graphics              R Documentation

Identify Points in a Scatter Plot

Description:

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

Usage:

     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, ...)

Arguments:

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

  labels: an optional character vector, the same length as 'x' and 'y',
          giving labels for the points.  Will be coerced using
          'as.character'.

     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 at 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.  Ignored if 'atpen = TRUE' or 'pos =
          0'.

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

Details:

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

     If 'plot' is 'TRUE', the point is labelled with the corresponding
     element of 'text'. The labels are placed below, to the left, above
     or to the right of the identified point, depending on where the
     cursor was relative to the point.

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

Value:

     If 'pos' is 'FALSE', an integer vector containing the indexes of
     the identified points.

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

References:

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

See Also:

     'locator'

