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 = getOption("ggspectra.norm", default = "update"),
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,
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 = getOption("ggspectra.norm", default = "update"),
plot.qty = getOption("photobiology.filter.qty", default = "transmittance"),
pc.out = getOption("ggspectra.pc.out", default = FALSE),
plot.data = "as.is",
idfactor = TRUE,
facets = FALSE,
object.label = deparse(substitute(object)),
na.rm = TRUE
)
Arguments
- object
a filter_spct object or a filter_mspct object.
- ...
in the case of collections of spectra, additional arguments passed to the plot methods for individual spectra, otherwise currently ignored.
- w.band
a single waveband object or a list of waveband objects.
- range
an R object on which
range()
returns a vector of length 2, with minimum and maximum wavelengths (nm).- norm
numeric Normalization wavelength (nm) or character string
"max"
, or"min"
for normalization at the corresponding wavelength,"update"
to update the normalization after modifying units of expression, quantity or range but respecting the previously used criterion, or"skip"
to force return ofobject
unchanged.- plot.qty
character string one of "transmittance" or "absorbance".
- pc.out
logical, if
TRUE
use percent instead of fraction of one for normalized spectral data.- label.qty
character string giving the type of summary quantity to use for labels, one of
"mean"
,"total"
,"contribution"
, and"relative"
.- span
a peak is defined as an element in a sequence which is greater than all other elements within a window of width span centred at that element.
- wls.target
numeric vector indicating the spectral quantity values for which wavelengths are to be searched and interpolated if need. The
character
strings"half.maximum"
and"half.range"
are also accepted as arguments. A list withnumeric
and/orcharacter
values is also accepted.- annotations
a character vector. For details please see sections Plot Annotations and Title Annotations.
- geom
character The name of a ggplot geometry, currently only
"area"
,"spct"
and"line"
. The defaultNULL
selects between them based onstacked
.- time.format
character Format as accepted by
strptime
.- tz
character Time zone to use for title and/or subtitle.
- text.size
numeric size of text in the plot decorations.
- chroma.type
character one of
"CMF"
(color matching function) or"CC"
(color coordinates) or achroma_spct
object.- idfactor
character Name of an index column in data holding a
factor
with each spectrum in a long-form multispectrum object corresponding to a distinct level of the factor.- facets
logical or integer Indicating if facets are to be created for the levels of
idfactor
whenspct
contain multiple spectra in long form.- plot.data
character Data to plot. Default is
"as.is"
plotting one line per spectrum. When passing"mean"
,"median"
,"sum"
,"prod"
,"var"
,"sd"
,"se"
as argument all the spectra must contain data at the same wavelength values.- ylim
numeric y axis limits,
- object.label
character The name of the object being plotted.
- na.rm
logical.
Details
The plot object returned is a ggplot (an object of class
"gg"
) and it can be added to or modified as any other ggplot. The
axis labels are encoded as plotmath expressions as they contain
superscripts and special characters. In 'ggplot2', plotmath expressions do
not obey theme settings related to text fonts, except for size
.
Scale limits are expanded so as to make space for the annotations. If
annotations are disabled, limits are not expanded unless
reserve.space
is passed to parameter annotations
.
The generic of the autoplot
method is defined in
package 'ggplot2'. Package 'ggspectra' defines specializations for the
different classes for storage of spectral data defined in package
photobiology
.
Note
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.
Plot Annotations
The recognized annotation names are: "summaries"
, "peaks"
,
"peak.labels"
, "valleys"
, "valley.labels"
,
"wls"
, "wls.labels"
, "colour.guide"
,
"color.guide"
, "boxes"
, "segments"
, "labels"
.
In addition, "+"
is interpreted as a request to add to the already
present default annotations, "-"
as request to remove annotations
and "="
or missing"+"
and "-"
as a request to reset
annotations to those requested. If used, "+"
, "-"
or
"="
must be the first member of a character vector, and followed by
one or more of the names given above. To simultaneously add and remove
annotations one can pass a list
containing character
vectors
each assembled as described. The vectors are applied in the order they
appear in the list. To disable all annotations pass ""
or
c("=", "")
as argument. Adding a variation of an annotation already
present, replaces the existing one automatically: e.g., adding
"peak.labels"
replaces"peaks"
if present.
Title Annotations
metadata retrieved from object object
is
paased to ggplot2::ggtitle()
as arguments for title
,
subtitle
and caption
. The specification for the title is
passed as argument to annotations
, and consists in the keyword
title
with optional modifiers selecting the kind of metatdata to
use, separated by colons. Up to three keywords separated by colons are
accepted, and correspond to title, subtitle and caption. The recognized
keywords are: "objt"
, "class"
, "what"
, "when"
,
"where"
, "how"
, "inst.name"
, "inst.sn"
,
"comment"
and "none"
are recognized as modifiers to
"title"
; "none"
is a placeholder. Default is
"title:objt"
or no title depending on the context.
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()
,
set_annotations_default()
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 = "absorptance")
#> Warning: Conversion from internal Tfr to Afr possible only if Rfr or Rfr.constant are known.
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 = "Spectra")
#> 'multiple.wl > 1' but no idexing factor found.
#> Warning: Computation failed in `stat_wb_mean()`.
#> Caused by error in `findInterval()`:
#> ! 'vec' must be sorted non-decreasingly and not contain NAs
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)