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.
identify(x, …)# S3 method for default
identify(x, y = NULL, labels = seq_along(x), pos = FALSE,
n = length(x), plot = TRUE, atpen = FALSE, offset = 0.5,
tolerance = 0.25, order = FALSE, …)
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.
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.
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.
the maximum number of points to be identified.
logical: if plot is TRUE, the labels are
printed near the points and if FALSE they are omitted.
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.
the distance (in character widths) which separates the
label from identified points. Negative values are allowed. Not
used if atpen = TRUE.
the maximal distance (in inches) for the pointer to be ‘close enough’ to a point.
if order is TRUE, a component is added to the
return value which indicates the order in which points were
identified: see Value.
further arguments passed to par such as
cex, col and font.
If both pos and order are FALSE,
an integer vector containing the
indices of the identified points.
If either of pos or order is TRUE,
a list containing a component
ind, indicating which points were identified and (if
pos is TRUE) 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) and (if order is TRUE)
a component order, indicating the order in which points
were identified.
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.
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.
The identification process is terminated by clicking the second button
and selecting ‘Stop’ from the menu, or from the ‘Stop’
menu on the graphics window.
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
(e.g., saving the plot from the window's menu)
will give unpredictable results.
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole.
dev.capabilities to see if it is supported.
# NOT RUN {
## 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?
}
# }
Run the code above in your browser using DataLab