decoration: Add decorations to spectrum plot (private)

Description

Add decorations to plots generated by the autoplot() methods defined in this package. It collects code that is common to autoplot() methods for different types of spectra but as it may change in the future it is not exported.

Usage

decoration(
  w.band,
  y.max,
  y.min,
  x.max,
  x.min,
  x.expanse = x.max - x.min,
  y.expanse = y.max - y.min,
  annotations,
  span,
  strict = FALSE,
  wls.target = "HM",
  label.qty,
  label.mult = 1,
  summary.label,
  unit.out = NULL,
  time.unit = NULL,
  text.size = 2.5,
  label.color = NULL,
  chroma.type = "CMF",
  pos.shift = 0,
  by.group = FALSE,
  na.rm = TRUE
)

Value

A list of ggplot "components" that can be added to a ggplot object with operator +. The length of the list depends on the value of argument

annotations.

Arguments

w.band: waveband object or list of waveband objects passed to statistics as argument to their w.band formal parameter.
y.max, y.min, x.max, x.min, x.expanse, y.expanse: numeric. Used to compute the positions of annotations.
annotations: character vector with names of annotations.
span: numeric passed to stat_peaks() and stat_valleys().
strict: logical passed to stat_peaks() and stat_valleys().
wls.target: numeric or character vector passed to stat_find_wls()
label.qty: character the quantity for "summaries" annotaion, affecting the statistic called or the arguments passed to it.
summary.label: character the name of the quantity to be parsed into a plotmath expression.
text.size: numeric giving the size of text for "labels" and "summaries".
label.color: color definition or name
chroma.type: character one of "CMF" (color matching function) or "CC" (color coordinates) or a chroma_spct object. Used to generate colour definitions from wavelengths.
pos.shift: numeric Shift the position of the annotations.
by.group: logical flag If TRUE repeated identical annotation layers are added for each group within a plot panel as needed for animation. If FALSE, the default, single layers are added per panel.
na.rm: logical Passed to all statistics and geometries.

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.

Details

Vectors of character strings passed as argument to annotations are parsed so that if the first member string is "+", the remaining members are added to the current default for annotations; if it is "-" the remaining members are removed from the current default for annotations; and if it is "=" the remaining members become the new default. If the first member is none of these three strings, the whole vector becomes the new default. If annotations is NULL the annotations are reset to the package defaults. When removing annotations "title*", "peaks*" and "valleys*" will remove any variation of these annotations. The string "" means no annotations while "reserve.space" means no annotations but expand y scale to reserve space for annotations. These two values take precedence over any other values in the character vector. The order of the names of annotations has no meaning: the vector is interpreted as a set except for the three possible "operators" at position 1.