Package 'ggspectra'

Description

Additional annotations, stats, geoms and scales for plotting "light" spectra with 'ggplot2', together with specializations of ggplot() and autoplot() methods for spectral data and waveband definitions stored in objects of classes defined in package 'photobiology'. Part of the 'r4photobiology' suite, Aphalo P. J. (2015) doi:10.19232/uv4pb.2015.1.14.

Details

Package 'ggspectra' provides a set of layer functions and autoplot() methods extending packages 'ggplot2' and 'photobiology'. The autoplot() methods specialised for objects of classes defined in package 'photobiology' facilitate in many respects the plotting of spectral data. The ggplot() methods specialised for objects of classes defined in package 'photobiology' combined with the new layer functions and scales easy the task of flexibly plotting radiation-related spectra and of annotating the resulting plots.

These methods, layer functions and scales are specialized and work only with certain types of data and ways of expressing physical quantities. Most importantly, all statistics expect the values mapped to the x aesthetic to be wavelengths expressed in nanometres (nm), which is ensured when the data are stored in data objects of classes defined in package 'photobiology'. The support for scale transforms is manual and only partial. Flipping is not supported.

Although originally aimed at plots relevant to photobiology, many of the functions in the package are also useful for plotting other UV, VIS and NIR spectra of light emission, transmittance, reflectance, absorptance, and responses.

The available summary quantities are both simple statistical summaries and response-weighted summaries. Simple derived quantities represent summaries of a given range of wavelengths, and can be expressed either in energy or photon based units. Derived biologically effective quantities are used to quantify the effect of radiation on different organisms or processes within organisms. These effects can range from damage to perception of informational light signals. Additional features of spectra may be important and worthwhile annotating in plots. Of these, local maxima (peaks), minima (valleys) and spikes present in spectral data can also be annotated with statistics from 'ggspectra'.

Package 'ggspectra' is useful solely for plotting spectral data as most functions depend on the x aesthetic being mapped to a variable containing wavelength values expressed in nanometres. It works well together with many other extensions to package 'ggplot2' such as packages 'ggrepel', 'gganimate' and 'cowplot'.

This package is part of a suite of R packages for photobiological calculations described at the [r4photobiology](https://www.r4photobiology.info) web site.

Note

This package makes use of the new features of 'ggplot2' >= 2.0.0 that make writing this kind of extensions easy and is consequently not compatible with earlier versions of 'ggplot2'.

Author(s)

Maintainer: Pedro J. Aphalo [email protected] (ORCID)

Other contributors:

• Titta K. Kotilainen (ORCID) [contributor]

References

Aphalo, Pedro J. (2015) The r4photobiology suite. UV4Plants Bulletin, 2015:1, 21-29. doi:10.19232/uv4pb.2015.1.14.

ggplot2 web site at https://ggplot2.tidyverse.org/
ggplot2 source code at https://github.com/tidyverse/ggplot2
Function multiplot from http://www.cookbook-r.com/

See Also

Useful links:

• https://docs.r4photobiology.info/ggspectra/

• https://github.com/aphalo/ggspectra/

• Report bugs at https://github.com/aphalo/ggspectra/issues/

Examples

library(photobiologyWavebands)

ggplot(sun.spct) +
  geom_line() +
  stat_peaks(span = NULL)

ggplot(sun.spct, aes(w.length, s.e.irrad)) +
  geom_line() +
  stat_peaks(span = 21, geom = "point", colour = "red") +
  stat_peaks(span = 51, geom = "text", colour = "red", vjust = -0.3,
             label.fmt = "%3.0f nm")

ggplot(polyester.spct, range = UV()) + geom_line()

autoplot(sun.spct)

autoplot(polyester.spct,
         UV_bands(),
         range = UV(),
         annotations = c("=", "segments", "labels"))

Description

Generate cps axis labels in SI units, using SI scale factors. Output can be selected as character, expression (R default devices) or LaTeX (for tikz device).

Usage

A_label(
  unit.exponent = 0,
  format = getOption("photobiology.math", default = "R.expression"),
  label.text = NULL,
  scaled = FALSE,
  normalized = FALSE,
  axis.symbols = getOption("ggspectra.axis.symbols", default = TRUE),
  Tfr.type
)

A_internal_label(
  unit.exponent = 0,
  format = getOption("photobiology.math", default = "R.expression"),
  label.text = NULL,
  scaled = FALSE,
  normalized = FALSE,
  axis.symbols = getOption("ggspectra.axis.symbols", default = TRUE)
)

A_total_label(
  unit.exponent = 0,
  format = getOption("photobiology.math", default = "R.expression"),
  label.text = NULL,
  scaled = FALSE,
  normalized = FALSE,
  axis.symbols = getOption("ggspectra.axis.symbols", default = TRUE)
)

Arguments

Value

a character string or an R expression.

Note

Default for label.text depends on the value passed as argument to Tfr.type.

Examples

A_label(Tfr.type = "internal")
A_label(Tfr.type = "total")
A_label(Tfr.type = "total", axis.symbols = FALSE)


A_internal_label()
A_internal_label(format = "R.expression", axis.symbols = FALSE)
A_internal_label(-3)
A_internal_label(format = "R.expression")
A_internal_label(format = "LaTeX")
A_internal_label(-3, format = "LaTeX")


A_total_label()
A_total_label(format = "R.expression", axis.symbols = FALSE)
A_total_label(-3)
A_total_label(format = "R.expression")
A_total_label(format = "LaTeX")
A_total_label(-3, format = "LaTeX")

Description

Generate cps axis labels in SI units, using SI scale factors. Output can be selected as character, expression (R default devices) or LaTeX (for tikz device).

Usage

Afr_label(
  unit.exponent = ifelse(pc.out, -2, 0),
  format = getOption("photobiology.math", default = "R.expression"),
  label.text = axis_labels(append = ifelse(axis.symbols, ",", ""))[["s.Afr"]],
  scaled = FALSE,
  normalized = FALSE,
  axis.symbols = getOption("ggspectra.axis.symbols", default = TRUE),
  pc.out = getOption("ggspectra.pc.out", default = FALSE)
)

Rfr_total_label(
  unit.exponent = ifelse(pc.out, -2, 0),
  format = getOption("photobiology.math", default = "R.expression"),
  label.text = NULL,
  scaled = FALSE,
  normalized = FALSE,
  axis.symbols = getOption("ggspectra.axis.symbols", default = TRUE),
  pc.out = getOption("ggspectra.pc.out", default = FALSE)
)

Arguments

Value

a character string or an R expression.

Examples

Afr_label()
Afr_label(format = "R.expression", axis.symbols = FALSE)
Afr_label(-2)
Afr_label(-3)
Afr_label(format = "R.expression")
Afr_label(format = "LaTeX")
Afr_label(-2, format = "LaTeX")


Rfr_total_label()
Rfr_total_label(axis.symbols = FALSE)
Rfr_total_label(-2)
Rfr_total_label(-3)
Rfr_total_label(format = "R.expression")
Rfr_total_label(format = "LaTeX")
Rfr_total_label(-3, format = "LaTeX")

Description

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

Usage

## S3 method for class 'calibration_spct'
autoplot(
  object,
  ...,
  w.band = getOption("photobiology.plot.bands", default = list(UVC(), UVB(), UVA(),
    PhR())),
  range = getOption("ggspectra.wlrange", default = NULL),
  unit.out = "ignored",
  pc.out = getOption("ggspectra.pc.out", default = FALSE),
  label.qty = "mean",
  span = NULL,
  wls.target = "HM",
  annotations = NULL,
  by.group = FALSE,
  geom = "line",
  time.format = "",
  tz = "UTC",
  norm = NA,
  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 'calibration_mspct'
autoplot(
  object,
  ...,
  range = getOption("ggspectra.wlrange", default = NULL),
  unit.out = "ignored",
  norm = NA,
  pc.out = getOption("ggspectra.pc.out", default = FALSE),
  by.group = FALSE,
  plot.data = "as.is",
  idfactor = TRUE,
  facets = FALSE,
  object.label = deparse(substitute(object)),
  na.rm = TRUE
)

Arguments

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, calibration_spct, waveband, photobiologyWavebands-package and autoplot

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

Examples

# to be added

Description

These methods return a ggplot object with an annotated plot of a cps_spct or a cps_mspct object.

Usage

## S3 method for class 'cps_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 = NULL,
  pc.out = getOption("ggspectra.pc.out", default = FALSE),
  label.qty = "mean",
  span = NULL,
  wls.target = "HM",
  annotations = NULL,
  by.group = FALSE,
  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 'cps_mspct'
autoplot(
  object,
  ...,
  range = getOption("ggspectra.wlrange", default = NULL),
  norm = NA,
  unit.out = NULL,
  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

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, cps_spct, waveband, photobiologyWavebands-package and autoplot

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

Examples

autoplot(white_led.cps_spct)
autoplot(white_led.cps_spct, geom = "spct")
autoplot(normalize(white_led.cps_spct, norm = "max"))

two_leds.mspct <-
  cps_mspct(list("LED 1" = white_led.cps_spct,
                 "LED 2" = white_led.cps_spct / 2))
autoplot(two_leds.mspct)
autoplot(two_leds.mspct, idfactor = "Spectra")
autoplot(two_leds.mspct, plot.data = "mean")

Description

These methods return a ggplot object of an annotated plot from spectral data contained in a filter_spct or a filter_mspct object. Data can be expressed as absorbance, absorptance or transmittance.

Usage

## S3 method for class 'filter_spct'
autoplot(
  object,
  ...,
  w.band = getOption("photobiology.plot.bands", default = list(UVC(), UVB(), UVA(),
    PhR())),
  range = getOption("ggspectra.wlrange", default = NULL),
  norm = NULL,
  plot.qty = getOption("photobiology.filter.qty", default = "transmittance"),
  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 'filter_mspct'
autoplot(
  object,
  ...,
  range = getOption("ggspectra.wlrange", default = NULL),
  norm = NULL,
  plot.qty = getOption("photobiology.filter.qty", default = "transmittance"),
  pc.out = getOption("ggspectra.pc.out", default = FALSE),
  by.group = FALSE,
  plot.data = "as.is",
  idfactor = TRUE,
  facets = FALSE,
  object.label = deparse(substitute(object)),
  na.rm = TRUE
)

Arguments

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.

Note

The plotting of absorbance is an exception to scale limits as the y-axis is not extended past 6 a.u. In the case of absorbance, values larger than 6 a.u. are rarely meaningful due to stray light during measurement. However, when transmittance values below the detection limit are rounded to zero, and later converted into absorbance, values Inf a.u. result, disrupting the plot. Scales are further expanded so as to make space for the annotations.

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

See Also

normalize, filter_spct, waveband, photobiologyWavebands-package and autoplot

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

Examples

# one spectrum
autoplot(yellow_gel.spct)
autoplot(yellow_gel.spct, geom = "spct")
autoplot(yellow_gel.spct, plot.qty = "transmittance")
autoplot(yellow_gel.spct, plot.qty = "absorbance")
autoplot(yellow_gel.spct, pc.out = TRUE)
autoplot(yellow_gel.spct, annotations = c("+", "wls"))

# spectra for two filters in long form
autoplot(two_filters.spct)
autoplot(two_filters.spct, idfactor = TRUE)
autoplot(two_filters.spct, idfactor = "Spectra")
autoplot(two_filters.spct, facets = TRUE)

# spectra for two filters as a collection
autoplot(two_filters.mspct)
autoplot(two_filters.mspct, idfactor = "Spectra")
autoplot(two_filters.mspct, facets = TRUE)

Description

These methods return a ggplot object with an annotated plot of an object_spct or an object_spct object. This objects contain spectral transmittance, reflectance and possibly absorptance data. As these quantities add up to one, only two are needed.

Usage

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

## S3 method for class 'object_mspct'
autoplot(
  object,
  ...,
  range = getOption("ggspectra.wlrange", default = NULL),
  norm = NULL,
  plot.qty = getOption("photobiology.filter.qty", default = "all"),
  pc.out = getOption("ggspectra.pc.out", default = FALSE),
  by.group = FALSE,
  plot.data = "as.is",
  idfactor = TRUE,
  facets = plot.qty == "all",
  object.label = deparse(substitute(object)),
  na.rm = TRUE
)

Arguments

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.

Note

In the case of multiple spectra contained in the argument to object plotting is for plot.qty = "all" is always done using facets. Other plot quantities are handled by the methods for filter_spct and reflector_spct objects after on-the-fly conversion and the use of facets is possible but not the default.

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

See Also

normalize, object_spct, waveband, photobiologyWavebands-package and autoplot

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

Examples

autoplot(Ler_leaf.spct)
autoplot(Ler_leaf.spct, geom = "line")
autoplot(Ler_leaf.spct, plot.qty = "absorptance")
autoplot(Ler_leaf.spct, plot.qty = "reflectance")
autoplot(Ler_leaf.spct, plot.qty = "transmittance")

Description

These methods construct a ggplot object with an annotated plot of a raw_spct or a raw_mspct object.

Usage

## S3 method for class 'raw_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 = "counts",
  pc.out = getOption("ggspectra.pc.out", default = FALSE),
  by.group = FALSE,
  label.qty = "mean",
  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 'raw_mspct'
autoplot(
  object,
  ...,
  range = getOption("ggspectra.wlrange", default = NULL),
  norm = NA,
  unit.out = "counts",
  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

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, raw_spct, waveband, photobiologyWavebands-package and autoplot

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

Examples

low_res.raw_spct <- thin_wl(white_led.raw_spct,
                            max.wl.step = 20,
                            max.slope.delta = 0.05,
                            col.names = "counts_3")
autoplot(low_res.raw_spct)
autoplot(low_res.raw_spct, annotations = "")

two_leds.mspct <-
  raw_mspct(list("LED 1" = low_res.raw_spct,
                 "LED 2" = low_res.raw_spct))
autoplot(two_leds.mspct)
autoplot(two_leds.mspct, facets = 1) # one column

Description

These methods return a ggplot object for an annotated plot from spectral data stored in a reflector_spct or a reflector_mspct object.

Usage

## S3 method for class 'reflector_spct'
autoplot(
  object,
  ...,
  w.band = getOption("photobiology.plot.bands", default = list(UVC(), UVB(), UVA(),
    PhR())),
  range = getOption("ggspectra.wlrange", default = NULL),
  norm = NULL,
  plot.qty = getOption("photobiology.reflector.qty", default = "reflectance"),
  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 'reflector_mspct'
autoplot(
  object,
  ...,
  range = getOption("ggspectra.wlrange", default = NULL),
  norm = NULL,
  plot.qty = getOption("photobiology.reflector.qty", default = "reflectance"),
  pc.out = getOption("ggspectra.pc.out", default = FALSE),
  by.group = FALSE,
  plot.data = "as.is",
  idfactor = TRUE,
  facets = FALSE,
  object.label = deparse(substitute(object)),
  na.rm = TRUE
)

Arguments

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, reflector_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.response_spct(), autoplot.source_spct(), autoplot.waveband()

Examples

autoplot(Ler_leaf_rflt.spct)
autoplot(Ler_leaf_rflt.spct, geom = "spct")
autoplot(Ler_leaf_rflt.spct, annotations = c("+", "valleys"))

two_leaves.mspct <-
 reflector_mspct(list("Arabidopsis leaf 1" = Ler_leaf_rflt.spct,
                      "Arabidopsis leaf 2" = Ler_leaf_rflt.spct / 2))
autoplot(two_leaves.mspct)
autoplot(two_leaves.mspct, idfactor = "Spectra")
autoplot(two_leaves.mspct, facets = 2)

Description

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

Arguments

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, response_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.source_spct(), autoplot.waveband()

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 * 1.5e-5,
                     "Coupled charge device" = ccd.spct))

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")

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

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

Description

Construct a ggplot object with an annotated plot of a waveband object.

Usage

## S3 method for class 'waveband'
autoplot(
  object,
  ...,
  w.length = NULL,
  range = NULL,
  fill = 0,
  span = NULL,
  wls.target = "HM",
  unit.in = getOption("photobiology.radiation.unit", default = "energy"),
  unit.out = unit.in,
  annotations = NULL,
  by.group = FALSE,
  geom = "line",
  wb.trim = TRUE,
  norm = NA,
  text.size = 2.5,
  ylim = c(NA, NA),
  object.label = deparse(substitute(object)),
  na.rm = TRUE
)

Arguments

Details

A response_spct object is created based on the waveband object and the argument passed to parameter w.length. By default wavelengths spanning the waveband definition expanded by 1 nm at each end are used. A waveband object can describe either a simple wavelength range or a (biological) spectral weighting function (BSWF). An effectiveness is a response expressed per unit of excitation, and in most cases normalised.

Effectiveness spectra can be plotted expressing the spectral effectiveness either per mol of photons ($1 mol^{-1} nm$) or per joule of energy ($1 J^{-1} nm$), selected through formal argument unit.out. The value of unit.in has no direct effect on the result for BSWFs, as BSWFs are defined based on a certain base of expression, which is enforced. Indirectly it affects plots as unit.out defaults to unit.in. In contrast, for wavebands which only define a wavelength range, changing the assumed reference irradiance units, changes the responsivity according to Plank's law, i.e., the four possible combinations of pairs of values for unit.in and unit.out produce four different plots. _Only in rare cases unit.in and unit.out is useful as normally the dependency on base of expresion is encoded in the waveband definition as a BSWF._

While w.length' provides the wavelengths of the generated response spectrum, 'range' sets the wavelength range of the $x$-axis of the plot.

Unused named arguments are forwarded to autoplot.response_spct(), allowing control of additional plot properties.

Value

a ggplot object.

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.

See Also

autoplot.response_spct, waveband.

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.source_spct()

Examples

autoplot(waveband(c(400, 500)))
autoplot(waveband(c(400, 500)), w.length = c(300,600))
autoplot(waveband(c(400, 500)), range = c(300,600))
autoplot(waveband(c(400, 500)), geom = "spct")

Description

Add a title, subtitle and caption to a spectral plot based on automatically extracted metadata from an spectral object.

Usage

autotitle(
  object,
  object.label = deparse(substitute(object)),
  annotations = "title",
  time.format = NULL,
  tz = "",
  default.title = "title:objt"
)

ggtitle_spct(
  object,
  object.label = deparse(substitute(object)),
  annotations = "title",
  time.format = NULL,
  tz = "",
  default.title = "title:objt"
)

Arguments

Value

The return value of ggplot2::labs().

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.

Note

Method renamed as autotitle() to better reflect its function; ggtitle_spct() is deprecated but will remain available for backwards compatibility.

Examples

p <- ggplot(sun.spct) +
  geom_line()

p + autotitle(sun.spct)
p + autotitle(sun.spct, object.label = "The terrestrial solar spectrum")
p + autotitle(sun.spct, annotations = "title:objt:class")
p + autotitle(sun.spct, annotations = "title:where:when:how")

p <- ggplot(sun_evening.spct) +
  aes(linetype = spct.idx) +
  geom_line()

p + autotitle(sun_evening.spct, annotations = "title:objt:class")
p + autotitle(sun_evening.spct, annotations = "title:where:when:how")
p + autotitle(sun_evening.spct, annotations = "title:none:none:how")

p <- ggplot(sun_evening.mspct) +
  aes(linetype = spct.idx) +
  geom_line()

p + autotitle(sun_evening.mspct, annotations = "title:objt:class")

Description

Texts used by default for axis labels in plots are recalled from character vectors returned by these functions. The aim is that their default values can be easily changed or translated to other languages. They contain only the text part, but not symbols or units of expression.

Usage

axis_labels_uk(append = "", sep = "")

axis_labels_none()

axis_labels(append = "", sep = "")

Arguments

Details

By default axis_labels() contains a copy of axis_labels_uk_comma(). By assigning to this name a user function that returns a named character vector using the same names for its members as those returned by these functions, it is possible to temporarily change the default texts.

Currently only UK English label texts are predefined and axis_labels() is a synonym of axis_labels_uk().

Value

A character vector

Examples

names(axis_labels())

axis_labels()[["w.length"]] # no comma
axis_labels(append = ",")[["w.length"]] # ending in a comma

axis_labels_uk()[["w.length"]] # English (same as default)
axis_labels_none()[["w.length"]] # empty label

Description

Chose black or white color based on a color to be used as background. Usefull when using geom_text on top of tiles or bars, or geom_label with a variable fill.

Usage

black_or_white(colors, threshold = 0.45)

Arguments

Examples

black_or_white("red")
black_or_white(colors()[1:10])

Description

Color-checker-chart ggplot labelled with color names or with indexes of the colors in the vector passed as first argument.

Usage

color_chart(
  colors = grDevices::colors(),
  ncol = NULL,
  use.names = NULL,
  text.size = 2,
  text.color = NULL,
  grid.color = "white"
)

Arguments

Note

Default text.color uses black_or_white() to ensure enough contrast. Default for use.names depends on number of columns in the grid, indexes are used when columns are seven or more.

Examples

color_chart()
color_chart(grep("dark", colors(), value = TRUE), text.size = 3.5)

Description

Generate axis labels in SI units, using SI scale factors. Output can be selected as character, expression (R default devices) or LaTeX (for tikz device).

Usage

counts_label(
  unit.exponent = 3,
  format = getOption("photobiology.math", default = "R.expression"),
  label.text = axis_labels(append = ifelse(axis.symbols, ",", ""))[["counts"]],
  scaled = FALSE,
  normalized = FALSE,
  axis.symbols = getOption("ggspectra.axis.symbols", default = TRUE)
)

Arguments

Value

a character string or an R expression.

Examples

counts_label()
counts_label("R.expression")
counts_label("LaTeX")

Description

Generate pixel response rate axis labels in cps units. Output can be selected as character, expression (R default devices) or LaTeX (for tikz device).

Usage

cps_label(
  unit.exponent = 0,
  format = getOption("photobiology.math", default = "R.expression"),
  label.text = axis_labels(append = ifelse(axis.symbols, ",", ""))[["cps"]],
  scaled = FALSE,
  normalized = FALSE,
  axis.symbols = getOption("ggspectra.axis.symbols", default = TRUE)
)

Arguments

Value

a character string or an R expression.

Examples

cps_label()
cps_label(3)
cps_label(format = "R.expression")
cps_label(format = "R.character")
cps_label(format = "LaTeX")
cps_label(3, format = "LaTeX")

Description

Convert SI unit prefixes into exponents of ten of multipliers and vice-versa.

Usage

exponent2prefix(
  exponent,
  char.set = getOption("photobiology.fancy.chars", default = "utf8")
)

exponent2factor(exponent = 0, if.zero.exponent = "1")

exponent2prefix_name(exponent)

prefix_name2exponent(name)

prefix2exponent(
  prefix,
  char.set = getOption("photobiology.fancy.chars", default = "utf8")
)

has_SI_prefix(exponent)

nearest_SI_exponent(exponent)

Arguments

Note

To change the default char.set, set R option "photobiology.fancy.chars". Implementation is based on a table of data and extensible to any alphabet supported by R character objects by expanding the table.

Examples

exponent2prefix(3)
exponent2prefix(0)
exponent2prefix(-6)


exponent2factor(3)
exponent2factor(0)
exponent2factor(0, NULL)
exponent2factor(0, "")
exponent2factor(-6)

Description

For each continuous x value, geom_spct displays a y interval. geom_spct is a special case of geom_area, where the minimum of the range is fixed to 0, but stacking is not enabled.

Usage

geom_spct(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  outline.type = "upper",
  ...,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Details

An spectrum plot is the analog of a line plot (see geom_path), and can be used to show how y varies over the range of x. The difference is that the area under the line is filled.

Aesthetics

See geom_ribbon

See Also

geom_ribbon for stacked areas, geom_path for lines (lines), geom_point for scatter plots.

Examples

# ggplot() methods for spectral objects set a default mapping for x and y.
ggplot(sun.spct) + geom_spct()

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 class 'source_spct'
ggplot(
  data,
  mapping = NULL,
  ...,
  range = NULL,
  unit.out = getOption("photobiology.radiation.unit", default = "energy"),
  idfactor = NULL,
  by.group = FALSE,
  environment = parent.frame()
)

## S3 method for class 'response_spct'
ggplot(
  data,
  mapping = NULL,
  ...,
  range = NULL,
  unit.out = getOption("photobiology.radiation.unit", default = "energy"),
  idfactor = NULL,
  by.group = FALSE,
  environment = parent.frame()
)

## S3 method for class 'filter_spct'
ggplot(
  data,
  mapping = NULL,
  ...,
  range = NULL,
  plot.qty = getOption("photobiology.filter.qty", default = "transmittance"),
  idfactor = NULL,
  by.group = FALSE,
  environment = parent.frame()
)

## S3 method for class 'reflector_spct'
ggplot(
  data,
  mapping = NULL,
  ...,
  range = NULL,
  plot.qty = NULL,
  idfactor = NULL,
  by.group = FALSE,
  environment = parent.frame()
)

## S3 method for class 'cps_spct'
ggplot(
  data,
  mapping = NULL,
  ...,
  range = NULL,
  idfactor = NULL,
  by.group = FALSE,
  environment = parent.frame()
)

## S3 method for class 'calibration_spct'
ggplot(
  data,
  mapping = NULL,
  ...,
  range = NULL,
  idfactor = NULL,
  by.group = FALSE,
  environment = parent.frame()
)

## S3 method for class 'raw_spct'
ggplot(
  data,
  mapping = NULL,
  ...,
  range = NULL,
  idfactor = NULL,
  by.group = FALSE,
  environment = parent.frame()
)

## S3 method for class 'object_spct'
ggplot(
  data,
  mapping = NULL,
  ...,
  range = NULL,
  plot.qty = getOption("photobiology.object.qty", default = "all"),
  idfactor = NULL,
  environment = parent.frame()
)

## S3 method for class 'generic_spct'
ggplot(
  data,
  mapping = NULL,
  ...,
  range = NULL,
  spct_class,
  idfactor = NULL,
  environment = parent.frame()
)

## S3 method for class 'generic_mspct'
ggplot(
  data,
  mapping = NULL,
  ...,
  range = NULL,
  idfactor = TRUE,
  environment = parent.frame()
)

## S3 method for class 'filter_mspct'
ggplot(
  data,
  mapping = NULL,
  ...,
  range = NULL,
  plot.qty = getOption("photobiology.filter.qty", default = "transmittance"),
  idfactor = TRUE,
  environment = parent.frame()
)

## S3 method for class 'source_mspct'
ggplot(
  data,
  mapping = NULL,
  ...,
  range = NULL,
  unit.out = getOption("photobiology.radiation.unit", default = "energy"),
  idfactor = TRUE,
  environment = parent.frame()
)

## S3 method for class '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()
)

Arguments

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.

Value

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

Note

plot.qty is ignored for reflectors.

See Also

Method link[ggspectra]{autoplot} provides further automation of plot creation. Function rbindspct is used to convert collections of spectra into "long-form" spectral objects. Function setIdFactor() is used to set the indexing factor of spectral objects multiple spectra in "long-form". The generic of method link[ggplot2](ggplot) is defined in package 'ggplot2'.

Examples

# 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()

Description

Calibration multipliers axis labels. Output can be selected as character, expression (R default devices) or LaTeX (for tikz device).

Usage

multipliers_label(
  unit.exponent = 0,
  format = getOption("photobiology.math", default = "R.expression"),
  label.text = axis_labels(append = ifelse(axis.symbols, ",", ""))[["e.mult"]],
  scaled = FALSE,
  normalized = FALSE,
  axis.symbols = getOption("ggspectra.axis.symbols", default = TRUE)
)

Arguments

Value

a character string or an R expression.

Examples

multipliers_label()
multipliers_label(3)
multipliers_label(format = "R.expression")
multipliers_label(format = "R.character")
multipliers_label(format = "LaTeX")
multipliers_label(3, format = "LaTeX")

Description

Grid based; allows multiple plots arraged in a matrix and printed to any R device. ggplot objects can be passed in ..., or to plotlist (as a list of ggplot objects)

Usage

multiplot(
  ...,
  plotlist = NULL,
  ncol = 1,
  cols = ncol,
  layout = NULL,
  title = "",
  title.position = "left",
  title.fontsize = 12,
  title.fontfamily = "sans",
  title.fontface = "bold",
  title.colour = "black"
)

Arguments

Details

ggplot objects can be passed in ..., or to plotlist (as a list of ggplot objects) If the layout is something like matrix(c(1,2,3,3), nrow=2, byrow=TRUE), then plot 1 will go in the upper left, 2 will go in the upper right, and 3 will go all the way across the bottom.

Note

Modified from example by Winston Chang found in the Cookbook for R Licenced under CC BY-SA

References

http://www.cookbook-r.com/

Examples

multiplot(plot(sun.spct), plot(yellow_gel.spct), ncol = 1)
multiplot(plot(sun.spct), plot(yellow_gel.spct), ncol = 1,
          title = "The sun and a yellow filter")

Description

These plot() methods return a ggplot object with an annotated plot of an object of a class derived from generic_spct, of a class derived from generic_mspct or of an object of class waveband for which an autoplot() method exists. They are implemented as wrappers of autoplot(). The generic for plot() is defined by base R and specializations for objects of diverse classes are provided various packages and R itself. The generic for autoplot() is defined by package 'ggplot2'.

Usage

## S3 method for class 'generic_spct'
plot(x, ...)

## S3 method for class 'generic_mspct'
plot(x, ...)

## S3 method for class 'waveband'
plot(x, ...)

Arguments

Value

a ggplot object.

Deprecation warning!

These plot() specializatioms are provided for backwards compatibility, but all new or updated code should call autoplot() instead of plot() on objects of spectral and waveband classes defined in package 'photobiology'.

These methods add support for plot() specializations as these specialization were provided by package 'ggspectra' years ago, before 'ggplot2' had an autoplot() generic. As these methods return ggplots autoplot is a more suitable name for them.

See Also

autoplot.calibration_spct, autoplot.cps_spct, autoplot.filter_spct, autoplot.raw_spct, autoplot.response_spct, autoplot.source_spct and autoplot.waveband.

Examples

plot(sun.spct) # deprecated syntax, to be avoided
autoplot(sun.spct) # current syntax, to be used

Description

Generate spectral reflectance labels in SI units, using SI scale factors. Output can be selected as character, expression (R default devices) or LaTeX (for tikz device).

Usage

Rfr_label(
  unit.exponent = ifelse(pc.out, -2, 0),
  format = getOption("photobiology.math", default = "R.expression"),
  label.text = NULL,
  scaled = FALSE,
  normalized = FALSE,
  axis.symbols = getOption("ggspectra.axis.symbols", default = TRUE),
  pc.out = getOption("ggspectra.pc.out", default = FALSE),
  Rfr.type
)

Rfr_specular_label(
  unit.exponent = ifelse(pc.out, -2, 0),
  format = getOption("photobiology.math", default = "R.expression"),
  label.text = NULL,
  scaled = FALSE,
  normalized = FALSE,
  axis.symbols = getOption("ggspectra.axis.symbols", default = TRUE),
  pc.out = getOption("ggspectra.pc.out", default = FALSE)
)

Arguments

Value

a character string or an R expression.

Note

Default for label.text depends on the value passed as argument to Rfr.type.

Examples

Rfr_label(Rfr.type = "specular")
Rfr_label(Rfr.type = "total")


Rfr_specular_label()
Rfr_specular_label(axis.symbols = FALSE)
Rfr_specular_label(-2)
Rfr_specular_label(-3)
Rfr_specular_label(format = "R.expression")
Rfr_specular_label(format = "LaTeX")
Rfr_specular_label(-3, format = "LaTeX")

Description

Generate axis labels for spectral irradiance, fluence or exposure in SI units, using SI scale factors. Output can be selected as character, expression (R default devices) or LaTeX (for tikz device).

Usage

s.e.irrad_label(
  unit.exponent = NULL,
  markup.format = getOption("photobiology.math", default = "R.expression"),
  time.unit = "second",
  label.text = NULL,
  pc.out = FALSE,
  scaled = FALSE,
  normalised = FALSE,
  normalized = normalised,
  axis.symbols = getOption("ggspectra.axis.symbols", default = TRUE)
)

s.q.irrad_label(
  unit.exponent = NULL,
  markup.format = getOption("photobiology.math", default = "R.expression"),
  time.unit = "second",
  label.text = NULL,
  pc.out = FALSE,
  scaled = FALSE,
  normalised = FALSE,
  normalized = normalised,
  axis.symbols = getOption("ggspectra.axis.symbols", default = TRUE)
)

Arguments

Value

a character string or an R expression.

Examples

str(s.e.irrad_label())
str(s.e.irrad_label(axis.symbols = FALSE))
str(s.e.irrad_label(markup.format = "R.expression"))
str(s.e.irrad_label(markup.format = "LaTeX"))
str(s.e.irrad_label(markup.format = "R.character"))

str(s.q.irrad_label())
str(s.q.irrad_label(axis.symbols = FALSE))
str(s.q.irrad_label(markup.format = "R.expression"))
str(s.q.irrad_label(markup.format = "LaTeX"))
str(s.q.irrad_label(markup.format = "R.character"))

Description

Generate axis labels for response or action spectra in SI units, using SI scale factors. Output can be selected as character, expression (R default devices) or LaTeX (for tikz device).

Usage

s.e.response_label(
  unit.exponent = 0,
  format = getOption("photobiology.math", default = "R.expression"),
  label.text = axis_labels(append = ifelse(axis.symbols, ",", ""))[["s.e.response"]],
  scaled = FALSE,
  normalized = FALSE,
  axis.symbols = getOption("ggspectra.axis.symbols", default = TRUE)
)

s.q.response_label(
  unit.exponent = 0,
  format = getOption("photobiology.math", default = "R.expression"),
  label.text = axis_labels(append = ifelse(axis.symbols, ",", ""))[["s.q.response"]],
  scaled = FALSE,
  normalized = FALSE,
  axis.symbols = getOption("ggspectra.axis.symbols", default = TRUE)
)

s.e.action_label(
  unit.exponent = 0,
  format = getOption("photobiology.math", default = "R.expression"),
  label.text = axis_labels(append = ifelse(axis.symbols, ",", ""))[["s.e.action"]],
  scaled = FALSE,
  normalized = FALSE,
  axis.symbols = getOption("ggspectra.axis.symbols", default = TRUE)
)

s.q.action_label(
  unit.exponent = 0,
  format = getOption("photobiology.math", default = "R.expression"),
  label.text = axis_labels(append = ifelse(axis.symbols, ",", ""))[["s.q.action"]],
  scaled = FALSE,
  normalized = FALSE,
  axis.symbols = getOption("ggspectra.axis.symbols", default = TRUE)
)

Arguments

Value

a character string or an R expression.

Examples

s.e.response_label()
s.e.response_label(format = "R.expression")
s.e.response_label(format = "R.character")
s.e.response_label(format = "LaTeX")
s.e.response_label(unit.exponent = 3, format = "R.character")
s.q.response_label(format = "R.character")
s.e.action_label(format = "R.character")
s.q.action_label(format = "R.character")
s.e.response_label(scaled = TRUE)
s.e.response_label(scaled = TRUE, format = "R.character")
s.e.response_label(scaled = TRUE, format = "LaTeX")
s.e.response_label(normalized = 300)
s.e.response_label(normalized = 300, format = "R.character")
s.e.response_label(normalized = 300, format = "LaTeX")
s.q.response_label(scaled = TRUE)
s.q.response_label(scaled = TRUE, format = "R.character")
s.q.response_label(scaled = TRUE, format = "LaTeX")
s.q.response_label(normalized = 300)
s.q.response_label(normalized = 300, format = "R.character")
s.q.response_label(normalized = 300, format = "LaTeX")

Description

Scale x continuous with defaults suitable for wavelengths expressed as energy per photon [eV] or [J].

Usage

scale_x_energy_eV_continuous(
  unit.exponent = 0,
  name = w_energy_eV_label(unit.exponent = unit.exponent, label.text = label.text,
    axis.symbols = axis.symbols),
  breaks = scales::pretty_breaks(n = 7),
  labels = SI_pl_format(exponent = unit.exponent),
  label.text = axis_labels(append = ifelse(axis.symbols, ",", ""))[["energy"]],
  axis.symbols = getOption("ggspectra.axis.symbols", default = TRUE),
  ...
)

scale_x_energy_J_continuous(
  unit.exponent = -18,
  name = w_energy_J_label(unit.exponent = unit.exponent, label.text = label.text,
    axis.symbols = axis.symbols),
  breaks = scales::pretty_breaks(n = 7),
  labels = SI_pl_format(exponent = unit.exponent),
  label.text = axis_labels(append = ifelse(axis.symbols, ",", ""))[["energy"]],
  axis.symbols = getOption("ggspectra.axis.symbols", default = TRUE),
  ...
)

Arguments