autoplot.source_spct: Plot one or more light-source spectra.

In ggspectra: Extensions to 'ggplot2' for Radiation Spectra

Plot one or more light-source spectra.

Description

These methods return a ggplot object with an annotated plot of the spectral data contained in a source_spct or a source_mspct object.

Usage

## S3 method for class 'source_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,
  by.group = FALSE,
  geom = "line",
  time.format = "",
  tz = "UTC",
  text.size = 2.5,
  chroma.type = "CMF",
  idfactor = NULL,
  facets = FALSE,
  plot.data = "as.is",
  ylim = c(NA, NA),
  object.label = deparse(substitute(object)),
  na.rm = TRUE
)

## S3 method for class 'source_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),
  by.group = FALSE,
  idfactor = TRUE,
  facets = FALSE,
  plot.data = "as.is",
  object.label = deparse(substitute(object)),
  na.rm = TRUE
)

Arguments

object	a source_spct or a source_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). 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, by default the normalization is updated when a unit conversion applied. A wavelength in nanometres as a numeric value or one of the strings "max", "min", "update", "skip" or "undo" are accepted.
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.
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.
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.
chroma.type	character one of "CMF" (color matching function) or "CC" (color coordinates) or a chroma_spct object.
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.
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.

Details

The autoplot() methods from 'ggspectra' are convenience wrapper functions that easy the creation of plots from spectral objects at the cost of lacking the flexibility of the grammar of graphics. 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.

Limits of the y scale 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. An argument passed to parameter ylim manually sets the limits.

An argument passed to parameter range sets the limits of the x scale to which wavelengths in nanometres are mapped. When the limits are narrower than the data the spectrum in "trimmed", when broader only the scale limits are expanded. If the argument is a vector of length 2, NA values are replaced by the default limits.

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.

For details about normalization and arguments to parameter norm, please, see normalize(). If norm = NULL, the default, if the object is normalized norm = "update" is used and otherwise norm = "skip". Values passed as argument to norm are passed to a call to normalize() with this value as its argument. In the case of objects created with 'photobiology' (<= 0.10.9) norm = "undo" is not supported. Be aware that calls to normalize() remove any scaling previously applied with fscale() methods. In practice, the only difference between "skip" and "update" is that with "skip" a message is issued when an update of the normalization is necessary because of a conversion between quantities or bases of expression that are wavelength dependent or non-linear.

For multiple spectra in long form spectral objects, with idfactor = NULL, the default, the name of the factor is retrieved from metadata. If the character string passed as argument to idfactor does not match the one retrieved from the object, results in renaming of the pre-existing factor. 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.

Value

A ggplot object with a number of layers that depends on the data and annotations. The data member retains its original class and metadata attributes.

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.

See Also

normalize(), source_spct(), waveband(), photobiologyWavebands-package and autoplot()

Other autoplot methods: autoplot.calibration_spct(), autoplot.cps_spct(), autoplot.filter_spct(), autoplot.object_spct(), autoplot.raw_spct(), autoplot.reflector_spct(), autoplot.response_spct(), autoplot.waveband()

Examples

autoplot(sun.spct)
autoplot(sun.spct, geom = "spct")
autoplot(sun.spct, unit.out = "photon")

# multiple spectra in long form
autoplot(sun_evening.spct)
autoplot(sun_evening.spct, facets = 1) # one column
autoplot(sun_evening.spct, facets = 2) # two columns
autoplot(sun_evening.spct, plot.data = "mean")
autoplot(sun_evening.spct, idfactor = "Sequence")

# multiple spectra as a collection
autoplot(sun_evening.mspct)
# other examples above using .mspct instead of .spct

ggspectra documentation built on March 18, 2026, 1:06 a.m.