Order of parameters in layer functions

Ensure that the order of parameters is consistent with current 'ggplot2'. In particular the ellipsis position affects partial matching of argument names. Also added transform support to stat_spikes(), stat_find_wls() and stat_find_qtys().
aphalo · Sep 28, 2024 · 6925737 · 6925737
1 parent 4766536
commit 6925737
Show file tree

Hide file tree

Showing 40 changed files with 611 additions and 454 deletions.
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -2,7 +2,7 @@ Package: ggspectra
 Type: Package
 Title: Extensions to 'ggplot2' for Radiation Spectra
 Version: 0.3.13.9000
-Date: 2024-09-12
+Date: 2024-09-28
 Authors@R:
    c(
     person("Pedro J.", "Aphalo", email = "pedro.aphalo@helsinki.fi", role = c("aut", "cre"), comment = c(ORCID = "0000-0003-3385-972X")),

diff --git a/NEWS.md b/NEWS.md
@@ -4,6 +4,13 @@ editor_options:
     wrap: 72
 ---
 
+# ggspectra 0.3.14
+
+- Make the order of parameters of layer functions consistent with those in
+'ggplot2'. This affects partial matching of argument names!
+- Add manual support for scale transformations, needed for label construction
+and matching colour calculations.
+
 # ggspectra 0.3.13
 
 - Revise function `autotitle()` to better support collections of spectra and 

diff --git a/R/geom-spct.r b/R/geom-spct.r
@@ -41,9 +41,14 @@
 #' ggplot(sun.spct) + geom_spct()
 #'
 #' @export
-geom_spct <- function(mapping = NULL, data = NULL, stat = "identity",
-                      position = "identity", na.rm = FALSE, show.legend = NA,
-                      inherit.aes = TRUE, ...) {
+geom_spct <- function(mapping = NULL,
+                      data = NULL,
+                      stat = "identity",
+                      position = "identity",
+                      ...,
+                      na.rm = FALSE,
+                      show.legend = NA,
+                      inherit.aes = TRUE) {
   layer(
     data = data,
     mapping = mapping,

diff --git a/R/ggspectra.r b/R/ggspectra.r
@@ -1,15 +1,24 @@
-#' @details Package `ggspectra` provides a set of stats, geoms and methods
-#' extending packages `ggplot2` and `photobiology`. They easy the task of
-#' plotting radiation-related spectra and of annotating the resulting plots with
-#' labels and summary quantities derived from the spectral data.
-#'
-#' Plot methods automate in many respects the plotting of spectral data.
-#' 'ggplot2' compatible statistics make the addition of labels or plotting of
-#' subject-area specific summaries possible as well as the addition of labels
-#' and wvaelength-based colour to plots easy. Available summaries are most of
-#' those relevant to photobiology. However, many of the functions in the package
-#' are more generaly useful for plotting UV, VIS and NIR spectra of light
-#' emission, transmittance, reflectance, absorptance, and responses.
+#' @details Package `ggspectra` provides a set of layer functions and
+#'   \code{autoplot()} methods extending packages `ggplot2` and `photobiology`.
+#'   The \code{autoplot()} methods specialised for objects of classes defined in
+#'   package 'photobiology' facilitate in many respects the plotting of spectral
+#'   data. The \code{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.
+#'
+#'   \strong{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 \code{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
@@ -18,15 +27,14 @@
 #' 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) and minima (valleys)
-#' present in spectral data can also be annotated with statistics made available
-#' by the 'ggspectra' package.
+#' 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
+#' functions depend on the \code{x} aesthetic being mapped to a variable containing
 #' wavelength values expressed in nanometres. It works well together with
-#' some other extensions to package 'ggplot2' such as packages 'ggrepel' and
-#' 'cowplot'.
+#' 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
@@ -56,18 +64,23 @@
 #'
 #' library(photobiologyWavebands)
 #'
-#' ggplot(sun.spct) + geom_line() + stat_peaks(span = NULL)
+#' ggplot(sun.spct) +
+#'   geom_line() +
+#'   stat_peaks(span = NULL)
 #'
-#' ggplot(sun.spct, aes(w.length, s.e.irrad)) + geom_line() +
+#' 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()
 #'
-#' plot(sun.spct)
+#' autoplot(sun.spct)
 #'
-#' plot(polyester.spct, UV_bands(), range = UV(),
-#'      annotations = c("=", "segments", "labels"))
+#' autoplot(polyester.spct,
+#'          UV_bands(),
+#'          range = UV(),
+#'          annotations = c("=", "segments", "labels"))
 #'
 "_PACKAGE"
diff --git a/R/stat-color.R b/R/stat-color.R
@@ -3,27 +3,29 @@
 #' \code{stat_color} computes color definitions according to human vision.
 #'
 #' @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.
+#'   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 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 chroma.type character one of "CMF" (color matching function) or "CC"
 #'   (color coordinates) or a \code{\link[photobiology]{chroma_spct}} object.
+#' @param x.colour.transform function Applied to \code{x} values before computing
+#'   matching colours.
 #'
 #' @return The original data frame with a variable with color definitions added.
 #'
@@ -60,16 +62,18 @@
 stat_color <- function(mapping = NULL,
                        data = NULL,
                        geom = "point",
-                       chroma.type = "CMF",
                        position = "identity",
+                       ...,
+                       chroma.type = "CMF",
+                       x.colour.transform = I,
                        na.rm = FALSE,
                        show.legend = FALSE,
-                       inherit.aes = TRUE,
-                       ...) {
+                       inherit.aes = TRUE) {
   ggplot2::layer(
     stat = StatColor, data = data, mapping = mapping, geom = geom,
     position = position, show.legend = show.legend, inherit.aes = inherit.aes,
     params = list(chroma.type = chroma.type,
+                  x.colour.transform = x.colour.transform,
                   na.rm = na.rm,
                   ...)
   )
@@ -86,9 +90,11 @@ StatColor <-
     ggplot2::Stat,
     compute_group = function(data,
                              scales,
-                             chroma.type) {
+                             chroma.type,
+                             x.colour.transform) {
       data[["wl.color"]] <-
-        photobiology::fast_color_of_wl(data[["x"]], chroma.type = chroma.type)
+        photobiology::fast_color_of_wl(colour-transform(data[["x"]]),
+                                       chroma.type = chroma.type)
       data
     },
     default_aes = ggplot2::aes(color = after_stat(wl.color),