R/plot_spectra.R

Defines functions makeContext.specproc_raster rasterize_layer raster_dpi plain_numbers legend_theme palette_scale check_palette line_marks spectra_ends spectra_segments spectra_long summary_band summarize_spectra panel_tag window_labels spectra_meta transform_spectra window_of spectra_windows plot_spectra

Documented in plot_spectra

#' @title Plotting of Spectra
#'
#' @description
#' Spectrum plots are commonly x–y plots in which the x-axis represents the
#' wavelength and the y-axis represents intensity of a spectrum's signal.
#' The function allows to plot a spectrum or several spectra in a single plot,
#' identified either by an id (for example, the samples or spectra id) or by a
#' target variable (for example, the concentration of a chemical element).
#' The spectra can be split into panels by a grouping variable, summarized by
#' their mean or median, and labeled with the emission lines they show.
#'
#' @author Christian L. Goueguel
#'
#' @details
#' This function is based on the ggplot2 package, thus allowing users to easily
#' add or modify different components of the plot. Each row of `x` is drawn as
#' a separate line. All columns other than `id`, `colvar` and `panel` must be
#' named by their wavelength.
#'
#' **Filled spectra.** With `color_as = "fill"`, the area between each
#' spectrum and its baseline (zero intensity, shifted by `offset`) is filled,
#' with the spectrum drawn as a thin dark line. Overlaid spectra are filled
#' with translucent colors. Stacked spectra (with a vertical `offset`) are
#' filled with opaque colors and drawn from the back to the front (from the
#' top to the bottom of the stack), so that the front spectra hide the back
#' ones, as in a waterfall plot.
#'
#' **Detectors.** The spectra are not drawn across the gaps between
#' detectors (wavelength steps of more than 5 times the channel spacing), and
#' the channels of overlapping detectors (where the wavelengths step back in
#' column order) are drawn as separate lines, not joined in a zigzag.
#'
#' **Summaries.** With `summary = "mean"`, each group of spectra is drawn as
#' its mean spectrum, in a band of plus or minus one standard deviation; with
#' `summary = "median"`, as its median spectrum, in a band from the first to
#' the third quartile. The groups are the panels and, within them, the values
#' of `id`; the color of `colvar` is then the mean of `colvar` in each group.
#' The band is not drawn with `color_as = "fill"`.
#'
#' **Transformations.** `transform` receives the spectral columns of `x` (a
#' data frame of the columns named by their wavelength, without `id`,
#' `colvar` and `panel`) and returns the transformed spectra, one row per
#' spectrum: a data frame or a matrix with columns named by their wavelength,
#' or a list holding them as `correction`, as returned by [snv()], [msc()],
#' [baseline_als()] and the other baseline corrections. The number of
#' channels may change, as with [bin_spectra()]. The whole spectra are
#' transformed, before `wavelength` selects the channels to draw, so that a
#' normalization or a baseline correction uses all the channels; the
#' summaries, offsets and labels are those of the transformed spectra. Give
#' `ylab` for the units of the transformed intensities.
#'
#' **Wavelength windows.** With a list of ranges in `wavelength`, each range
#' is drawn in its own panel, side by side and of the same width, with its
#' own wavelength axis: a zoom on several groups of lines at once. The ranges
#' must not overlap; they are drawn in increasing wavelength order, under
#' their names (if any). With `scales = "free_y"`, each range has its own
#' intensity axis, so that weak lines stay readable next to strong ones. With
#' `panel`, the groups are drawn in rows and the ranges in columns (`layout`
#' is ignored), and `scales = "free_y"` fits the intensity axis to each row.
#'
#' **Emission lines.** Each line of `lines` within the wavelength range is
#' marked by a dashed vertical line, labeled with its species and wavelength
#' above the plot (above the top panels, or above each row of panels with
#' several wavelength ranges). Lines closer than 2% of the wavelength range
#' (of their window) share a label, such as "Ca II 393.37, 396.85". The
#' markers are at the tabulated wavelengths: with a horizontal `offset`, they
#' match the first spectrum of each panel. Over a wide range, keep the
#' strongest lines, for example with the `top` or `min_relative` arguments of
#' [libs_lines()], or labels become long.
#'
#' **Publication figures.** Journals print figures about 85 mm wide for a
#' single column and 175 mm for a double column, with text of 7 to 9 points.
#' Make the plot at its printed size, with `base_size` set to the text size,
#' and save it with [ggplot2::ggsave()], in a vector format (PDF or EPS) or
#' as a TIFF of 600 dpi, for example
#' `ggsave("figure.pdf", p, width = 85, height = 65, units = "mm")`. Many
#' long spectra make large and slow vector files: `rasterize = TRUE` draws
#' the spectra as an image within the plot, keeping the text, axes and
#' markers as vectors (this needs the ragg package).
#'
#' @param x data frame or tibble of the spectra.
#' @param id optional (`NULL` by default). Column name of a factor variable
#' that identified each spectrum.
#' @param colvar optional (`NULL` by default). Column name of a numeric
#' variable to be display in color scale.
#' @param interactive A logical: an interactive plotly plot (`TRUE`) or a
#'   ggplot (`FALSE`, default).
#' @param drop_na Optional (`FALSE` by default). Remove rows with NA intensity
#' if drop_na is `TRUE`.
#' @param offset Optional (`NULL` by default). The offsets between successive
#'   spectra, to separate them: a number (vertical offset, in intensity
#'   units), or two numbers `c(horizontal, vertical)` (in nm and intensity
#'   units). The spectrum of row `i` is shifted by `(i - 1)` times the
#'   offsets, so that the first one stays in place. With `panel`, the rows
#'   are counted in each panel, so that the first spectrum of every panel
#'   stays in place. With `summary`, the summary spectra are offset.
#' @param wavelength Optional (`NULL` by default). The wavelength range
#'   `c(min, max)` to draw, in nm, or a list of ranges, drawn side by side,
#'   such as `list("Ca II H and K" = c(392, 398), "K I" = c(765, 771))` (see
#'   Details).
#' @param transform Optional (`NULL` by default). A function applied to the
#'   spectra before they are drawn, such as `snv` or
#'   `\(s) baseline_als(s, lambda = 1e5)`, a formula such as
#'   `~ savitzky_golay(.x, derivative = 1)`, or a list of them, applied in
#'   order (see Details).
#' @param panel Optional (`NULL` by default). Column name of a grouping
#'   variable: the spectra of each group are drawn in a separate panel.
#' @param layout The arrangement of the panels: `"vertical"` (default), one
#'   above the other, or `"horizontal"`, side by side. Ignored without
#'   `panel`, and with several wavelength ranges.
#' @param grid A logical: draw grid lines at the major breaks of the axes
#'   (`FALSE`, default).
#' @param color_as How the colors of `colvar` (or of `id`, without `colvar`)
#'   are shown: as the color of the lines (`"line"`, default), or as the fill
#'   of the area under each spectrum (`"fill"`).
#' @param legend The position of the legend of `colvar` (a color bar) or `id`:
#'   `"none"` (default), `"right"`, `"top"`, `"bottom"`, or `"inside"` (the
#'   top right corner of the plot).
#' @param legend_title The title of the legend. Default is the name of
#'   `colvar` (or `id`); give it with units, such as `"K (%)"`.
#' @param xlab,ylab The axis titles. Default are `"Wavelength (nm)"` and
#'   `"Intensity (arb. units)"`.
#' @param title The plot title. A long title is split into a title and a
#'   subtitle.
#' @param lines Optional table of emission lines, such as returned by
#'   [libs_lines()]: a data frame with the columns `species` (such as
#'   `"K I"`) and `wavelength` (nm). Each line within the wavelength range is
#'   marked and labeled (see Details).
#' @param palette The colors of `colvar` or `id`: the name of a viridis
#'   palette (`"viridis"`, default, `"magma"`, `"inferno"`, `"plasma"`,
#'   `"cividis"`, `"rocket"`, `"mako"` or `"turbo"`), all readable by
#'   colorblind readers and in grayscale except `"turbo"`, or a vector of at
#'   least two colors, interpolated for `colvar` and for the levels of `id`
#'   when there are fewer colors than levels.
#' @param base_size The size of the text, in points. Default is 11; use the
#'   text size of the journal (often 7 to 9 points) for a figure saved at its
#'   printed size. The axis lines and labels scale with it.
#' @param linewidth The width of the spectra lines. Default is 0.5; about 0.3
#'   suits small figures.
#' @param scales `"fixed"` (default), the same intensity axis for all panels,
#'   or `"free_y"`, an intensity axis fitted to each panel.
#' @param panel_tags A logical: tag the panels (a), (b), (c), ... before their
#'   labels (`FALSE`, default): the groups of `panel`, else the wavelength
#'   ranges.
#' @param label_spectra A logical: label each spectrum at its right end
#'   (`FALSE`, default), with its `id`, else its value of `colvar`, else its
#'   row number (or `"Mean"`/`"Median"` for summaries). Most useful for
#'   spectra stacked by `offset`.
#' @param summary `"none"` (default), each spectrum drawn; `"mean"`, the mean
#'   spectrum of each group with a band of plus or minus one standard
#'   deviation; or `"median"`, the median spectrum of each group with a band
#'   of the first to third quartiles (see Details).
#' @param rasterize `FALSE` (default), `TRUE`, or a resolution in dpi: draw
#'   the spectra as an image, of 300 dpi with `TRUE`, within an otherwise
#'   vector plot (see Details). Ignored for interactive plots.
#' @param .interactive `r lifecycle::badge("deprecated")` Use `interactive`.
#'
#' @return Object of class ggplot or of class plotly if `interactive = TRUE`.
#'
#' @seealso [libs_lines()] for the emission lines.
#'
#' @export plot_spectra
#'
#' @examples
#' data(forageLIBS)
#' wl <- as.numeric(names(forageLIBS)[-(1:14)])
#' k_lines <- names(forageLIBS)[-(1:14)][wl > 764 & wl < 772]
#' # the K I resonance lines, colored by potassium content
#' plot_spectra(forageLIBS[1:20, c("K", k_lines)], colvar = K, legend = "right",
#'              legend_title = "K (%)")
#'
#' # five spectra stacked, each shifted up by 20000 counts and right by 0.5 nm,
#' # labeled at their right end
#' plot_spectra(forageLIBS[1:5, c("Measurement", k_lines)], id = Measurement,
#'              offset = c(0.5, 20000), label_spectra = TRUE)
#'
#' # one panel per potassium level, side by side, with the area under the
#' # spectra filled by potassium content and grid lines
#' spectra <- forageLIBS[1:30, c("K", k_lines)]
#' spectra$level <- cut(spectra$K, 3, labels = c("Low K", "Medium K", "High K"))
#' plot_spectra(spectra, colvar = K, panel = level, layout = "horizontal",
#'              offset = c(0.2, 8000), color_as = "fill", grid = TRUE)
#'
#' # a figure for a journal column: the mean spectrum of each potassium level,
#' # with the K I lines labeled (from libs_lines() in practice)
#' lines <- data.frame(species = "K I", wavelength = c(766.49, 769.90))
#' p <- plot_spectra(spectra, colvar = K, panel = level, summary = "mean",
#'                   lines = lines, panel_tags = TRUE, legend = "right",
#'                   legend_title = "K (%)", ylab = "Intensity (counts)",
#'                   base_size = 8, linewidth = 0.3, wavelength = c(765, 771))
#' p
#' # saved at that size (here in the temporary directory)
#' ggplot2::ggsave(file.path(tempdir(), "figure.pdf"), p, width = 85, height = 90,
#'                 units = "mm")
#'
#' # the spectra normalized by SNV over all the channels, then drawn in two
#' # windows side by side, each with its own intensity axis
#' channels <- names(forageLIBS)[-(1:14)]
#' plot_spectra(forageLIBS[1:20, c("K", channels)], colvar = K, transform = snv,
#'              wavelength = list("Ca II H and K" = c(392, 398), "K I" = c(765, 771)),
#'              scales = "free_y", ylab = "SNV intensity")
#'
#' # several transformations, in order: a baseline correction, then the first
#' # derivative
#' plot_spectra(forageLIBS[1:20, c("K", k_lines)], colvar = K,
#'              transform = list(\(s) baseline_als(s, lambda = 1e4),
#'                               ~ savitzky_golay(.x, window = 7, derivative = 1)),
#'              ylab = "First derivative")
plot_spectra <- function(x, id = NULL, colvar = NULL, interactive = FALSE, drop_na = FALSE,
                         offset = NULL, wavelength = NULL, transform = NULL, panel = NULL,
                         layout = c("vertical", "horizontal"), grid = FALSE,
                         color_as = c("line", "fill"),
                         legend = c("none", "right", "top", "bottom", "inside"),
                         legend_title = NULL, xlab = "Wavelength (nm)",
                         ylab = "Intensity (arb. units)", title = NULL, lines = NULL,
                         palette = "viridis", base_size = 11, linewidth = 0.5,
                         scales = c("fixed", "free_y"), panel_tags = FALSE,
                         label_spectra = FALSE, summary = c("none", "mean", "median"),
                         rasterize = FALSE, .interactive = deprecated()) {
  if (missing(x)) {
    stop("Missing 'data' argument.")
  }
  if (!is.data.frame(x)) {
    stop("Input 'data' must be a data frame or tibble.")
  }
  id_quo <- rlang::enquo(id)
  col_quo <- rlang::enquo(colvar)
  panel_quo <- rlang::enquo(panel)
  id_name <- if (rlang::quo_is_null(id_quo)) NULL else rlang::as_name(id_quo)
  col_name <- if (rlang::quo_is_null(col_quo)) NULL else rlang::as_name(col_quo)
  panel_name <- if (rlang::quo_is_null(panel_quo)) NULL else rlang::as_name(panel_quo)
  if (!is.null(id_name) && !id_name %in% colnames(x)) {
    stop("The 'id' column does not exist in the provided data.")
  }
  if (!is.null(col_name) && !col_name %in% colnames(x)) {
    stop("The 'colvar' column does not exist in the provided data.")
  }
  if (!is.null(panel_name) && !panel_name %in% colnames(x)) {
    stop("The 'panel' column does not exist in the provided data.")
  }
  interactive <- renamed_arg(.interactive, interactive, "plot_spectra", ".interactive",
                             "interactive")
  check_flag(interactive, "interactive")
  if (!is.logical(drop_na)) {
    stop("The argument 'drop_na' must be of type boolean (TRUE or FALSE)")
  }
  check_flag(grid, "grid")
  check_flag(panel_tags, "panel_tags")
  check_flag(label_spectra, "label_spectra")
  layout <- match.arg(layout)
  color_as <- match.arg(color_as)
  legend <- match.arg(legend)
  scales <- match.arg(scales)
  summary <- match.arg(summary)
  check_number(base_size, "base_size", lower = 0, lower_open = TRUE)
  check_number(linewidth, "linewidth", lower = 0, lower_open = TRUE)
  check_palette(palette)
  dpi <- raster_dpi(rasterize)
  if (!is.null(dpi) && !interactive) {
    rlang::check_installed("ragg", reason = "to rasterize the spectra.")
  }
  if (!is.null(offset)) {
    if (!is.numeric(offset) || !length(offset) %in% 1:2 || anyNA(offset)) {
      stop("'offset' must be a number (vertical offset) or two numbers c(horizontal, vertical).",
           call. = FALSE)
    }
    offset <- if (length(offset) == 1) c(0, offset) else offset
  }
  windows <- spectra_windows(wavelength)

  spec_cols <- setdiff(names(x), c(id_name, col_name, panel_name))
  wl <- parse_wavelength(spec_cols)
  if (anyNA(wl)) {
    stop("Spectral column names must be wavelengths; use 'id', 'colvar' and 'panel' for the other columns.")
  }
  spectra <- as.matrix(x[spec_cols])
  if (!is.numeric(spectra)) {
    stop("The spectral columns must be numeric.", call. = FALSE)
  }
  if (!is.null(transform)) {
    spectra <- transform_spectra(x[spec_cols], transform)
    wl <- parse_wavelength(colnames(spectra))
  }
  # the window of each channel, after the transformation of the whole spectra
  window <- rep(1L, length(wl))
  if (!is.null(windows)) {
    window <- window_of(wl, windows)
    keep <- window > 0
    spectra <- spectra[, keep, drop = FALSE]
    wl <- wl[keep]
    window <- window[keep]
  }
  marks <- if (is.null(lines)) NULL else line_marks(lines, wl, window)

  meta <- spectra_meta(x, id_name, col_name, panel_name, panel_tags)
  curves <- if (summary == "none") {
    list(meta = meta, center = spectra)
  } else {
    summarize_spectra(spectra, meta, id_name, col_name, summary)
  }
  fill <- color_as == "fill"
  long <- spectra_long(curves, wl, window, offset, fill)
  if (drop_na) {
    long <- long[!is.na(long$intensity), ]
  }
  split_windows <- length(windows) > 1 || any(nzchar(names(windows)))

  intensity <- .group <- .base <- .lower <- .upper <- NULL

  p <- ggplot2::ggplot(long) +
    ggplot2::aes(x = wavelength, y = intensity, group = .group)

  if (!is.null(marks)) {
    # in the panels of their window (`.window`)
    p <- p + ggplot2::geom_vline(data = marks$at, ggplot2::aes(xintercept = .data$wavelength),
                                 linetype = "dashed", colour = "grey60", linewidth = 0.3)
  }
  colour_by <- if (!is.null(col_name)) {
    rlang::quo(.data[[!!col_name]])
  } else if (!is.null(id_name)) {
    rlang::quo(factor(.data[[!!id_name]]))
  }
  band <- summary != "none" && !fill
  layers <- list()
  if (band) {
    layers$band <- if (is.null(colour_by)) {
      ggplot2::geom_ribbon(ggplot2::aes(ymin = .lower, ymax = .upper), fill = "#002a52",
                           alpha = 0.2, colour = NA)
    } else {
      ggplot2::geom_ribbon(ggplot2::aes(ymin = .lower, ymax = .upper, fill = !!colour_by),
                           alpha = 0.25, colour = NA)
    }
  }
  if (fill) {
    # opaque fills when the spectra are stacked, translucent when they overlap
    stacked <- !is.null(offset) && offset[2] != 0
    alpha <- if (stacked) 1 else 0.6
    layers$spectra <- if (is.null(colour_by)) {
      # #667f97 is #002a52 at alpha 0.6 on white
      ggplot2::geom_ribbon(ggplot2::aes(ymin = .base, ymax = intensity),
                           fill = if (stacked) "#667f97" else "#002a52", alpha = alpha,
                           colour = "#002a52", linewidth = 0.6 * linewidth, outline.type = "upper")
    } else {
      ggplot2::geom_ribbon(ggplot2::aes(ymin = .base, ymax = intensity, fill = !!colour_by),
                           alpha = alpha, colour = "grey20", linewidth = 0.6 * linewidth,
                           outline.type = "upper")
    }
  } else {
    layers$spectra <- if (is.null(colour_by)) {
      ggplot2::geom_line(color = "#002a52", linewidth = linewidth)
    } else {
      ggplot2::geom_line(ggplot2::aes(colour = !!colour_by), linewidth = linewidth)
    }
  }
  if (!is.null(dpi) && !interactive) {
    layers <- lapply(layers, rasterize_layer, dpi = dpi)
  }
  p <- p + layers

  if (!is.null(colour_by)) {
    aesthetics <- c(if (!fill) "colour", if (fill || band) "fill")
    n_levels <- if (is.null(col_name)) length(unique(stats::na.omit(curves$meta[[id_name]]))) else 0
    p <- p + palette_scale(palette, discrete = is.null(col_name), aesthetics = aesthetics,
                           name = legend_title %||% col_name %||% id_name, n = n_levels)
  }
  if (label_spectra) {
    ends <- spectra_ends(long, curves$meta, id_name, col_name, summary)
    # right of the spectra (in the last window), moved apart vertically by
    # ggrepel
    span <- diff(range(long$wavelength[long$.window == max(long$.window)]))
    p <- p +
      ggrepel::geom_text_repel(data = ends, ggplot2::aes(x = .data$wavelength, y = .data$intensity,
                                                         label = .data$.label),
                               hjust = 0, direction = "y", nudge_x = 0.01 * span,
                               xlim = c(max(long$wavelength) + 0.005 * span, Inf),
                               size = 0.8 * base_size / ggplot2::.pt, colour = "grey20",
                               segment.colour = "grey60", min.segment.length = 0.2,
                               max.overlaps = Inf, seed = 1, inherit.aes = FALSE) +
      ggplot2::coord_cartesian(clip = "off")
  }
  # labels at the right end need room; the emission lines are labeled on a
  # top axis, above the spectra
  x_scale <- list()
  if (label_spectra) {
    room <- 0.012 * max(0, nchar(ends$.label))
    if (split_windows) {
      # in the last window only, a fraction of the width of the plot
      nw <- length(windows)
      p <- p + ggplot2::geom_blank(
        data = data.frame(wavelength = max(long$wavelength) + (0.05 + room * nw) * span,
                          intensity = ends$intensity[1], .window = nw),
        ggplot2::aes(x = .data$wavelength, y = .data$intensity), inherit.aes = FALSE
      )
    } else {
      x_scale$expand <- ggplot2::expansion(mult = c(0.05, 0.05 + room))
    }
  }
  if (!is.null(marks)) {
    x_scale$sec.axis <- ggplot2::dup_axis(name = NULL, breaks = marks$labels$wavelength,
                                          labels = marks$labels$label)
  }
  if (length(x_scale) > 0) {
    p <- p + do.call(ggplot2::scale_x_continuous, x_scale)
  }
  p <- p + ggplot2::scale_y_continuous(labels = plain_numbers)

  p <- p +
    ggplot2::labs(x = xlab, y = ylab, title = title) +
    ggplot2::theme_classic(base_size = base_size) +
    ggplot2::theme(
      axis.line = ggplot2::element_line(color = "#4b4b4b", linewidth = base_size / 16),
      axis.ticks = ggplot2::element_line(color = "#4b4b4b"),
      axis.line.x.top = ggplot2::element_blank(),
      axis.ticks.x.top = ggplot2::element_blank(),
      axis.text.x.top = ggplot2::element_text(angle = 90, hjust = 0, vjust = 0.5)
    ) +
    legend_theme(legend)

  strips <- ggplot2::theme(strip.background = ggplot2::element_rect(fill = "grey95", colour = NA),
                           strip.text = ggplot2::element_text(hjust = 0))
  if (split_windows) {
    # one column per window, with its own wavelength axis; the groups of
    # `panel` in rows
    labels <- window_labels(windows, tags = panel_tags && is.null(panel_name))
    free <- if (scales == "free_y") "free" else "free_x"
    p <- p + strips + if (is.null(panel_name)) {
      ggplot2::facet_wrap(ggplot2::vars(.data$.window), nrow = 1, scales = free,
                          labeller = ggplot2::as_labeller(labels), axes = "all",
                          axis.labels = "margins")
    } else {
      ggplot2::facet_grid(rows = ggplot2::vars(.data$.panel), cols = ggplot2::vars(.data$.window),
                          scales = free, labeller = ggplot2::labeller(.window = labels),
                          axes = "all", axis.labels = "margins")
    }
    if (!any(nzchar(labels))) {
      p <- p + ggplot2::theme(strip.background.x = ggplot2::element_blank(),
                              strip.text.x = ggplot2::element_blank())
    }
  } else if (!is.null(panel_name)) {
    p <- p + strips +
      ggplot2::facet_wrap(ggplot2::vars(.data$.panel),
                          ncol = if (layout == "vertical") 1 else NULL,
                          nrow = if (layout == "horizontal") 1 else NULL,
                          scales = scales, axes = "all", axis.labels = "margins")
  }
  if (grid) {
    p <- p + ggplot2::theme(panel.grid.major = ggplot2::element_line(colour = "grey90", linewidth = 0.3))
  }
  p <- finish_title(p)

  if (!interactive) {
    return(p)
  }
  rlang::check_installed("plotly", reason = "to create interactive plots.")
  out <- plotly::ggplotly(p, tooltip = "all")
  if (!is.null(title)) {
    out <- plotly::layout(out, title = plotly_title(title))
  }
  out
}

# ---- internals ---------------------------------------------------------------

# The wavelength windows of `wavelength`: a list of ranges c(from, to), in
# increasing order and named by their labels ("" when unnamed), or NULL.
spectra_windows <- function(wavelength) {
  if (is.null(wavelength)) {
    return(NULL)
  }
  windows <- if (is.list(wavelength) && !is.data.frame(wavelength)) wavelength else list(wavelength)
  is_range <- function(w) is.numeric(w) && length(w) == 2 && !anyNA(w) && w[1] < w[2]
  if (length(windows) == 0 || !all(vapply(windows, is_range, logical(1)))) {
    stop("'wavelength' must be two increasing wavelengths c(from, to), or a list of them.",
         call. = FALSE)
  }
  labels <- names(windows) %||% rep("", length(windows))
  labels[is.na(labels)] <- ""
  from <- vapply(windows, `[[`, numeric(1), 1)
  to <- vapply(windows, `[[`, numeric(1), 2)
  o <- order(from)
  if (any(from[o][-1] < to[o][-length(o)])) {
    stop("The ranges of 'wavelength' must not overlap.", call. = FALSE)
  }
  stats::setNames(lapply(o, function(i) unname(windows[[i]])), labels[o])
}

# The window of each wavelength `wl` (0 outside them).
window_of <- function(wl, windows) {
  window <- integer(length(wl))
  for (i in seq_along(windows)) {
    inside <- wl >= windows[[i]][1] & wl <= windows[[i]][2]
    if (!any(inside)) {
      range <- if (length(windows) > 1) paste0(" (", windows[[i]][1], "-", windows[[i]][2], " nm)")
      stop("No wavelength of the spectra is within 'wavelength'", range, ".", call. = FALSE)
    }
    window[inside] <- i
  }
  window
}

# Applies `transform` to the spectra (a data frame of the spectral columns):
# a function, a formula (as a purrr lambda), or a list of them, in order. Each
# step must return the spectra, one row per spectrum with columns named by
# their wavelength, as a data frame or a matrix, or a list holding them as
# `correction` (as snv(), msc() and the baseline corrections). Returns a
# matrix.
transform_spectra <- function(spectra, transform) {
  steps <- if (is.list(transform)) transform else list(transform)
  is_step <- function(f) is.function(f) || rlang::is_formula(f)
  if (length(steps) == 0 || !all(vapply(steps, is_step, logical(1)))) {
    stop("'transform' must be a function, a formula or a list of them.", call. = FALSE)
  }
  n <- nrow(spectra)
  for (i in seq_along(steps)) {
    step <- if (length(steps) > 1) paste0(" (step ", i, ")") else ""
    out <- rlang::as_function(steps[[i]])(spectra)
    if (is.list(out) && !is.data.frame(out)) {
      out <- out$correction
    }
    if (!(is.data.frame(out) || is.matrix(out)) || nrow(out) != n) {
      stop("'transform'", step, " must return the spectra, one row per spectrum: a data frame, ",
           "a matrix, or a list holding them as 'correction'.", call. = FALSE)
    }
    if (is.matrix(out)) {
      out <- tibble::as_tibble(out, .name_repair = "minimal")
    }
    if (ncol(out) == 0 || anyNA(parse_wavelength(names(out)))) {
      stop("The spectra returned by 'transform'", step, " must have columns named by their ",
           "wavelength.", call. = FALSE)
    }
    if (!all(vapply(out, is.numeric, logical(1)))) {
      stop("The spectra returned by 'transform'", step, " must be numeric.", call. = FALSE)
    }
    spectra <- out
  }
  as.matrix(spectra)
}

# The variables of each spectrum: `id` and `colvar` under their names, and the
# panel as the factor `.panel` (its levels tagged (a), (b), ... on request).
spectra_meta <- function(x, id_name, col_name, panel_name, panel_tags) {
  meta <- data.frame(.row = seq_len(nrow(x)))
  for (nm in unique(c(id_name, col_name))) {
    meta[[nm]] <- x[[nm]]
  }
  if (!is.null(panel_name)) {
    panel <- x[[panel_name]]
    panel <- if (is.factor(panel)) droplevels(panel) else factor(panel)
    if (panel_tags) {
      levels(panel) <- paste(panel_tag(nlevels(panel)), levels(panel))
    }
    meta$.panel <- panel
  }
  meta
}

# The labels of the wavelength windows (their names), tagged (a), (b), ... on
# request, named by the index of the window.
window_labels <- function(windows, tags) {
  labels <- names(windows)
  if (tags) {
    labels <- trimws(paste(panel_tag(length(labels)), labels))
  }
  stats::setNames(labels, seq_along(labels))
}

panel_tag <- function(k) {
  paste0("(", if (k <= 26) letters[seq_len(k)] else seq_len(k), ")")
}

# The mean (with +/- one SD) or median (with the quartiles) spectrum of each
# group of rows sharing a panel and an id; `colvar` is averaged per group.
summarize_spectra <- function(spectra, meta, id_name, col_name, summary) {
  keys <- intersect(c(".panel", id_name), names(meta))
  key <- if (length(keys) == 0) {
    rep("all", nrow(meta))
  } else {
    do.call(paste, c(lapply(meta[keys], as.character), sep = "\r"))
  }
  groups <- split(seq_len(nrow(meta)), factor(key, levels = unique(key)))
  bands <- lapply(groups, function(rows) summary_band(spectra[rows, , drop = FALSE], summary))
  part <- function(name) do.call(rbind, lapply(bands, `[[`, name))
  out <- meta[vapply(groups, `[`, integer(1), 1), , drop = FALSE]
  if (!is.null(col_name)) {
    out[[col_name]] <- vapply(groups, function(rows) mean(meta[[col_name]][rows], na.rm = TRUE),
                              numeric(1))
  }
  list(meta = out, center = part("center"), lower = part("lower"), upper = part("upper"))
}

summary_band <- function(s, summary) {
  if (summary == "mean") {
    center <- colMeans(s, na.rm = TRUE)
    n <- colSums(!is.na(s))
    sd <- sqrt(colSums(sweep(s, 2, center)^2, na.rm = TRUE) / (n - 1))
    sd[n < 2] <- NA
    list(center = center, lower = center - sd, upper = center + sd)
  } else {
    q <- apply(s, 2, stats::quantile, probs = c(0.25, 0.5, 0.75), na.rm = TRUE, names = FALSE)
    list(center = q[2, ], lower = q[1, ], upper = q[3, ])
  }
}

# One row per curve and wavelength, offset by the position of the curve in
# its panel. `.draw` is the drawing order: filled curves are drawn from the
# back (the top of a stack) to the front. `.group` draws each detector
# segment of a curve as its own line, in the drawing order. `.window` is the
# wavelength window of each channel.
spectra_long <- function(curves, wl, window, offset, fill) {
  meta <- curves$meta
  n <- nrow(meta)
  position <- if (is.null(meta$.panel)) {
    seq_len(n)
  } else {
    stats::ave(seq_len(n), match(meta$.panel, unique(meta$.panel)), FUN = seq_along)
  }
  index <- rep(seq_len(n), times = length(wl))
  long <- meta[index, , drop = FALSE]
  rownames(long) <- NULL
  long$.curve <- index
  long$.draw <- if (fill && (is.null(offset) || offset[2] >= 0)) n + 1 - index else index
  segment <- spectra_segments(wl)
  long$.group <- (long$.draw - 1) * max(segment) + rep(segment, each = n)
  long$wavelength <- rep(wl, each = n)
  long$.window <- rep(window, each = n)
  long$intensity <- as.vector(curves$center)
  if (!is.null(curves$lower)) {
    long$.lower <- as.vector(curves$lower)
    long$.upper <- as.vector(curves$upper)
  }
  long$.base <- 0
  if (!is.null(offset)) {
    shift <- position[index] - 1
    long$wavelength <- long$wavelength + shift * offset[1]
    long$.base <- shift * offset[2]
    long$intensity <- long$intensity + long$.base
    if (!is.null(curves$lower)) {
      long$.lower <- long$.lower + long$.base
      long$.upper <- long$.upper + long$.base
    }
  }
  long
}

# The detector segments of the spectral columns (see wavelength_segments()),
# drawn as separate lines: a line does not cross a gap between detectors, nor
# zigzag between the channels of two overlapping ones. Columns in decreasing
# or no wavelength order, which would make most channels a segment, are
# split at the gaps only.
spectra_segments <- function(wl) {
  segment <- wavelength_segments(wl)
  if (max(segment) > length(wl) / 4) {
    o <- order(wl)
    segment[o] <- wavelength_segments(wl[o])
  }
  segment
}

# The right end of each curve, with its label: the id, else the value of
# colvar, else the row number (or the name of the summary).
spectra_ends <- function(long, meta, id_name, col_name, summary) {
  long <- long[!is.na(long$intensity), ]
  last <- vapply(split(seq_len(nrow(long)), long$.curve),
                 function(rows) rows[which.max(long$wavelength[rows])], integer(1))
  ends <- long[last, , drop = FALSE]
  ends$.label <- if (!is.null(id_name)) {
    as.character(ends[[id_name]])
  } else if (!is.null(col_name)) {
    vapply(ends[[col_name]], format, character(1), digits = 3)
  } else if (summary != "none") {
    c(mean = "Mean", median = "Median")[[summary]]
  } else {
    as.character(ends$.curve)
  }
  ends
}

# The emission lines within the wavelength range of each window: their
# wavelengths and windows (`at`), and their labels. Lines closer than 2% of
# the range of their window share one label, at their mean wavelength, such
# as "Ca II 393.37, 396.85".
line_marks <- function(lines, wl, window = rep(1L, length(wl))) {
  if (!is.data.frame(lines) || !all(c("species", "wavelength") %in% names(lines)) ||
      !is.numeric(lines$wavelength)) {
    stop("'lines' must be a data frame with the columns 'species' and 'wavelength', ",
         "such as a table returned by libs_lines().", call. = FALSE)
  }
  marks <- lapply(sort(unique(window)), function(w) {
    range <- range(wl[window == w])
    inside <- !is.na(lines$wavelength) & lines$wavelength >= range[1] &
      lines$wavelength <= range[2]
    if (!any(inside)) {
      return(NULL)
    }
    found <- unique(data.frame(species = as.character(lines$species[inside]),
                               wavelength = lines$wavelength[inside]))
    found <- found[order(found$wavelength), ]
    group <- cumsum(c(TRUE, diff(found$wavelength) >= 0.02 * diff(range)))
    labels <- lapply(split(found, group), function(g) {
      species <- unique(g$species)
      text <- vapply(species, function(s) {
        paste(s, paste(format_wavelength(g$wavelength[g$species == s], 2), collapse = ", "))
      }, character(1))
      data.frame(wavelength = mean(g$wavelength), label = paste(text, collapse = ", "))
    })
    list(at = data.frame(wavelength = found$wavelength, .window = w),
         labels = do.call(rbind, labels))
  })
  marks <- marks[!vapply(marks, is.null, logical(1))]
  if (length(marks) == 0) {
    warning("None of 'lines' is within the wavelength range of the spectra.", call. = FALSE)
    return(NULL)
  }
  list(at = do.call(rbind, lapply(marks, `[[`, "at")),
       labels = do.call(rbind, lapply(marks, `[[`, "labels")))
}

viridis_palettes <- c("viridis", "magma", "inferno", "plasma", "cividis", "rocket", "mako", "turbo")

check_palette <- function(palette) {
  is_colour <- function(x) {
    vapply(x, function(col) !inherits(try(grDevices::col2rgb(col), silent = TRUE), "try-error"),
           logical(1))
  }
  ok <- is.character(palette) && length(palette) >= 1 && !anyNA(palette) &&
    ((length(palette) == 1 && palette %in% viridis_palettes) ||
       (length(palette) >= 2 && all(is_colour(palette))))
  if (!ok) {
    stop("'palette' must be the name of a viridis palette (",
         paste0("\"", viridis_palettes, "\"", collapse = ", "), ") or at least two colors.",
         call. = FALSE)
  }
  invisible(palette)
}

# The color scale of colvar (continuous) or id (discrete with n levels). The
# lightest end of the viridis palettes is left out, too pale on white.
palette_scale <- function(palette, discrete, aesthetics, name, n) {
  if (length(palette) == 1) {
    if (discrete) {
      ggplot2::scale_colour_viridis_d(name = name, option = palette, end = 0.9, direction = -1,
                                      aesthetics = aesthetics)
    } else {
      ggplot2::scale_colour_viridis_c(name = name, option = palette, end = 0.9,
                                      aesthetics = aesthetics)
    }
  } else if (discrete) {
    values <- if (length(palette) >= n) palette else grDevices::colorRampPalette(palette)(n)
    ggplot2::scale_colour_manual(name = name, values = values, aesthetics = aesthetics)
  } else {
    ggplot2::scale_colour_gradientn(name = name, colours = palette, aesthetics = aesthetics)
  }
}

legend_theme <- function(legend) {
  if (legend == "inside") {
    ggplot2::theme(legend.position = "inside", legend.position.inside = c(0.99, 0.99),
                   legend.justification.inside = c(1, 1),
                   legend.background = ggplot2::element_rect(fill = "white", colour = NA))
  } else {
    ggplot2::theme(legend.position = legend)
  }
}

# Axis numbers in plain notation, with thousands separators ("100,000" rather
# than "1e+05").
plain_numbers <- function(x) {
  out <- format(x, big.mark = ",", scientific = FALSE, trim = TRUE)
  out[is.na(x)] <- NA
  out
}

raster_dpi <- function(rasterize) {
  if (isFALSE(rasterize)) {
    return(NULL)
  }
  if (isTRUE(rasterize)) {
    return(300)
  }
  if (!is.numeric(rasterize) || length(rasterize) != 1 || is.na(rasterize) || rasterize <= 0) {
    stop("'rasterize' must be TRUE, FALSE or a resolution in dpi.", call. = FALSE)
  }
  rasterize
}

# A layer whose grobs are drawn as an image, at the size of the panel and the
# resolution `dpi`, when the plot is rendered (as by the ggrastr package).
rasterize_layer <- function(layer, dpi) {
  geom <- layer$geom
  ggplot2::ggproto(NULL, layer, geom = ggplot2::ggproto(NULL, geom,
    draw_layer = function(self, data, params, layout, coord) {
      grobs <- ggplot2::ggproto_parent(geom, self)$draw_layer(data, params, layout, coord)
      lapply(grobs, function(g) grid::gTree(children = grid::gList(g), dpi = dpi,
                                            cl = "specproc_raster"))
    }
  ))
}

#' @exportS3Method grid::makeContext
#' @noRd
makeContext.specproc_raster <- function(x) {
  width <- grid::convertWidth(grid::unit(1, "npc"), "in", valueOnly = TRUE)
  height <- grid::convertHeight(grid::unit(1, "npc"), "in", valueOnly = TRUE)
  if (width <= 0 || height <= 0) {
    return(grid::nullGrob())
  }
  current <- grDevices::dev.cur()
  capture <- ragg::agg_capture(width = width, height = height, units = "in", res = x$dpi,
                               background = "transparent")
  image <- tryCatch({
    # the grobs are in native units, of the 0-1 scales of a new viewport (the
    # root viewport of a device has other scales)
    grid::pushViewport(grid::viewport())
    grid::grid.draw(x$children)
    grid::popViewport()
    capture(native = TRUE)
  }, finally = {
    grDevices::dev.off()
    grDevices::dev.set(current)
  })
  grid::rasterGrob(image, width = grid::unit(width, "in"), height = grid::unit(height, "in"))
}

Try the specProc package in your browser

Any scripts or data that you put into this service are public.

specProc documentation built on Nov. 20, 2026, 5:11 p.m.