Plot generic spectral data.

This function returns a ggplot object with an annotated plot from spectral data contained in a generic_spct object.

Usage

# S3 method for class 'generic_spct'
autoplot(
  object,
  ...,
  y.name,
  ymin.name = NULL,
  ymax.name = NULL,
  ylab = ggplot2::waiver(),
  w.band = getOption("photobiology.plot.bands", default = list(UVC(), UVB(), UVA(),
    PhR())),
  range = getOption("ggspectra.wlrange", default = NULL),
  norm = NA,
  label.qty = "none",
  span = NULL,
  wls.target = "HM",
  annotations = NULL,
  by.group = FALSE,
  time.format = "",
  tz = "UTC",
  text.size = 2.5,
  idfactor = NULL,
  facets = FALSE,
  ylim = c(NA, NA),
  object.label = deparse(substitute(object)),
  na.rm = TRUE
)

# S3 method for class 'generic_mspct'
autoplot(object, ...)

Arguments

object: a generic_spct object.
...: in the case of collections of spectra, additional arguments passed to the plot methods for individual spectra, otherwise currently ignored.
y.name, ymin.name, ymax.name: character Names of the columns to be mapped to the y aesthetic.
ylab: character or expression The y-axis label.
w.band: a single waveband object or a list of waveband objects.
range: an R object on which range() returns a vector of length 2, with minimum and maximum wavelengths (nm). Used to trim the spectrum or to expand the wavelength limits of the plot.
norm: numeric or character. Normalization to apply before plotting, If object is already normalized, the normalization is updated when a unit conversion applied.
label.qty: character string giving the type of summary quantity to use for labels, one of "mean", "total", "contribution", and "relative".
span: a peak is defined as an element in a sequence which is greater than all other elements within a window of width span centred at that element.
wls.target: numeric vector indicating the spectral quantity values for which wavelengths are to be searched and interpolated if need. The character strings "half.maximum" and "half.range" are also accepted as arguments. A list with numeric and/or character values is also accepted.
annotations: a character vector. For details please see sections Plot Annotations and Title Annotations.
by.group: logical flag If TRUE repeated identical annotation layers are added for each group within a plot panel as needed for animation. If FALSE, the default, single layers are added per panel.
time.format: character Format as accepted by strptime.
tz: character Time zone to use for title and/or subtitle.
text.size: numeric size of text in the plot decorations.
idfactor: character Name of an index factor used to identify each spectrum when multiple spectra are included in a plot. It is used as title to the guide in the plot and can include embedded spaces and new lines.
facets: logical or integer Indicating if facets are to be created for the levels of idfactor when spct contain multiple spectra in long form.
ylim: numeric y axis limits,
object.label: character The name of the object being plotted.
na.rm: logical.

Value

a ggplot object.

Details

No automatic plot method is possible for objects of class generic_spct as this class is meant to be mainly used only as a pure base class for derivation. A method is provided for generic_spct but not for generic_mspct as generic_mspct objects can contain an assortment of objects including generic_spct and classes derived from generic_spct making the spectra are unlikely be suitable for plotting in the same ggplot.

Contrary to other autoplot methods, the method for generic_spct does not supply defaults to several of its parameters and cannot be used simply by calling it with the spectrum as argument. There are also limitations on which annotations are accepted. On-the-fly normalization is not supported.

No method is implemented for generic_mspct objects as they can contain an heterogeneous collection of objects of class generic_spct or any other class derived from it.

Plot Annotations

The recognized annotation names are: "summaries", "peaks", "peak.labels", "valleys", "valley.labels", "wls", "wls.labels", "colour.guide", "color.guide", "boxes", "segments", "labels". In addition, "+" is interpreted as a request to add to the already present default annotations, "-" as request to remove annotations and "=" or missing"+" and "-" as a request to reset annotations to those requested. If used, "+", "-" or "=" must be the first member of a character vector, and followed by one or more of the names given above. To simultaneously add and remove annotations one can pass a list containing character vectors each assembled as described. The vectors are applied in the order they appear in the list. To disable all annotations pass "" or c("=", "") as argument. Adding a variation of an annotation already present, replaces the existing one automatically: e.g., adding "peak.labels" replaces"peaks" if present.

The annotation layers are added to the plot using statistics defined in 'ggspectra': stat_peaks, stat_valleys, stat_label_peaks, stat_label_valleys, stat_find_wls, stat_spikes, stat_wb_total, stat_wb_mean, stat_wb_irrad, stat_wb_sirrad, stat_wb_contribution, stat_wb_relative, and stat_wl_strip. However, only some of their parameters can be passed arguments through autoplot methods. In some cases the defaults used by autoplot methods are not the defaults of the statistics.

Title Annotations

metadata retrieved from object object is paased to ggplot2::ggtitle() as arguments for title, subtitle and caption. The specification for the title is passed as argument to annotations, and consists in the keyword title with optional modifiers selecting the kind of metatdata to use, separated by colons. Up to three keywords separated by colons are accepted, and correspond to title, subtitle and caption. The recognized keywords are: "objt", "class", "what", "when", "where", "how", "inst.name", "inst.sn", "comment" and "none" are recognized as modifiers to "title"; "none" is a placeholder. Default is "title:objt" or no title depending on the context.

Examples


sun.generic_spct <- as.generic_spct(sun.spct)
autoplot(sun.generic_spct, y.name = "s.q.irrad")

autoplot(sun.generic_spct, y.name = "s.e.irrad")

autoplot(sun.generic_spct, y.name = "s.q.irrad",
         annotations = "")

autoplot(sun.generic_spct, y.name = "s.q.irrad",
         annotations = "title:objt:when",
         ylab = s.q.irrad_label(unit.exponent = 0))

autoplot(sun.generic_spct, y.name = "s.e.irrad",
         annotations = "colour.guide")

autoplot(sun.generic_spct, y.name = "s.q.irrad",
         ylim = c(-1e-6, 4e-6))