Plot a map and identify/select spectra in the map

lattice::levelplot() functions for hyperSpec objects. An image or map of a summary value of each spectrum is plotted. Spectra may be identified by mouse click.

plotmap(object, model = spc ~ x * y, func = mean, func.args = list(), ...)

# S4 method for formula,hyperSpec
levelplot(
  x,
  data,
  transform.factor = TRUE,
  ...,
  contour = FALSE,
  useRaster = !contour
)

# S4 method for hyperSpec,missing
levelplot(x, data, ...)

map.identify(
  object,
  model = spc ~ x * y,
  voronoi = FALSE,
  ...,
  tol = 0.02,
  warn = TRUE
)

plotvoronoi(object, model = spc ~ x * y, use.tripack = FALSE, mix = FALSE, ...)

Arguments

object, data	the `hyperSpec` object
model, x	formula specifying the columns of object that are to be displayed by `lattice::levelplot()`
func, func.args	Before plotting, `plotmap` applies function `func` with the arguments given in the list `func.args` to each of the spectra. Thus a single summary value is displayed for each of the spectra. This can be suppressed manually by setting `func` to NULL. It is automatically suppressed if `.wavelength` appears in the formula.
...	further arguments are passed down the call chain, and finally to `lattice::levelplot()`
transform.factor	If the color-coded variable is a factor, should `trellis.factor.key()` be used to compute the color coding and legend?
contour, useRaster	see `lattice::levelplot()`
voronoi	Should the plot for identifying spectra by mouse click be produced by `plotmap` (default) or `plotvoronoi`?
tol	tolerance for `map.identify` as fraction of the viewport (i.e. in "npc" units)
warn	should a warning be issued if no point is within the specified tolerance? See also details.
use.tripack	Whether package tripack should be used for calculating the voronoi polygons. If `FALSE`, package deldir is used instead. See details.
mix	For Voronoi plots using package tripack, I experienced errors if the data was spatially ordered. Randomly rearranging the rows of the hyperSpec object circumvents this problem.

Value

map.identify returns a vector of row indices into object of the clicked points.

The other functions return a lattice object.

Details

The model can contain the special column name .wavelength to specify the wavelength axis.

plotmap, map.identify, and the levelplot methods internally use the same gateway function to lattice::levelplot(). Thus transform.factor can be used with all of them and the panel function defaults to lattice::panel.levelplot.raster() for all three. Two special column names, .rownames and .wavelength may be used.

levelplot plots the spectra matrix.

plotvoronoi calls plotmap with different default settings, namely the panel function defaults to latticeExtra::panel.voronoi(). latticeExtra::panel.voronoi() depends on either of the packages 'tripack' or 'deldir' being installed. For further information, please consult the help page of latticeExtra::panel.voronoi(). On the faux_cell() data set, plotmap is roughly 5 times faster than plotvoronoi using tripack, and ca. 15 times faster than plotvoronoi using deldir. Package tripack, however, is free only for non-commercial use. Also, it seems that tripack version hang (R running at full CPU power, but not responding nor finishing the calculation) for certain data sets. In this case, mix = TRUE may help.

map.identify calls plotmap and plotvoronoi, respectively and waits for (left) mouse clicks on points. Other mouse clicks end the input.

Unlike lattice::panel.identify(), the indices returned by map.identify are in the same order as the points were clicked. Also, multiple clicks on the same point are returned as multiple entries with the same index.

map.identify uses option debuglevel similar to spc.identify(): debuglevel == 1 will plot the tolerance window if no data point was inside (and additionally labels the point) while debuglevel == 2 will always plot the tolerance window.

The map.sel.* functions offer further interactive selection, see map.sel.poly().

Author

C. Beleites

Examples

if (FALSE) {
vignette(plotting)
vignette(hyperSpec)
}

levelplot(spc ~ y * x, faux_cell[, , 1003]) # properly rotated
#> Warning: device support for raster images unknown, ignoring 'raster=TRUE'
plotmap(faux_cell[, , 1003])
#> Warning: device support for raster images unknown, ignoring 'raster=TRUE'

# plot spectra matrix
levelplot(spc ~ .wavelength * t, laser, contour = TRUE, col = "#00000080")
# see also plotmat

plotmap(faux_cell, region ~ x * y)
#> Warning: device support for raster images unknown, ignoring 'raster=TRUE'

# Voronoi plots
smpl <- sample(faux_cell, 300)
plotmap(smpl, region ~ x * y)
#> Warning: device support for raster images unknown, ignoring 'raster=TRUE'
if (require(tripack)) {
  plotvoronoi(smpl, region ~ x * y)
}
#> Loading required package: tripack
#> Loading required namespace: deldir
#> Warning: device support for raster images unknown, ignoring 'raster=TRUE'
if (require(deldir)) {
  plotvoronoi(smpl, region ~ x * y,
    use.tripack = FALSE
  )
}
#> Loading required package: deldir
#> deldir 0.2-10      Nickname: "Morpheus and Euripides"
#> 
#>      Note 1: As of version 0.2-1, error handling in this 
#>      package was amended to conform to the usual R protocol. 
#>      The deldir() function now actually throws an error 
#>      when one occurs, rather than displaying an error number 
#>      and returning a NULL.
#>  
#>      Note 2:  As of version 0.1-29 the arguments "col" 
#>      and "lty" of plot.deldir() had their names changed to 
#>      "cmpnt_col" and "cmpnt_lty" respectively basically 
#>      to allow "col" and and "lty" to be passed as "..." 
#>      arguments.
#>  
#>      Note 3: As of version 0.1-29 the "plotit" argument 
#>      of deldir() was changed to (simply) "plot".
#>  
#>      See the help for deldir() and plot.deldir().
#> Warning: device support for raster images unknown, ignoring 'raster=TRUE'