% File src/library/graphics/man/identify.Rd
% Part of the R package, https://www.R-project.org
% Copyright 1995-2017 R Core Team
% Distributed under GPL 2 or later

\name{identify}
\alias{identify}
\alias{identify.default}
\title{Identify Points in a Scatter Plot}
\usage{
identify(x, \dots)

\method{identify}{default}(x, y = NULL, labels = seq_along(x), pos = FALSE,
         n = length(x), plot = TRUE, atpen = FALSE, offset = 0.5,
         tolerance = 0.25, order = FALSE, \dots)
}
\arguments{
  \item{x, y}{coordinates of points in a scatter plot.  Alternatively, any
    object which defines coordinates (a plotting structure, time
    series etc: see \code{\link{xy.coords}}) can be given as \code{x},
    and \code{y} left missing.}
  \item{labels}{an optional character vector giving labels for the
    points.  Will be coerced using \code{\link{as.character}}, and
    recycled if necessary to the length of \code{x}.  Excess labels will
    be discarded, with a warning.}
  \item{pos}{if \code{pos} is \code{TRUE}, a component is added to the
    return value which indicates where text was plotted relative to each
    identified point: see Value.}
  \item{n}{the maximum number of points to be identified.}
  \item{plot}{logical: if \code{plot} is \code{TRUE}, the labels are
    printed near the points and if \code{FALSE} they are omitted.}
  \item{atpen}{logical: if \code{TRUE} and \code{plot = TRUE}, the
    lower-left corners of the labels are plotted at the points clicked
    rather than relative to the points.}
  \item{offset}{the distance (in character widths) which separates the
    label from identified points.  Negative values are allowed.  Not
    used if \code{atpen = TRUE}.}
  \item{tolerance}{the maximal distance (in inches) for the pointer to be
    \sQuote{close enough} to a point.}
  \item{order}{if \code{order} is \code{TRUE}, a component is added to the
    return value which indicates the order in which points were
    identified: see Value.}
  \item{\dots}{further arguments passed to \code{\link{par}} such as
    \code{cex}, \code{col} and \code{font}.}
}
\description{
  \code{identify} reads the position of the graphics pointer when the
  (first) mouse button is pressed.  It then searches the coordinates
  given in \code{x} and \code{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.
}
\details{
  \code{identify} is a generic function, and only the default method is
  described here.

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

  Clicking near (as defined by \code{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 \code{plot} is \code{TRUE}, the point is labelled with the
  corresponding element of \code{labels}.  If \code{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 \code{atpen} is true, the
  labels are placed with the bottom left of the string's box at the
  pointer.

#ifdef unix
  For the usual \code{\link{X11}} device the identification process is
  terminated by pressing any mouse button other than the first.
  For the \code{\link{quartz}} device the process is terminated by
  pressing either the pop-up menu equivalent (usually second mouse
  button or \code{Ctrl}-click) or the \code{ESC} key.
#endif
#ifdef windows
  The identification process is terminated by clicking the second button
  and selecting \sQuote{Stop} from the menu, or from the \sQuote{Stop}
  menu on the graphics window.
#endif

  On most devices which support \code{identify}, successful selection of
  a point is indicated by a bell sound unless
  \code{\link{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 \code{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 \code{identify} are not
  recorded in the device's display list until the identification process has
  terminated.

  If you interrupt the \code{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
#ifdef windows
  (e.g., saving the plot from the window's menu)
#endif
  will give unpredictable results.
}
\value{
  If both \code{pos} and \code{order} are \code{FALSE},
  an integer vector containing the
  indices of the identified points.

  If either of \code{pos} or \code{order} is \code{TRUE},
  a list containing a component
  \code{ind}, indicating which points were identified and (if
  \code{pos} is \code{TRUE}) a component
  \code{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 \code{atpen = TRUE}) and (if \code{order} is \code{TRUE})
  a component \code{order}, indicating the order in which points
  were identified.
}
\section{Technicalities}{
  The algorithm used for placing labels is the same as used by
  \code{text} if \code{pos} is specified there, the difference being
  that the position of the pointer relative the identified point
  determines \code{pos} in \code{identify}.

  For labels placed to the left of a point, the right-hand edge of the
  string's box is placed \code{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 \code{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 \code{offset} units below the
  point.  If you want more precise placement (e.g., centering) use
  \code{plot = FALSE} and plot via \code{\link{text}} or
  \code{\link{points}}: see the examples.
}
\references{
  Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
  \emph{The New S Language}.
  Wadsworth & Brooks/Cole.
}
\seealso{
  \code{\link{locator}}, \code{\link{text}}.

  \code{\link{dev.capabilities}} to see if it is supported.
}
\examples{
## 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), plot = FALSE, pch = 19, ...)
{
    xy <- xy.coords(x, y); x <- xy$x; y <- xy$y
    sel <- rep(FALSE, length(x))
    while(sum(sel) < n) {
        ans <- identify(x[!sel], y[!sel], labels = which(!sel), n = 1, plot = plot, ...)
        if(!length(ans)) break
        ans <- which(!sel)[ans]
        points(x[ans], y[ans], pch = pch)
        sel[ans] <- TRUE
    }
    ## return indices of selected points
    which(sel)
}

if(dev.interactive()) { ## use it
  x <- rnorm(50); y <- rnorm(50)
  plot(x,y); identifyPch(x,y) # how fast to get all?
}

}
\keyword{iplot}