spc.identify {hyperSpec}

Identifying Spectra and Spectral Data Points This function allows to identify the spectrum and the wavelength of a point in a plot produced by plotspc.

Description

This function first finds the spectrum with a point closest to the clicked position (see locator). The distance to the clicked point is evaluated relative to the size of the tolerance window.

Usage

spc.identify(
  x,
  y = NULL,
  wavelengths = NULL,
  ispc = NULL,
  tol.wl = diff(range(x))/200,
  tol.spc = diff(range(y))/50,
  point.fn = spc.point.max,
  formatter = spc.label.default,
  ...,
  cex = 0.7,
  adj = c(0, 0.5),
  srt = 90,
  warn = TRUE
)

spc.point.max(wl, spc, wlclick)

spc.point.default(wl, spc, wlclick)

spc.point.min(wl, spc, wlclick)

spc.point.sqr(wl, spc, wlclick, delta = 1L)

spc.label.default(ispc, wl, spc, digits = 3)

spc.label.wlonly(ispc, wl, spc, digits = 3)

Arguments

x

either the abscissa coordinates or the list returned by plotspc

y

the ordinate values. Giving y will override any values from x$y.

wavelengths

the wavelengths for the data points. Giving wavelengths will override any values from x$wavelengths.

ispc

if a selection of spectra was plotted, their indices can be given in ispc. In this case ispc [i] is returned rather than i.

tol.wl, tol.spc

tolerance in wavelength and spectral intensity to search around the clicked point. See details.

point.fn

function (wl, spc, wlclick) to determine the actual point to label, see details.

formatter

function (i, wl, spc) that produces the labels. If NULL, no labels are displayed.

...

passed to text in order to produce the labels

cex, adj, srt

see par

warn

Should the user be warned if no point is in the considered window? In addition, see the discussion of option debuglevel in the details.

If FALSE, the resulting data.frame will have a row of NAs instead.

wl

the wavelength to label

spc

the intensity to label

wlclick

the clicked wavelength

delta

spc.point.sqr fits the parabola in the window wlclick \pm delta points.

digits

how many digits of the wavelength should be displayed?

Details

In a second step, max.fn searches for the actual point to label within the specified wavelength window of that spectrum. This allows to label maxima (or minima) without demanding too precise clicks. Currently, the following functions to determine the precise point:

spc.point.default	uses the clicked wavelength together with its spectral intensity
spc.point.max	the point with the highest intensity in the wavelength window
spc.point.min	the point with the lowest intensity in the wavelength window
spc.point.sqr	maximum of a parabola fit throug the point with highest intensity and the two surrounding points

point.fn is called with the arguments wl containing the considered wavelength window, spc the respective intensities of the closest spectrum, and wlclick the wavelength that was clicked. They return a vector of two elements (wavelength and intensity).

As a last step, a label for the point produced by formatter and plotted using text. Currently, the following formatters are available:

spc.label.default	spectrum number, wavelength
spc.label.wlonly	wavelength

formatter functions receive the number of the spectrum ispc, the wavelength wl, and the spectral intensity spc and produce a character variable suitable for labelling. The predefined formatters surround the label text by spaces in order to easily have an appropriate offset from the point of the spectrum.

The warning issued if no spectral point is inside the tolerance window may be switched of by warn = FALSE. In that case, the click will produce a row of NAs in the resulting data.frame.

spc.identify uses option debuglevel to determine whether debugging output should be produced. debuglevel == 2 will plot the tolerance window for every clicked point, debuglevel == 1 will plot the tolerance window only if no data point was inside. See hyperSpec options for details about retrieving and setting options.

You may want to adjust the plot's ylim to ensure that the labels are not clipped. As a dirty shortcut, xpd = NA may help.

Value

a data.frame with columns

ispc

spectra indices of the identified points, i.e. the rows of the hyperSpec object that was plotted.

If ispc is given, ispc [i] is returned rather than i.

wavelengths

the wavelengths of the identified points

spc

the intensities of the identified points

Author(s)

C. Beleites

See Also

locator, plotspc, hyperSpec options

map.identify map.sel.poly

Examples

if (interactive ()){
ispc <- sample (nrow (laser), 10)
ispc

identified <- spc.identify (plotspc (laser[ispc]))

## convert to the "real" spectra indices
ispc [identified$ispc]
identified$wl
identified$spc

## allow the labels to be plotted into the plot margin
spc.identify (plotspc (laser[ispc]), ispc = ispc, xpd = NA) 

spc.identify (plotspc (paracetamol, xoffset = 1100,
              wl.range = c (600 ~ 1700, 2900 ~ 3150)),
              formatter = spc.label.wlonly)

## looking for minima
spc.identify (plot (-paracetamol, wl.reverse = TRUE),
              point.fn = spc.point.min, adj = c (1, 0.5))

}