plotspc: Plotting Spectra Plot the spectra of a 'hyperSpec' object,...
In hyperSpec: Work with Hyperspectral Data, i.e. Spectra + Meta Information (Spatial, Time, Concentration, ...)

Description Usage Arguments Details Value Author(s) See Also Examples

This is hyperSpec's main plotting function for spectra plots.

Usually, the stacked argument of plotspc will do fine, but if you need fine control over the stacking, you may calculate the y offsets yourself.

plotspc(
  object,
  wl.range = TRUE,
  wl.index = FALSE,
  wl.reverse = FALSE,
  spc.nmax = hy.getOption("plot.spc.nmax"),
  func = NULL,
  func.args = list(),
  stacked = NULL,
  stacked.args = list(),
  add = FALSE,
  bty = "l",
  plot.args = list(),
  col = "black",
  lines.args = list(),
  xoffset = 0,
  yoffset = 0,
  nxticks = 10,
  axis.args = list(),
  break.args = list(),
  title.args = list(),
  fill = NULL,
  fill.col = NULL,
  border = NA,
  polygon.args = list(),
  zeroline = list(lty = 2, col = col),
  debuglevel = hy.getOption("debuglevel")
)

stacked.offsets(
  x,
  stacked = TRUE,
  min.zero = FALSE,
  add.factor = 0.05,
  add.sum = 0,
  .spc = NULL,
  debuglevel = hy.getOption("debuglevel")
)

`object`	the `hyperSpec` object
`wl.range`	the wavelength range to be plotted. Either a numeric vector or a list of vectors with different wavelength ranges to be plotted separately. The values can be either wavelengths or wavelength indices (according to `wl.index`).
`wl.index`	if `TRUE`, `wl.range` is considered to give column indices into the spectra matrix. Defaults to specifying wavelength values rather than indices.
`wl.reverse`	if `TRUE`, the wavelength axis is plotted backwards.
`spc.nmax`	maximal number of spectra to be plotted (to avoid accidentally plotting of large numbers of spectra).
`func`	a function to apply to each wavelength in order to calculate summary spectra such as mean, min, max, etc.
`func.args`	`list` with furter arguments for `func`
`stacked`	if not `NULL`, a "stacked" plot is produced, see the example. `stacked` may be `TRUE` to stack single spectra. A numeric or factor is interpreted as giving the grouping, character is interpreted as the name of the extra data column that holds the groups.
`stacked.args`	a list with further arguments to `stacked.offsets`.
`add`	if `TRUE`, the output is added to the existing plot
`bty`	see `par`
`plot.args`	`list` with further arguments to `plot`
`col`	see `par`. `col` might be a vector giving individual colors for the spectra.
`lines.args`	list with further arguments to `lines`. `lines.args$type` defaults to "l".
`xoffset`	vector with abscissa offsets for each of the `wl.range`s. If it has one element less than there are `wl.range`s, 0 is padded at the beginning. The values are interpreted as the distance along the wavelength axis that the following parts of the spectra are shifted towards the origin. E.g. if `wl.range = list (600 ~ 1800, 2800 ~ 3200)`, `xoffset = 750` would result in a reasonable plot. See also the examples.
`yoffset`	ordinate offset values for the spectra. May be offsets to stack the spectra (`stacked.offsets`). Either one for all spectra, one per spectrum or one per group in `stacked`.
`nxticks`	hint how many tick marks the abscissa should have.
`axis.args`	`list` with further arguments for `axis`. `axis.args$x` should contain arguments for plotting the abscissa, `axis.args$y` those for the ordinate (again as `lists`).
`break.args`	list with arguments for `axis.break`.
`title.args`	list with further arguments to `title`. `title.args` may contain two lists, `$x`, and `$y` to set parameters individually for each axis.
`fill`	if not `NULL`, the area between the specified spectra is filled with color `col`. The grouping can be given as factor or numeric, or as a character with the name of the extra data column to use. If a group contains more than 2 spectra, the first and the last are used. If `TRUE` spectra n and nrow (spc) - n build a group.
`fill.col`	character vector with fill color. Defaults to brightened colors from `col`.
`border`	character vector with border color. You will need to set the line color `col` to `NA` in order see the effect.
`polygon.args`	list with further arguments to `polygon` which draws the filled areas.
`zeroline`	`NA` or a list with arguments `abline`, used to plot line (s) marking I = 0. `NA` suppresses plotting of the line. The line is by default turned off if `yoffset` is not 0.
`debuglevel`	if > 0, additional debug output is produced, see `options` for details
`x`	a `hyperSpec` object
`min.zero`	if `TRUE`, the lesser of zero and the minimum intensity of the spectrum is used as minimum.
`add.factor, add.sum`	proportion and absolute amount of space that should be added.
`.spc`	for internal use. If given, the ranges are evaluated on `.spc`. However, this may change in future.

New plots are created by plot, but the abscissa and ordinate are drawn separately by axis. Also, title is called explicitly to set up titles and axis labels. This allows fine-grained customization of the plots.

If package plotrix is available, its function axis.break is used to produce break marks for cut wavelength axes.

Empty levels of the stacking factor are dropped (as no stacking offset can be calculated in that case.)

plotspc invisibly returns a list with

`x`	the abscissa coordinates of the plotted spectral data points
`y`	a matrix the ordinate coordinates of the plotted spectral data points
`wavelengths`	the wavelengths of the plotted spectral data points

This can be used together with spc.identify.

a list containing

`offsets`	numeric with the yoffset for each group in `stacked`
`groups`	numeric with the group number for each spectrum
`levels`	if `stacked` is a factor, the levels of the groups

C. Beleites

plot, axis, title, lines, polygon, par for the description of the respective arguments.

axis.break for cut marks

See plot for some predefined spectra plots such as mean spectrum +/- one standard deviation and the like.

identify and locator about interaction with plots.

plotspc

plotspc (flu)

## artificial example to show wavelength axis cutting
plotspc (chondro [sample (nrow (chondro), 50)],
         wl.range = list (600 ~ 650, 1000 ~ 1100, 1600 ~ 1700),
         xoffset = c (0, 300, 450))

plotspc (chondro [sample (nrow (chondro), 50)],
         wl.range = list (600 ~ 650, 1000 ~ 1100, 1600 ~ 1700),
         xoffset = c (300, 450))

## some journals publish Raman spectra backwards
plotspc (chondro [sample (nrow (chondro), 50)], wl.reverse = TRUE)

plotspc (laser[(0:4)*20+1,,], stacked = TRUE)

plotspc (laser, func = mean_pm_sd,
         col = c(NA, "red", "black"), lines.args = list (lwd = 2),
         fill = c (1, NA, 1),
         fill.col = "yellow", border = "blue",
         polygon.args = list (lty = 2, lwd = 4),
         title.args = list (xlab = expression (lambda[emission] / nm),
                            y = list(line = 3.4),
                            col.lab = "darkgreen"),
         axis.args = list (x = list (col = "magenta"), y = list (las = 1))
        )

mean.pm.sd <- aggregate (chondro, chondro$clusters, mean_pm_sd)
plot (mean.pm.sd, col = matlab.palette (3), fill = ".aggregate", stacked = ".aggregate")


mean.pm.sd <- aggregate (chondro, chondro$clusters, mean_pm_sd)

offset <- stacked.offsets (mean.pm.sd, ".aggregate")
plot (mean.pm.sd, fill.col = matlab.palette (3), fill = ".aggregate",
      stacked = ".aggregate")

plot (aggregate (chondro, chondro$clusters, mean), yoffset = offset$offsets,
      lines.args = list (lty = 2, lwd = 2), add = TRUE)

barb <- do.call (collapse, barbiturates [1:3])
plot (barb, lines.args = list (type = "h"), stacked = TRUE,
      stacked.args = list (add.factor = .2))