ggplot: Create a new ggplot plot from spectral data.

Description

ggplot methods initialize a ggplot object. They can be used to declare the input data object for a graphic and to optionally specify the set of plot aesthetics intended to be common throughout all subsequent layers unless specifically overridden. The method specializations from package 'ggspectra' support the classes for storage of spectral data from package 'photobiology'.

Usage

# S3 method for source_spct
ggplot(
  data,
  mapping = NULL,
  ...,
  range = NULL,
  unit.out = getOption("photobiology.radiation.unit", default = "energy"),
  by.group = FALSE,
  environment = parent.frame()
)
# S3 method for response_spct
ggplot(
  data,
  mapping = NULL,
  ...,
  range = NULL,
  unit.out = getOption("photobiology.radiation.unit", default = "energy"),
  by.group = FALSE,
  environment = parent.frame()
)
# S3 method for filter_spct
ggplot(
  data,
  mapping = NULL,
  ...,
  range = NULL,
  plot.qty = getOption("photobiology.filter.qty", default = "transmittance"),
  by.group = FALSE,
  environment = parent.frame()
)
# S3 method for reflector_spct
ggplot(
  data,
  mapping = NULL,
  ...,
  range = NULL,
  plot.qty = NULL,
  by.group = FALSE,
  environment = parent.frame()
)
# S3 method for cps_spct
ggplot(
  data,
  mapping = NULL,
  ...,
  range = NULL,
  by.group = FALSE,
  environment = parent.frame()
)
# S3 method for calibration_spct
ggplot(
  data,
  mapping = NULL,
  ...,
  range = NULL,
  by.group = FALSE,
  environment = parent.frame()
)
# S3 method for raw_spct
ggplot(
  data,
  mapping = NULL,
  ...,
  range = NULL,
  by.group = FALSE,
  environment = parent.frame()
)
# S3 method for object_spct
ggplot(
  data,
  mapping = NULL,
  ...,
  range = NULL,
  plot.qty = getOption("photobiology.object.qty", default = "all"),
  environment = parent.frame()
)
# S3 method for generic_spct
ggplot(
  data,
  mapping = NULL,
  ...,
  range = NULL,
  spct_class,
  environment = parent.frame()
)
# S3 method for generic_mspct
ggplot(
  data,
  mapping = NULL,
  ...,
  range = NULL,
  idfactor = TRUE,
  environment = parent.frame()
)
# S3 method for filter_mspct
ggplot(
  data,
  mapping = NULL,
  ...,
  range = NULL,
  plot.qty = getOption("photobiology.filter.qty", default = "transmittance"),
  idfactor = TRUE,
  environment = parent.frame()
)
# S3 method for source_mspct
ggplot(
  data,
  mapping = NULL,
  ...,
  range = NULL,
  unit.out = getOption("photobiology.radiation.unit", default = "energy"),
  idfactor = TRUE,
  environment = parent.frame()
)
# S3 method for object_mspct
ggplot(
  data,
  mapping = NULL,
  ...,
  range = NULL,
  plot.qty = getOption("photobiology.object.qty", default = ifelse(length(data) > 1L,
    "as.is", "all")),
  idfactor = TRUE,
  environment = parent.frame()
)

Value

A ggplot object, containing data and mapping of data to aesthetics but no plot layers.

Arguments

data: Default spectrum dataset to use for plot. If not a spectrum, the methods used will be those defined in package ggplot2. See ggplot. If not specified, must be supplied in each layer added to the plot.
mapping: Default list of aesthetic mappings to use for plot. If not specified, in the case of spectral objects, a default mapping will be used.
...: Other arguments passed on to methods.
range: an R object on which range() returns a vector of length 2, with min and max wavelengths (nm).
unit.out: character string indicating type of units to use for plotting spectral irradiance or spectral response, "photon" or "energy".
by.group: logical flag If FALSE, the default, individual spectra are mapped to the group aesthetic to ensure separate lines are plotted. Must be set to by.group = TRUE when plots are animated with 'gganimate' "by group" as the grouping for animation is NOT set using aes.
environment: If a variable defined in the aesthetic mapping is not found in the data, ggplot will look for it in this environment. It defaults to using the environment in which ggplot() is called. The use of these parameter has been deprecated in 'ggplot2' in favour of "tidy evaluation".
plot.qty: character string One of "transmittance", "absorptance" or "absorbance" for filter_spct objects, and in addition to these "reflectance", "all" or "as.is" for object_spct objects.
spct_class: character Class into which a generic_spct object will be converted before plotting. The column names in data should match those expected by the class constructor (see setGenericSpct); other arguments should be passed by name). If the argument is "generic_spct", "tibble" or "data.frame" no aesthetic mapping will be set auutomatically.
idfactor: logical or character Generates an index column of factor type. Default is (idfactor=TRUE) for both lists and _mspct objects. If idfactor=TRUE then the column is auto named spct.idx. Alternatively the column name can be directly provided to idfactor as a character string.

Details

ggplot is typically used to construct a plot incrementally, using the + operator to add layers to the existing ggplot object. This is advantageous in that the code is explicit about which layers are added and the order in which they are added. For complex graphics with multiple layers, initialization with ggplot is recommended.

We show seven common ways to invoke ggplot methods for spectra and collections of spectra:

ggplot(spct)
ggplot(spct, unit.out = <unit.to.use>)
ggplot(spct, plot.qty = <quantity.to.plot>)
ggplot(spct, range = <wavelength.range>)
ggplot(spct) + aes(<other aesthetics>)
ggplot(spct, aes(x, y, <other aesthetics>))
ggplot(spct, aes())

The first approach is recommended if all layers use the same data and the same set of automatic default x and y aesthetics. The second, third and fourth use automatic default x and y aesthetics but first transform or trim the spectral data to be plotted. The fifth uses automatic default x and y aesthetics and adds mappings for other aesthetics. These patterns can be combined as needed. The sixth overrides the default automatic mapping, while the seventh delays the mapping of aesthetics and can be convenient when using different mappings for different geoms.

When using the default automatic mapping to x and y aesthetics, unit or quantity conversions are done on the fly according to the arguments passed to parameters unit.out and plot.qty. In contrast, if a mapping for x and/or y aesthetics is passed as an argument to parameter mapping, the arguments to parameters unit.out and plot.qty are ignored and all the mapped variables should be present in the spectral object passed as argument to data.

The current implementation merges the default mapping for x and y aesthetics with the user supplied mapping if it only contains mappings to aesthetics other than x or y or an empty mapping. In addition, when the user does not pass an argument to mapping, not even an empty one, if the object contains multiple spectra, a mapping of the indexing factor to the group aesthetic is added. The name of the id factor is retrieved from the data object metadata.

Differently to objects of other spectral classes, objects of class object_spct contain data for multiple physical quantities. Thus, in the case of class object_spct, the special arguments "all" and "as.is" can be passed as argument to plot.qty. Where all, the defaul indicates that the data are to be converted into long form and indexed with a factor named variable, to allow stacking or faceting. In contrast, "as.is" indicates that data for the different quantities should remain in separate variables (=columns) when added to the plot object. "reflectance" passed as argument to plot.qty triggers conversion of the object_spct object passed as argument to data into a reflector_spct object and "absorbance", "absorptance" and "reflectance", trigger conversion into a filter_spct object. After conversion the objects are forwarded to the matching ggplot method.

The methods for collections of spectra accept arguments through additional. When plotting collections of spectra a factor named as indicated by the argument passed to parameter idfactor, or "spct.idx" by default, is added using as levels the names of the individual members of the collection. The spectral object is forwarded to the ggplot method matching its new class.

Heterogeneous generic collections of spectra containing members belonging to more than one class are not supported.

Examples

Run this code

# source
ggplot(sun.spct) + geom_line()
ggplot(sun.spct, unit.out = "photon") + geom_line()

# multiple spectra in long form
ggplot(sun_evening.spct) + geom_line()
ggplot(sun_evening.spct, aes(linetype = spct.idx)) + geom_line()

# collection of spectra
ggplot(sun_evening.mspct, idfactor = "step") +
  geom_line()
ggplot(sun_evening.mspct, idfactor = "step", aes(colour = step)) +
  geom_line()

# filter
ggplot(yellow_gel.spct) + geom_line()
ggplot(yellow_gel.spct, plot.qty = "absorbance") + geom_line()

# object
ggplot(Ler_leaf.spct) + facet_grid(~variable) + geom_line()
ggplot(Ler_leaf.spct) + aes(fill = variable) + geom_area()
ggplot(Ler_leaf.spct) + aes(linetype = variable) + geom_line()
ggplot(Ler_leaf.spct, plot.qty = "absorptance") + geom_line()