Plot one or more response spectra.

These methods return a ggplot object with an annotated plot of the spectral data contained in a response_spct or a response_mspct object. Spectral responsitivity can be expressed either on an energy basis or a photon or quantum basis.

Usage

# S3 method for class 'response_spct'
autoplot(
  object,
  ...,
  w.band = getOption("photobiology.plot.bands", default =
    list(photobiologyWavebands::UVC(), photobiologyWavebands::UVB(),
    photobiologyWavebands::UVA(), photobiologyWavebands::PhR())),
  range = getOption("ggspectra.wlrange", default = NULL),
  norm = NA,
  unit.out = getOption("photobiology.radiation.unit", default = "energy"),
  pc.out = getOption("ggspectra.pc.out", default = FALSE),
  label.qty = NULL,
  span = NULL,
  wls.target = "HM",
  annotations = NULL,
  geom = "line",
  time.format = "",
  tz = "UTC",
  text.size = 2.5,
  idfactor = NULL,
  facets = FALSE,
  plot.data = "as.is",
  ylim = c(NA, NA),
  object.label = deparse(substitute(object)),
  na.rm = TRUE
)

# S3 method for class 'response_mspct'
autoplot(
  object,
  ...,
  range = getOption("ggspectra.wlrange", default = NULL),
  norm = NA,
  unit.out = getOption("photobiology.radiation.unit", default = "energy"),
  pc.out = getOption("ggspectra.pc.out", default = FALSE),
  plot.data = "as.is",
  facets = FALSE,
  idfactor = TRUE,
  object.label = deparse(substitute(object)),
  na.rm = TRUE
)

Arguments

object: a response_spct object or a response_mspct object.
...: in the case of collections of spectra, additional arguments passed to the plot methods for individual spectra, otherwise currently ignored.
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).
norm: numeric No longer supported, normalization is always updated if present and a unit conversion applied.
unit.out: character string indicating type of radiation units to use for plotting: "photon" or its synonym "quantum", or "energy".
pc.out: logical, if TRUE use percent instead of fraction of one for normalized spectral data.
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.
geom: character The name of a ggplot geometry, currently only "area", "spct" and "line". The default NULL selects between them based on stacked.
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. If different from an existing one, renaming takes place. It is used as title for the plot guide and may 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.
plot.data: character Data to plot. Default is "as.is" plotting one line per spectrum. When passing "mean", "median", "sum", "prod", "var", "sd", "se" as argument all the spectra must contain data at the same wavelength values.
ylim: numeric y axis limits,
object.label: character The name of the object being plotted.
na.rm: logical.

Value

A ggplot object with a number of layers that depends on the data and annotations.

Details

The plot object returned is a ggplot (an object of class "gg") and it can be added to or modified as any other ggplot. The axis labels are encoded as plotmath expressions as they contain superscripts and special characters. In 'ggplot2', plotmath expressions do not obey theme settings related to text fonts, except for size.

Scale limits are expanded so as to make space for the annotations. If annotations are disabled, limits are not expanded unless reserve.space is passed to parameter annotations.

The generic of the autoplot method is defined in package 'ggplot2'. Package 'ggspectra' defines specializations for the different classes for storage of spectral data defined in package photobiology.

Note

If idfactor = NULL, the default, the name of the factor is retrieved from metadata or if no metadata found, the default "spct.idx" is tried. The default for collections of spectra is to create a factor named "spct.idx", but if a different name is passed, it will be used instead, possibly renaming a pre-existing one.

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.

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


autoplot(photodiode.spct)

autoplot(photodiode.spct, geom = "spct")

autoplot(photodiode.spct, unit.out = "photon")

autoplot(photodiode.spct, annotations = "")


two_sensors.mspct <-
 response_mspct(list("Photodiode" = photodiode.spct,
                     "Coupled charge device" = ccd.spct)) |>
 normalize()

autoplot(two_sensors.mspct, unit.out = "photon")

autoplot(two_sensors.mspct, idfactor = "Spectra")

autoplot(two_sensors.mspct, facets = 2)

autoplot(two_sensors.mspct, geom = "spct")