Document when x-axis transformations are accepted

Most stats work only when the values mapped to x are wavelengths expressed in nanometres. If a transformation is applied in the x-scale the values "seen" by the statistics are no longer wavelengths expressed in nanometres.

R/stat-wb-box.R

@@ -2,7 +2,8 @@
 #'
 #' \code{stat_wb_box} plots boxes corresponding to wavebands, by default located
 #' slightly above the peak of the spectrum. Sets suitable default aesthetics for
-#' "rect" geom.
+#' \code{geom_rect()}. \strong{\code{x}-scale transformations and axis
+#'   flipping are currently not supported}.
 #'
 #' @param mapping The aesthetic mapping, usually constructed with
 #'   \code{\link[ggplot2]{aes}} or \code{\link[ggplot2]{aes_}}. Only needs
@@ -88,8 +89,8 @@
 #'   scale_fill_identity()
 #'
 #' @note This stat uses a panel function and ignores grouping as it is meant to
-#'   be used for annotations.The value returned as default value for \code{y} is
-#'   based on the y-range of spectral values for the whole data set.
+#'   be used for annotations. The value returned as default value for \code{y}
+#'   is based on the y-range of spectral values for the whole data set.
 #'
 #' @export
 #' @family stats functions
@@ -104,6 +105,7 @@ stat_wb_box <- function(mapping = NULL,
                         ypos.mult = 1.07,
                         ypos.fixed = NULL,
                         box.height = 0.06,
+                        w.band.transform = I,
                         na.rm = FALSE,
                         show.legend = NA,
                         inherit.aes = TRUE) {
@@ -115,6 +117,7 @@ stat_wb_box <- function(mapping = NULL,
                   ypos.mult = ypos.mult,
                   ypos.fixed = ypos.fixed,
                   box.height = box.height,
+                  w.band.transform = w.band.transform,
                   na.rm = na.rm,
                   ...)
   )

R/stat-wb-column.R

@@ -3,7 +3,8 @@
 #' \code{stat_wb_column} computes means under a curve. It first integrates the
 #'   area under a spectral curve and also the mean expressed per nanaometre of
 #'   wavelength for each waveband in the input. Sets suitable default aesthetics
-#'   for "rect" geom.
+#'   for \code{geom_rect()}. \strong{\code{x}-scale transformations and axis
+#'   flipping are currently not supported}.
 #'
 #' @param mapping The aesthetic mapping, usually constructed with
 #'   \code{\link[ggplot2]{aes}} or \code{\link[ggplot2]{aes_}}. Only needs

R/stat-wb-contribution.R

@@ -1,10 +1,13 @@
 #' Integrate ranges under spectral curve.
 #'
-#' \code{stat_wb_contribution} computes means under a curve. It first integrates the
-#'   area under a spectral curve and also the mean expressed per nanaometre of
-#'   wavelength for each waveband in the input. Sets suitable default aesthetics
-#'   for "rect", "hline", "vline", "text" and "label" geoms displaying "contributions"
-#'   per waveband to the total of the spectral integral.
+#' \code{stat_wb_contribution} integrates the area under a spectral curve. It
+#' first integrates the area under the curve for each waveband and for the whole
+#' curve and then expresses the integral for each band as a relative
+#' contribution to the area under the whole spectral curve. Sets suitable
+#' default aesthetics for "rect", "hline", "vline", "text" and "label" geoms
+#' displaying "contributions" per waveband to the total of the spectral
+#' integral. \strong{\code{x}-scale transformations and axis flipping are
+#' currently not supported}.
 #'
 #' @param mapping The aesthetic mapping, usually constructed with
 #'   \code{\link[ggplot2]{aes}} or \code{\link[ggplot2]{aes_}}. Only needs

R/stat-wb-hbar.R

@@ -4,7 +4,8 @@
 #' area under a spectral curve and also the mean expressed per nanaometre of
 #' wavelength for each waveband in the input. Sets suitable default aesthetics
 #' for geoms "errorbarh" and "hline" from 'ggplot', and "linerangeh",
-#' and "errorbarh" from 'ggstance'.
+#' and "errorbarh" from 'ggstance'. \strong{\code{x}-scale transformations and
+#' axis flipping are currently not supported}.
 #'
 #' @param mapping The aesthetic mapping, usually constructed with
 #'   \code{\link[ggplot2]{aes}} or \code{\link[ggplot2]{aes_}}. Only needs

R/stat-wb-irrad.R

@@ -1,6 +1,10 @@
 #' Integrate irradiance for wavebands.
 #'
-#' \code{stat_wb_irrad} computes areas under a curve.
+#' \code{stat_wb_irrad} integrates the area under a spectral irradiance curve,
+#' yielding energy or photon irradiance. The range(s) of wavelengths to
+#' integrate are set with a list of \code{waveband} objects.
+#' \strong{\code{x}-scale transformations and axis flipping are currently not
+#' supported}.
 #'
 #' @param mapping The aesthetic mapping, usually constructed with
 #'   \code{\link[ggplot2]{aes}} or \code{\link[ggplot2]{aes_}}. Only needs

R/stat-wb-label.R

@@ -1,8 +1,9 @@
 #' Label ranges under spectral curve.
 #'
-#' \code{stat_wb_label} computes computes the center of a waveband. Sets
-#' suitable default aesthetics for "text" and "label"
-#' geoms displaying "boundaries" and "names" of wavebands.
+#' \code{stat_wb_label} computes the center of a waveband. Sets suitable default
+#' aesthetics for "text" and "label" geoms displaying "boundaries" and "names"
+#' of wavebands. \strong{\code{x}-scale transformations and axis flipping are
+#' currently not supported}.
 #'
 #' @param mapping The aesthetic mapping, usually constructed with
 #'   \code{\link[ggplot2]{aes}} or \code{\link[ggplot2]{aes_}}. Only needs

R/stat-wb-mean.R

@@ -1,9 +1,9 @@
 #' Integrate ranges under curve.
 #'
-#' \code{stat_wb_mean} computes means under a curve. It first integrates the
-#'   area under a spectral curve and also the mean expressed per nanaometre of
-#'   wavelength for each waveband in the input. Sets suitable default aesthetics
-#'   for "rect", "hline", "vline", "text" and "label" geoms.
+#' \code{stat_wb_mean} computes mean spectral irradiance under a curve for each
+#' waveband in the input. Sets suitable default aesthetics for "rect", "hline",
+#' "vline", "text" and "label" geoms. \strong{\code{x}-scale transformations
+#' and axis flipping are currently not supported}.
 #'
 #' @param mapping The aesthetic mapping, usually constructed with
 #'   \code{\link[ggplot2]{aes}} or \code{\link[ggplot2]{aes_}}. Only needs

R/stat-wb-relative.R

@@ -1,10 +1,11 @@
 #' Integrate ranges under spectral curve.
 #'
-#' \code{stat_wb_relative} computes means under a curve. It first integrates the
-#'   area under a spectral curve and also the mean expressed per nanaometre of
-#'   wavelength for each waveband in the input. Sets suitable default aesthetics
-#'   for "rect", "hline", "vline", "text" and "label" geoms displaying
-#'   values per waveband "relative" to the sum of the wavebands.
+#' \code{stat_wb_relative} computes relative-irradiances under a curve. It first
+#' integrates the area under the spectral curve for each waveband in the input,
+#' and expresses these irradianses relative to their sum. Sets suitable default
+#' aesthetics for "rect", "hline", "vline", "text" and "label" geoms.
+#' \strong{\code{x}-scale transformations and axis flipping are currently not
+#' supported}.
 #'
 #' @param mapping The aesthetic mapping, usually constructed with
 #'   \code{\link[ggplot2]{aes}} or \code{\link[ggplot2]{aes_}}. Only needs

R/stat-wb-sirrad.R

@@ -1,6 +1,10 @@
 #' Integrate spectral irradiance for wavebands.
 #'
-#' \code{stat_wb_sirrad} computes areas under a curve.
+#' \code{stat_wb_sirrad} computes the mean spectral irradiance under a curve,
+#' yielding energy or photon spectral irradiance. The range(s) of wavelengths to
+#' integrate are set with a list of \code{waveband} objects.
+#' \strong{\code{x}-scale transformations and axis flipping are currently not
+#' supported}.
 #'
 #' @param mapping The aesthetic mapping, usually constructed with
 #'   \code{\link[ggplot2]{aes}} or \code{\link[ggplot2]{aes_}}. Only needs

R/stat-wb-total.R

@@ -1,10 +1,9 @@
 #' Integrate ranges under spectral curve.
 #'
-#' \code{stat_wb_total} computes integral under a curve. It first integrates the
-#'   area under a spectral curve and also the mean expressed per nanaometre of
-#'   wavelength for each waveband in the input. Sets suitable default aesthetics
-#'   for "rect", "hline", "vline", "text" and "label" geoms displaying "totals"
-#'   per waveband.
+#' \code{stat_wb_total} computes integral under a curve. Sets suitable default
+#' aesthetics for "rect", "hline", "vline", "text" and "label" geoms displaying
+#' "totals" per waveband. \strong{\code{x}-scale transformations and axis
+#' flipping are currently not supported}.
 #'
 #' @param mapping The aesthetic mapping, usually constructed with
 #'   \code{\link[ggplot2]{aes}} or \code{\link[ggplot2]{aes_}}. Only needs

R/stat-wl-strip.R

@@ -1,30 +1,33 @@
 #' Calculate colours from wavelength.
 #'
-#' \code{stat_wl_strip} computes color definitions according to human vision.
+#' \code{stat_wl_strip} computes color definitions according to human vision and
+#' by default plots a narrow, guide-like colour gradient strip based on
+#' wavelength. \strong{\code{x}-scale transformations and axis flipping are
+#' currently not supported}.
 #'
 #' @param mapping The aesthetic mapping, usually constructed with
-#'    \code{\link[ggplot2]{aes}} or \code{\link[ggplot2]{aes_}}. Only needs to be set
-#'    at the layer level if you are overriding the plot defaults.
+#'   \code{\link[ggplot2]{aes}} or \code{\link[ggplot2]{aes_}}. Only needs to be
+#'   set at the layer level if you are overriding the plot defaults.
 #' @param data A layer specific dataset - only needed if you want to override
-#'    the plot defaults.
-#' @param geom The geometric object to use display the data
-#' @param position The position adjustment to use for overlapping points
-#'    on this layer
+#'   the plot defaults.
+#' @param geom The geometric object to use display the data.
+#' @param position The position adjustment to use for overlapping points on this
+#'   layer.
 #' @param show.legend logical. Should this layer be included in the legends?
-#'   \code{NA}, the default, includes if any aesthetics are mapped.
-#'   \code{FALSE} never includes, and \code{TRUE} always includes.
-#' @param inherit.aes If \code{FALSE}, overrides the default aesthetics,
-#'   rather than combining with them. This is most useful for helper functions
-#'   that define both data and aesthetics and shouldn't inherit behaviour from
-#'   the default plot specification, e.g. \code{\link[ggplot2]{borders}}.
-#' @param ... other arguments passed on to \code{\link[ggplot2]{layer}}. This can
-#'   include aesthetics whose values you want to set, not map. See
+#'   \code{NA}, the default, includes if any aesthetics are mapped. \code{FALSE}
+#'   never includes, and \code{TRUE} always includes.
+#' @param inherit.aes If \code{FALSE}, overrides the default aesthetics, rather
+#'   than combining with them. This is most useful for helper functions that
+#'   define both data and aesthetics and shouldn't inherit behaviour from the
+#'   default plot specification, e.g. \code{\link[ggplot2]{borders}}.
+#' @param ... other arguments passed on to \code{\link[ggplot2]{layer}}. This
+#'   can include aesthetics whose values you want to set, not map. See
 #'   \code{\link[ggplot2]{layer}} for more details.
-#' @param na.rm	a logical value indicating whether NA values should be
-#'   stripped before the computation proceeds.
+#' @param na.rm	a logical value indicating whether NA values should be stripped
+#'   before the computation proceeds.
 #' @param w.band waveband object or a list of such objects or NULL.
-#' @param length.out The number of steps to use to simulate a continuous
-#'   range of colours when w.band == NULL.
+#' @param length.out The number of steps to use to simulate a continuous range
+#'   of colours when w.band == NULL.
 #' @param chroma.type character one of "CMF" (color matching function) or "CC"
 #'   (color coordinates) or a \code{\link[photobiology]{chroma_spct}} object.
 #'
@@ -65,12 +68,15 @@
 #' @examples
 #'
 #' # ggplot() methods for spectral objects set a default mapping for x and y.
-#' ggplot(sun.spct) + geom_line() +
+#' ggplot(sun.spct) +
+#'   geom_line() +
 #'   stat_wl_strip(ymax = -0.02, ymin = -0.04) +
 #'   scale_fill_identity()
 #'
 #' # on some graphic devices the output may show spurious vertical lines
-#' ggplot(sun.spct) + wl_guide(alpha = 0.33, color = NA) + geom_line()
+#' ggplot(sun.spct) +
+#'   wl_guide(alpha = 0.33, color = NA) +
+#'   geom_line()
 #'
 #' @export
 #' @family stats functions
@@ -133,16 +139,16 @@ StatColorGuide <-
 #'
 wl_guide <- function(mapping = NULL,
                      data = NULL,
+                     position = "identity",
+                     ...,
                      chroma.type = "CMF",
                      w.band = NULL,
                      length.out = 150,
                      ymin = -Inf,
                      ymax = Inf,
-                     position = "identity",
                      na.rm = FALSE,
                      show.legend = FALSE,
-                     inherit.aes = TRUE,
-                     ...) {
+                     inherit.aes = TRUE) {
   list(stat_wl_strip(mapping = mapping,
                      data = data,
                      geom = "rect",