R/libs_lines.R

Defines functions stage_traces check_bands_table band_colours band_traces band_segments line_segments line_key lines_plotly as_spectrum check_lines_table empty_line_list rank_lines nist_empty_lines fetch_species_lines check_line_settings plot_lines libs_lines

Documented in libs_lines plot_lines

#' @title Candidate Emission Lines for LIBS Spectra
#'
#' @author Christian L. Goueguel
#'
#' @description
#' Lists the lines of the selected atoms and ions that are expected to be the
#' strongest in a plasma at a given temperature, from the NIST Atomic
#' Spectra Database, to help identify the emission lines of a spectrum.
#'
#' @details
#' For each species, the lines with a transition probability are retrieved
#' with [nist_lines()] (and cached for the R session). Their relative
#' intensities in a plasma in local thermodynamic equilibrium at
#' temperature \eqn{T} are
#' \deqn{I \propto \frac{g_k A_{ki}}{\lambda} \exp\left(-\frac{E_k}{k_B T}\right)}
#' normalized to the strongest line of the species in the range. The
#' intensities are relative within each species: comparing species would
#' need their concentrations and, between ionization stages, the Saha
#' equation. Self-absorption, which weakens resonance lines, is ignored.
#'
#' The `top` strongest lines of each species with a relative intensity of
#' at least `min_relative` are kept. [plot_lines()] overlays them on a
#' spectrum, and [line_finder()] does so interactively.
#'
#' @param species A character vector of emitters in spectroscopic notation,
#'   such as `c("Ca I", "Ca II", "Mg I")`.
#' @param wavelength A numeric vector of length 2: the wavelength range, in
#'   nm. Default is 200 to 900 nm.
#' @param temperature The plasma temperature, in K. Default is 10000.
#' @param top The maximum number of lines kept per species. Default is 20.
#' @param min_relative The minimum relative intensity of the lines kept,
#'   between 0 and 1. Default is 0.
#' @param timeout The download timeout, in seconds. Default is 120.
#'
#' @return A tibble with one row per line, sorted by wavelength, and
#'   columns `species`, `element`, `stage` (1 for neutral atoms, 2 for
#'   singly charged ions, ...), `wavelength` (nm), `relative_intensity`,
#'   `Aki`, `Ek`, `gk`, `accuracy`, `lower` and `upper`. Species without
#'   lines in the range contribute no rows.
#'
#' @seealso [plot_lines()], [line_finder()], [nist_lines()]
#' @export libs_lines
#'
#' @examples
#' \donttest{
#' # needs an internet connection; gives up after 20 s if NIST does not answer
#' lines <- try(libs_lines(c("Ca I", "Ca II"), wavelength = c(390, 450), top = 5,
#'                         timeout = 20))
#' if (!inherits(lines, "try-error")) lines
#' }
libs_lines <- function(species, wavelength = c(200, 900), temperature = 10000, top = 20,
                       min_relative = 0, timeout = 120) {
  if (!is.character(species) || length(species) == 0) {
    stop("'species' must be a character vector, such as c(\"Ca I\", \"Ca II\").")
  }
  if (!is.numeric(wavelength) || length(wavelength) != 2 || anyNA(wavelength) || any(wavelength <= 0)) {
    stop("'wavelength' must be a numeric vector of length 2 (nm).")
  }
  check_line_settings(temperature, top, min_relative)
  raw <- lapply(unique(species), fetch_species_lines, wavelength = sort(wavelength), timeout = timeout)
  rank_lines(do.call(rbind, raw), temperature = temperature, top = top,
             min_relative = min_relative, wavelength = wavelength)
}

#' @title Overlay Emission Lines on a Spectrum
#'
#' @description
#' Plots a spectrum with vertical markers at the wavelengths of candidate
#' emission lines, colored by ionization stage, and at the heads of
#' molecular bands, to identify the lines and bands of the spectrum.
#'
#' @details
#' With `interactive = TRUE`, the plot is made with plotly: the spectrum is
#' drawn with WebGL, the lines of each ionization stage form one trace that
#' can be shown or hidden from the legend, and hovering over a line shows its
#' species, wavelength, transition probability, upper-level energy and
#' accuracy grade. Otherwise, a ggplot is returned.
#'
#' With `scale_markers = TRUE`, the height of each marker is its relative
#' intensity (see [libs_lines()]) times the maximum of the spectrum;
#' otherwise all markers span the full height.
#'
#' The heads of molecular bands (`bands`, see [molecular_bands()]) are drawn
#' as dashed markers, one color per molecule, scaled by their relative
#' intensity within their system.
#'
#' @param spectrum A spectrum: a numeric vector named by wavelength, or a
#'   one-row matrix or data frame whose column names are the wavelengths.
#'   Average several spectra first.
#' @param lines A tibble returned by [libs_lines()], or `NULL` to draw only
#'   molecular bands.
#' @param shift A wavelength shift, in nm, added to the line and band
#'   wavelengths to correct the wavelength calibration of the spectrometer.
#'   Default is 0.
#' @param scale_markers A logical: scale the markers by the relative
#'   intensity of the lines (`TRUE`, default) or draw them full height.
#' @param interactive A logical: plotly (`TRUE`, default) or ggplot2.
#' @param title An optional plot title.
#' @param bands An optional tibble of molecular band heads returned by
#'   [molecular_bands()].
#' @param wavelength Optional (`NULL` by default). The wavelength range
#'   `c(min, max)` to draw, in nm. The markers are scaled to the maximum of
#'   the spectrum within the range, and the lines and bands outside it are
#'   left out.
#' @param xlab,ylab The axis titles. Default are `"Wavelength (nm)"` and
#'   `"Intensity (arb. units)"`.
#' @param base_size The size of the text, in points. Default is 11. Ignored
#'   for interactive plots.
#' @param linewidth The width of the spectrum line. Default is 0.3.
#' @param spectrum_color The color of the spectrum. Default is `"grey35"`.
#' @param marker_linewidth The width of the line and band markers. Default is
#'   0.5.
#' @param marker_alpha The opacity of the line and band markers, between 0
#'   and 1. Default is 0.7.
#'
#' @return A plotly or ggplot object.
#'
#' @seealso [libs_lines()], [molecular_bands()], [line_finder()]
#' @export plot_lines
#'
#' @examples
#' data(forageLIBS)
#' spectrum <- colMeans(forageLIBS[-(1:14)])
#' # the K I doublet, with the atomic data of the NIST database
#' lines <- tibble::tibble(
#'   species = "K I", element = "K", stage = 1L, wavelength = c(404.414, 404.721),
#'   relative_intensity = c(1, 0.5), Aki = c(1.15e6, 1.07e6), Ek = c(3.065, 3.063),
#'   gk = c(4, 2), accuracy = "A", lower = "4s 2S", upper = c("5p 2P* 3/2", "5p 2P* 1/2")
#' )
#' plot_lines(spectrum, lines, wavelength = c(403, 406), interactive = FALSE)
#'
plot_lines <- function(spectrum, lines = NULL, shift = 0, scale_markers = TRUE, interactive = TRUE,
                       title = NULL, bands = NULL, wavelength = NULL, xlab = "Wavelength (nm)",
                       ylab = "Intensity (arb. units)", base_size = 11, linewidth = 0.3,
                       spectrum_color = "grey35", marker_linewidth = 0.5, marker_alpha = 0.7) {
  spec <- as_spectrum(spectrum)
  if (is.null(lines) && is.null(bands)) {
    stop("Give 'lines' (from libs_lines()) or 'bands' (from molecular_bands()).", call. = FALSE)
  }
  if (is.null(lines)) lines <- empty_line_list() else check_lines_table(lines)
  if (!is.null(bands)) check_bands_table(bands)
  check_number(shift, "shift")
  check_flag(scale_markers, "scale_markers")
  check_flag(interactive, "interactive")
  check_plot_text(title, xlab, ylab, base_size)
  check_size(linewidth, "linewidth")
  check_colour(spectrum_color, "spectrum_color")
  check_size(marker_linewidth, "marker_linewidth")
  check_alpha(marker_alpha, "marker_alpha")
  window <- wavelength_window(wavelength)
  if (!is.null(window)) {
    spec <- spec[in_window(spec$wavelength, window), , drop = FALSE]
    if (nrow(spec) < 2) {
      stop("'spectrum' has fewer than 2 channels in the 'wavelength' range.", call. = FALSE)
    }
    lines <- lines[in_window(lines$wavelength + shift, range(spec$wavelength)), , drop = FALSE]
  }
  segments <- line_segments(lines, spec, shift, scale_markers)
  band_segs <- band_segments(bands, spec, shift, scale_markers)
  if (interactive) {
    rlang::check_installed("plotly", reason = "for interactive plots.")
    style <- list(color = plotly_colour(spectrum_color), width = plotly_width(linewidth),
                  marker_width = plotly_width(marker_linewidth), opacity = marker_alpha)
    p <- lines_plotly(spec, segments, style = style)
    for (trace in band_traces(band_segs, style)) {
      p <- do.call(plotly::add_trace, c(list(p), trace))
    }
    plotly::layout(p, title = plotly_title(title),
                   xaxis = list(title = xlab), yaxis = list(title = ylab),
                   legend = list(orientation = "h", y = -0.15), hovermode = "closest")
  } else {
    # markers on top of the spectrum, semi-transparent; one color scale for
    # the ionization stages and the molecules
    colours <- c(stage_colours, band_colours(band_segs$molecule))
    p <- ggplot2::ggplot() +
      ggplot2::geom_line(data = spec, ggplot2::aes(.data$wavelength, .data$intensity),
                         colour = spectrum_color, linewidth = linewidth) +
      ggplot2::geom_segment(
        data = segments,
        ggplot2::aes(x = .data$x, xend = .data$x, y = 0, yend = .data$height, colour = .data$stage_label),
        linewidth = marker_linewidth, alpha = marker_alpha
      ) +
      ggplot2::geom_segment(
        data = band_segs,
        ggplot2::aes(x = .data$x, xend = .data$x, y = 0, yend = .data$height, colour = .data$molecule),
        linewidth = marker_linewidth, alpha = marker_alpha, linetype = "dashed"
      ) +
      ggplot2::scale_colour_manual(values = colours, name = NULL, drop = TRUE) +
      ggplot2::scale_y_continuous(labels = plain_numbers) +
      ggplot2::labs(x = xlab, y = ylab, title = title) +
      ggplot2::theme_bw(base_size = base_size) +
      ggplot2::theme(legend.position = "bottom")
    finish_title(p)
  }
}

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

stage_colours <- c(I = "#1b9e77", II = "#d95f02", III = "#7570b3", IV = "#e7298a", V = "#66a61e")

check_line_settings <- function(temperature, top, min_relative) {
  check_number(temperature, "temperature", lower = 0, lower_open = TRUE)
  check_count(top, "top")
  check_number(min_relative, "min_relative", lower = 0, upper = 1)
  invisible(TRUE)
}

# Lines of one species with a transition probability; no rows when NIST has
# none in the range (other errors, such as network failures, propagate).
fetch_species_lines <- function(species, wavelength, timeout = 120) {
  tryCatch(
    nist_lines(species, wavelength, with_aki = TRUE, timeout = timeout),
    error = function(e) {
      if (grepl("returned no data", conditionMessage(e), fixed = TRUE)) {
        nist_empty_lines(parse_species(species)$label)
      } else {
        stop(e)
      }
    }
  )
}

nist_empty_lines <- function(label) {
  tibble::tibble(species = character(), wavelength = numeric(), Aki = numeric(),
                 fik = numeric(), accuracy = character(), Ei = numeric(), Ek = numeric(),
                 gi = numeric(), gk = numeric(), lower = character(), upper = character(),
                 intensity = character())
}

# Relative LTE intensities, and the strongest lines of each species.
rank_lines <- function(raw, temperature, top, min_relative, wavelength = NULL) {
  if (is.null(raw) || nrow(raw) == 0) {
    return(empty_line_list())
  }
  raw <- raw[!is.na(raw$Aki) & !is.na(raw$Ek) & !is.na(raw$gk) & !is.na(raw$wavelength), ]
  if (!is.null(wavelength)) {
    raw <- raw[raw$wavelength >= min(wavelength) & raw$wavelength <= max(wavelength), ]
  }
  if (nrow(raw) == 0) {
    return(empty_line_list())
  }
  strength <- raw$gk * raw$Aki / raw$wavelength * exp(-raw$Ek / (k_boltzmann_ev * temperature))
  relative <- strength / stats::ave(strength, raw$species, FUN = max)
  keep <- unlist(lapply(split(seq_len(nrow(raw)), raw$species), function(i) {
    i <- i[relative[i] >= min_relative]
    i[order(relative[i], decreasing = TRUE)][seq_len(min(top, length(i)))]
  }), use.names = FALSE)
  keep <- keep[!is.na(keep)]
  parsed <- lapply(raw$species[keep], parse_species)
  out <- tibble::tibble(
    species = raw$species[keep],
    element = vapply(parsed, `[[`, character(1), "element"),
    stage = vapply(parsed, function(p) p$charge + 1L, integer(1)),
    wavelength = raw$wavelength[keep],
    relative_intensity = relative[keep],
    Aki = raw$Aki[keep],
    Ek = raw$Ek[keep],
    gk = raw$gk[keep],
    accuracy = raw$accuracy[keep],
    lower = raw$lower[keep],
    upper = raw$upper[keep]
  )
  out[order(out$wavelength), ]
}

empty_line_list <- function() {
  tibble::tibble(species = character(), element = character(), stage = integer(),
                 wavelength = numeric(), relative_intensity = numeric(), Aki = numeric(),
                 Ek = numeric(), gk = numeric(), accuracy = character(), lower = character(),
                 upper = character())
}

check_lines_table <- function(lines) {
  needed <- c("species", "stage", "wavelength", "relative_intensity")
  if (!is.data.frame(lines) || !all(needed %in% names(lines))) {
    stop("'lines' must be a table returned by libs_lines().", call. = FALSE)
  }
  invisible(lines)
}

# A spectrum as a data frame of wavelength and intensity.
as_spectrum <- function(spectrum) {
  if (is.data.frame(spectrum) || is.matrix(spectrum)) {
    if (nrow(spectrum) != 1) {
      stop("'spectrum' must be a single spectrum (one row); average several spectra first.",
           call. = FALSE)
    }
    values <- as_numeric_matrix(spectrum, "spectrum")[1, ]
  } else if (is.numeric(spectrum)) {
    values <- spectrum
  } else {
    stop("'spectrum' must be a named numeric vector or a one-row matrix or data frame.", call. = FALSE)
  }
  wavelength <- parse_wavelength(names(values) %||% character(0))
  if (length(wavelength) != length(values) || anyNA(wavelength)) {
    stop("The names (or column names) of 'spectrum' must be the wavelengths.", call. = FALSE)
  }
  data.frame(wavelength = wavelength, intensity = unname(values))
}

# The style of the plotly spectrum and markers: the spectrum color and line
# width, and the width and opacity of the markers.
plotly_style <- list(color = "#595959", width = 1, marker_width = 1.5, opacity = 1)

# The spectrum and the line markers in plotly, from `source` (for the events
# of the line finder). With `heads`, each marker ends in a dot, easier to
# click than the end of a line.
lines_plotly <- function(spec, segments, source = "A", heads = FALSE, style = plotly_style) {
  p <- plotly::plot_ly(source = source)
  p <- plotly::add_trace(p, x = spec$wavelength, y = spec$intensity, type = "scattergl",
                         mode = "lines", name = "spectrum",
                         line = list(color = style$color, width = style$width), hoverinfo = "x+y")
  for (trace in stage_traces(segments, heads, style)) {
    p <- do.call(plotly::add_trace, c(list(p), trace))
  }
  p
}

# Key of a line: stays the same when the candidate lines are ranked again.
line_key <- function(lines) {
  sprintf("%s|%.4f|%.4f", lines$species, lines$wavelength, lines$Ek)
}

# Marker segments: one row per line, with its position, height, key and hover
# text.
line_segments <- function(lines, spec, shift, scale_markers) {
  top_value <- max(spec$intensity, na.rm = TRUE)
  if (!is.finite(top_value) || top_value <= 0) top_value <- 1
  if (nrow(lines) == 0) {
    return(data.frame(x = numeric(), height = numeric(), stage_label = character(),
                      key = character(), text = character()))
  }
  stage_label <- factor(roman_numerals[lines$stage], levels = roman_numerals)
  data.frame(
    x = lines$wavelength + shift,
    height = if (scale_markers) top_value * lines$relative_intensity else rep(top_value, nrow(lines)),
    stage_label = droplevels(stage_label),
    key = if (is.null(lines$Ek)) NA_character_ else line_key(lines),
    text = sprintf(
      "%s %.3f nm<br>relative intensity %.2f<br>A = %.2e s-1, Ek = %.2f eV, gk = %s<br>accuracy %s<br>%s - %s",
      lines$species, lines$wavelength, lines$relative_intensity,
      lines$Aki %||% NA, lines$Ek %||% NA, lines$gk %||% NA, lines$accuracy %||% "",
      lines$lower %||% "", lines$upper %||% ""
    ),
    stringsAsFactors = FALSE
  )
}

# Band markers: one row per band head, with its position, height, molecule
# and hover text.
band_segments <- function(bands, spec, shift, scale_markers) {
  if (is.null(bands) || nrow(bands) == 0) {
    return(data.frame(x = numeric(), height = numeric(), molecule = character(), text = character()))
  }
  top_value <- max(spec$intensity, na.rm = TRUE)
  if (!is.finite(top_value) || top_value <= 0) top_value <- 1
  inside <- bands$wavelength + shift >= min(spec$wavelength) &
    bands$wavelength + shift <= max(spec$wavelength)
  bands <- bands[inside, ]
  data.frame(
    x = bands$wavelength + shift,
    height = if (scale_markers) top_value * bands$relative_intensity else rep(top_value, nrow(bands)),
    molecule = bands$molecule,
    text = sprintf(
      "%s %s %s (%d,%d)<br>%s %.3f nm, origin %.3f nm<br>degraded to the %s, FCF %s<br>relative intensity %.2f",
      bands$molecule, bands$system, bands$name, bands$v_upper, bands$v_lower,
      ifelse(bands$head, "head", "band"), bands$wavelength, bands$origin,
      ifelse(is.na(bands$degraded), "?", bands$degraded),
      ifelse(is.na(bands$fcf), "unknown", sprintf("%.3f", bands$fcf)), bands$relative_intensity
    ),
    stringsAsFactors = FALSE
  )
}

# One dashed plotly trace per molecule.
band_traces <- function(segments, style = plotly_style) {
  if (nrow(segments) == 0) return(list())
  colours <- band_colours(segments$molecule)
  lapply(unique(segments$molecule), function(m) {
    s <- segments[segments$molecule == m, ]
    list(
      x = as.vector(rbind(s$x, s$x, NA)),
      y = as.vector(rbind(0, s$height, NA)),
      text = as.vector(rbind(s$text, s$text, NA)),
      type = "scatter", mode = "lines", name = paste(m, "bands"),
      line = list(color = unname(colours[m]), width = style$marker_width, dash = "dash"),
      opacity = style$opacity, hoverinfo = "text", connectgaps = FALSE
    )
  })
}

band_palette <- c("#1f78b4", "#e31a1c", "#6a3d9a", "#b15928", "#33a02c", "#ff7f00", "#a6761d",
                  "#666666", "#e6ab02", "#386cb0")

band_colours <- function(molecules) {
  molecules <- unique(molecules)
  stats::setNames(rep(band_palette, length.out = length(molecules)), molecules)
}

check_bands_table <- function(bands) {
  needed <- c("molecule", "system", "name", "v_upper", "v_lower", "wavelength", "origin", "degraded",
              "head", "fcf", "relative_intensity")
  if (!is.data.frame(bands) || !all(needed %in% names(bands))) {
    stop("'bands' must be a table returned by molecular_bands().", call. = FALSE)
  }
  invisible(bands)
}

# One plotly trace per ionization stage: vertical segments separated by NA,
# with the key of the line as custom data.
stage_traces <- function(segments, heads = FALSE, style = plotly_style) {
  if (nrow(segments) == 0) return(list())
  lapply(levels(droplevels(segments$stage_label)), function(stage) {
    s <- segments[segments$stage_label == stage, ]
    colour <- unname(stage_colours[stage])
    trace <- list(
      x = as.vector(rbind(s$x, s$x, NA)),
      y = as.vector(rbind(0, s$height, NA)),
      text = as.vector(rbind(s$text, s$text, NA)),
      customdata = as.vector(rbind(s$key, s$key, NA)),
      type = "scatter", mode = "lines", name = paste("stage", stage),
      line = list(color = colour, width = style$marker_width),
      opacity = style$opacity, hoverinfo = "text", connectgaps = FALSE
    )
    if (heads) {
      trace$mode <- "lines+markers"
      trace$marker <- list(color = colour, size = rep(c(0, 7, 0), nrow(s)))
    }
    trace
  })
}

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.