R/line_intensities.R

Defines functions required_pkgs.step_line_intensities tunable.step_line_intensities tidy.step_line_intensities print.step_line_intensities bake.step_line_intensities prep.step_line_intensities line_column_names voigt_areas noise_gain measure_line spectrum_noise line_table line_spectra step_line_intensities line_intensities

Documented in line_intensities step_line_intensities

#' @title Intensities of Emission Lines
#'
#' @author Christian L. Goueguel
#'
#' @description
#' Measures the intensity of emission lines in spectra: for each line, the
#' peak is searched near its tabulated wavelength, and its area or height is
#' measured. The result feeds [boltzmann()], [saha_boltzmann()],
#' [cf_libs()] and [calibration_curve()].
#'
#' @details
#' For each spectrum and line, the peak is the channel of highest intensity
#' within `search` nm of the tabulated wavelength, which absorbs small
#' errors of the wavelength calibration. The intensity is then measured on
#' the channels within `half_width` nm of the peak:
#'  - `method = "area"` (default): the integrated intensity (trapezoidal
#'    rule), in intensity units times nm;
#'  - `method = "height"`: the peak intensity;
#'  - `method = "voigt"`: the area of a Voigt profile fitted with
#'    [peak_fit()] to the channels within `fit_width` nm of the peak. It
#'    separates the line from a flat background and is less sensitive to the
#'    window, but it is slower and needs a line well sampled by the
#'    detector.
#'
#' With `baseline = TRUE`, a straight line through the intensities at both
#' ends of the window is subtracted before the area or height is measured
#' (the Voigt fit always includes a constant background).
#'
#' Each line is also checked:
#'  - `snr`: the height above the baseline divided by the noise of the
#'    spectrum, estimated robustly from its channel-to-channel differences;
#'    `detected` is `snr >= min_snr`.
#'  - `saturated`: with `limit`, whether a channel of the window reaches
#'    the saturation limit of the detector (see [saturation_summary()]).
#'
#' `intensity_se` is the standard error of the intensity due to the noise
#' of the spectrum: the noise (as for `snr`) propagated through the
#' integration and the baseline subtraction, or, for the Voigt method, the
#' standard error of the fitted area. The noise is taken as white and the
#' same in every channel, so this is a lower bound: it leaves out the
#' shot-to-shot fluctuations of the plasma, which usually dominate in LIBS.
#' These are better estimated from replicate spectra, as the standard
#' deviation of the intensities of the replicates divided by the square
#' root of their number. [plasma_uncertainty()] propagates `intensity_se`
#' to the temperature and the composition.
#'
#' @param spectra The spectra: a numeric vector named by wavelength (one
#'   spectrum), or a matrix or data frame with one spectrum per row and the
#'   wavelengths as column names. Other columns of a data frame (such as
#'   sample names) are kept in the result.
#' @param lines The lines: a numeric vector of wavelengths (nm), whose names
#'   are used as labels, or a data frame with a `wavelength` column, such as
#'   returned by [nist_lines()], whose columns are kept in the result.
#' @param half_width The half-width of the integration window around the
#'   peak, in nm. Default is 0.15.
#' @param search The half-width of the window in which the peak is
#'   searched around the tabulated wavelength, in nm. Default is 0.2.
#' @param method `"area"` (default), `"height"` or `"voigt"`.
#' @param baseline A logical: subtract a linear baseline under each line
#'   (`FALSE`, default).
#' @param fit_width The half-width of the window of the Voigt fit, in nm.
#'   Default is 3 times `half_width`.
#' @param limit The saturation limit of the detector, in counts, or `NULL`
#'   (default) not to check saturation.
#' @param min_snr The signal-to-noise ratio above which a line is detected.
#'   Default is 3.
#'
#' @return A tibble with one row per spectrum and line: the other columns
#'   of `spectra` (or `spectrum`, the row number), the columns of `lines`
#'   (or `line` and `wavelength`), and `peak_wavelength`, `shift` (nm),
#'   `height`, `intensity`, `intensity_se`, `snr`, `detected` and
#'   `saturated` (which replace the columns of `lines` of the same name,
#'   such as the relative intensity listed by [nist_lines()]). For a single
#'   spectrum, it has one row per line, like `lines`, with the measured
#'   `intensity`.
#'
#' @seealso [step_line_intensities()], [nist_lines()], [cf_libs()],
#'   [calibration_curve()], [peak_fit()]
#' @export line_intensities
#'
#' @examples
#' data(forageLIBS)
#' spectra <- forageLIBS[1:8, -(1:14)]
#' k <- c(`K I 404.41` = 404.414, `K I 404.72` = 404.721, `Mg I 518.36` = 518.360)
#' line_intensities(spectra, k, baseline = TRUE)
#'
#' # one spectrum and a table of lines, ready for a Boltzmann plot
#' lines <- data.frame(wavelength = c(428.30, 430.25, 443.50, 445.48),
#'                     Aki = c(4.34e7, 1.36e8, 6.70e7, 8.70e7), gk = c(5, 5, 5, 7),
#'                     Ek = c(4.78, 4.78, 4.68, 4.68))
#' mean_spectrum <- colMeans(forageLIBS[-(1:14)])
#' line_intensities(mean_spectrum, lines, baseline = TRUE)
line_intensities <- function(spectra, lines, half_width = 0.15, search = 0.2, method = "area",
                             baseline = FALSE, fit_width = 3 * half_width, limit = NULL,
                             min_snr = 3) {
  method <- match.arg(method, c("area", "height", "voigt"))
  check_number(half_width, "half_width", lower = 0, lower_open = TRUE)
  check_number(search, "search", lower = 0)
  check_number(fit_width, "fit_width", lower = 0, lower_open = TRUE)
  check_flag(baseline, "baseline")
  check_number(min_snr, "min_snr", lower = 0)
  if (!is.null(limit)) check_number(limit, "limit")
  sp <- line_spectra(spectra)
  lines <- line_table(lines)

  x <- sp$x
  wl <- sp$wavelength
  noise <- apply(x, 1, spectrum_noise)
  results <- lapply(seq_len(nrow(lines)), function(j) {
    m <- measure_line(x, wl, lines$wavelength[j], half_width, search, method, baseline,
                      fit_width, limit, noise)
    m$snr <- m$height / noise
    m$line_row <- j
    m$spectrum_row <- seq_len(nrow(x))
    m
  })
  res <- do.call(rbind, results)
  res$detected <- !is.na(res$snr) & res$snr >= min_snr
  measured <- c("peak_wavelength", "shift", "height", "intensity", "intensity_se", "snr",
                "detected", "saturated")
  # measured columns replace those of the same name (such as the relative
  # intensity of nist_lines())
  lines <- lines[setdiff(names(lines), measured)]
  ids <- sp$ids[setdiff(names(sp$ids), c(measured, names(lines)))]
  out <- tibble::as_tibble(cbind(
    ids[res$spectrum_row, , drop = FALSE],
    lines[res$line_row, , drop = FALSE],
    res[measured]
  ))
  out <- out[order(res$spectrum_row, res$line_row), , drop = FALSE]
  if (sp$single) out$spectrum <- NULL
  out
}

#' @title Emission Line Intensities Recipe Step
#'
#' @description
#' `step_line_intensities()` creates a *specification* of a recipe step
#' that replaces the spectral columns by the intensities of selected
#' emission lines, measured with [line_intensities()].
#'
#' @details
#' The selected columns form one spectrum per row, and their names must be
#' their wavelengths (in nm). Each line becomes a new column, named by
#' `prefix` and the name of the line (or its wavelength). Nothing is
#' estimated from the training data. The Voigt method of
#' [line_intensities()] is not offered, as it is too slow for resampling.
#' [tidy()][recipes::tidy.recipe] returns the `line` names, their
#' `wavelength`, the `method` and `id`.
#'
#' @inheritParams step_baseline
#' @inheritParams line_intensities
#' @param lines The lines: a numeric vector of wavelengths (nm), preferably
#'   named, such as `c(Ca = 393.37, Mg = 279.55)`.
#' @param method `"area"` (default) or `"height"`.
#' @param prefix The prefix of the new column names. Default is `"line_"`.
#' @param keep_original_cols A logical: keep the spectral columns (`FALSE`,
#'   default).
#'
#' @inherit step_baseline return
#' @seealso [line_intensities()], [step_line_ratio()]
#' @export
#'
#' @examples
#' if (rlang::is_installed("recipes")) {
#'   data(forageLIBS)
#'   rec <- recipes::recipe(K ~ ., data = forageLIBS[-c(1:10, 12:14)]) |>
#'     step_line_intensities(recipes::all_predictors(),
#'                           lines = c(K = 769.90, Mg = 285.21, Ca = 317.93)) |>
#'     recipes::prep()
#'   head(recipes::bake(rec, new_data = NULL))
#' }
step_line_intensities <- function(recipe, ..., lines, half_width = 0.15, search = 0.2,
                                  method = "area", baseline = FALSE, prefix = "line_",
                                  keep_original_cols = FALSE, role = "predictor",
                                  trained = FALSE, columns = NULL, skip = FALSE,
                                  id = recipes::rand_id("line_intensities")) {
  rlang::check_installed("recipes")
  if (missing(lines) || !is.numeric(lines) || length(lines) == 0 || anyNA(lines)) {
    stop("'lines' must be a numeric vector of wavelengths (nm).", call. = FALSE)
  }
  method <- match.arg(method, c("area", "height"))
  check_number(half_width, "half_width", lower = 0, lower_open = TRUE)
  check_number(search, "search", lower = 0)
  check_flag(baseline, "baseline")
  check_flag(keep_original_cols, "keep_original_cols")
  recipes::add_step(recipe, specproc_step_new(
    "line_intensities", terms = rlang::enquos(...), role = role, trained = trained,
    lines = lines, half_width = half_width, search = search, method = method,
    baseline = baseline, prefix = prefix, keep_original_cols = keep_original_cols,
    columns = columns, skip = skip, id = id
  ))
}

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

# Spectra as a matrix, their wavelengths and the id columns.
line_spectra <- function(spectra) {
  if (is.numeric(spectra) && is.null(dim(spectra))) {
    wl <- parse_wavelength(names(spectra) %||% character(length(spectra)))
    if (length(spectra) < 2 || anyNA(wl)) {
      stop("A single spectrum must be a numeric vector named by its wavelengths.", call. = FALSE)
    }
    x <- matrix(as.numeric(spectra), nrow = 1)
    return(list(x = x, wavelength = wl, ids = data.frame(spectrum = 1L), single = TRUE))
  }
  if (is.matrix(spectra)) spectra <- as.data.frame(spectra, check.names = FALSE)
  if (!is.data.frame(spectra) || nrow(spectra) == 0) {
    stop("'spectra' must be a named numeric vector, a matrix or a data frame.", call. = FALSE)
  }
  wl <- suppressWarnings(as.numeric(names(spectra)))
  channels <- !is.na(wl) & vapply(spectra, is.numeric, logical(1))
  if (sum(channels) < 2) {
    stop("'spectra' must have columns named by their wavelengths.", call. = FALSE)
  }
  x <- as.matrix(spectra[channels])
  storage.mode(x) <- "double"
  ids <- if (any(!channels)) as.data.frame(spectra[!channels]) else data.frame(spectrum = seq_len(nrow(x)))
  list(x = x, wavelength = wl[channels], ids = ids, single = FALSE)
}

# Lines as a data frame with a wavelength column.
line_table <- function(lines) {
  if (is.numeric(lines) && is.null(dim(lines))) {
    if (length(lines) == 0 || anyNA(lines)) {
      stop("'lines' must contain wavelengths (nm).", call. = FALSE)
    }
    labels <- names(lines) %||% format(lines)
    labels[is.na(labels) | labels == ""] <- format(lines)[is.na(labels) | labels == ""]
    return(data.frame(line = labels, wavelength = unname(lines), stringsAsFactors = FALSE))
  }
  if (!is.data.frame(lines) || !"wavelength" %in% names(lines) || nrow(lines) == 0) {
    stop("'lines' must be a numeric vector or a data frame with a `wavelength` column.",
         call. = FALSE)
  }
  if (!is.numeric(lines$wavelength) || anyNA(lines$wavelength)) {
    stop("The `wavelength` column of 'lines' must be numeric, without missing values.",
         call. = FALSE)
  }
  as.data.frame(lines)
}

# Noise of a spectrum, from its channel-to-channel differences.
spectrum_noise <- function(v) {
  d <- diff(v[!is.na(v)])
  s <- stats::mad(d) / sqrt(2)
  if (!is.finite(s) || s <= 0) s <- stats::sd(d) / sqrt(2)
  if (!is.finite(s) || s <= 0) NA_real_ else s
}

# Measures one line in every spectrum (rows of x). The spectra are grouped by
# the channel of their peak, which sets their integration window, and each
# group is measured with matrix operations. With the noise of each spectrum,
# the standard error of the intensity is the noise propagated through the
# linear combination of channels that gives the area or the height.
measure_line <- function(x, wl, center, half_width, search, method, baseline, fit_width, limit,
                         noise = NULL) {
  n <- nrow(x)
  out <- data.frame(peak_wavelength = rep(NA_real_, n), shift = NA_real_, height = NA_real_,
                    intensity = NA_real_, intensity_se = NA_real_, saturated = NA)
  if (min(abs(wl - center)) > search + half_width) {
    return(out)   # outside the spectral range
  }
  near <- which(abs(wl - center) <= max(search, min(abs(wl - center))))
  seg <- x[, near, drop = FALSE]
  seg[is.na(seg)] <- -Inf
  peak <- near[max.col(seg, ties.method = "first")]
  peak[rowSums(is.finite(seg)) == 0] <- NA_integer_   # no value in the search window
  for (pk in unique(stats::na.omit(peak))) {
    rows <- which(peak == pk)
    idx <- which(abs(wl - wl[pk]) <= half_width)
    idx <- idx[order(wl[idx])]
    w <- wl[idx]
    v <- x[rows, idx, drop = FALSE]
    m <- length(idx)
    if (baseline && m > 1) {
      v <- v - (v[, 1] + outer(v[, m] - v[, 1], (w - w[1]) / (w[m] - w[1])))
    }
    height <- suppressWarnings(apply(v, 1, max, na.rm = TRUE))
    height[!is.finite(height)] <- NA_real_
    out$peak_wavelength[rows] <- wl[pk]
    out$height[rows] <- height
    out$saturated[rows] <- if (is.null(limit)) NA else
      rowSums(x[rows, idx, drop = FALSE] >= limit, na.rm = TRUE) > 0
    out$intensity[rows] <- switch(
      method,
      height = height,
      area = if (m > 1) as.vector((v[, -1, drop = FALSE] + v[, -m, drop = FALSE]) %*% diff(w)) / 2 else height,
      voigt = NA_real_
    )
    if (!is.null(noise) && method != "voigt") {
      top <- if (method == "height" || m == 1) {
        apply(v, 1, function(r) if (all(is.na(r))) NA_integer_ else which.max(r))
      }
      out$intensity_se[rows] <- noise[rows] * noise_gain(w, method, baseline, top)
    }
  }
  out$shift <- out$peak_wavelength - center
  if (method == "voigt") {
    areas <- voigt_areas(x, wl, out$peak_wavelength, fit_width)
    out$intensity <- areas[1, ]
    out$intensity_se <- areas[2, ]
  }
  out
}

# Norm of the weights of the channels of a window (wavelengths w) in the
# area (trapezoidal rule) or in the height at channel `top`, after the
# subtraction of the linear baseline through the end channels: the standard
# error of the intensity per unit of white noise.
noise_gain <- function(w, method, baseline, top = NULL) {
  m <- length(w)
  f <- if (m > 1) (w - w[1]) / (w[m] - w[1]) else 0
  weights <- function(k) {
    cf <- numeric(m)
    cf[k] <- 1
    if (baseline && m > 1) {
      cf[1] <- cf[1] - (1 - f[k])
      cf[m] <- cf[m] - f[k]
    }
    sqrt(sum(cf^2))
  }
  if (method == "area" && m > 1) {
    d <- diff(w)
    cf <- c(d, 0) / 2 + c(0, d) / 2
    if (baseline) {
      cf[1] <- cf[1] - sum(cf * (1 - f))
      cf[m] <- cf[m] - sum(cf * f)
    }
    return(rep(sqrt(sum(cf^2)), max(length(top), 1)))
  }
  vapply(top, function(k) if (is.na(k)) NA_real_ else weights(k), numeric(1))
}

# Areas of Voigt profiles fitted around the peak of each spectrum, and their
# standard errors (a 2-row matrix).
voigt_areas <- function(x, wl, peaks, fit_width) {
  too_few <- vapply(peaks, function(p) !is.na(p) && sum(abs(wl - p) <= fit_width) < 6, logical(1))
  if (any(too_few)) {
    warning("Fewer than 6 channels to fit the line at ", round(peaks[too_few][1], 3),
            " nm: widen `fit_width`.", call. = FALSE)
  }
  vapply(seq_len(nrow(x)), function(i) {
    if (is.na(peaks[i]) || too_few[i]) return(c(NA_real_, NA_real_))
    keep <- abs(wl - peaks[i]) <= fit_width
    window <- tibble::as_tibble(as.list(stats::setNames(x[i, keep], wl[keep])))
    fit <- suppressWarnings(peak_fit(window, profile = "voigt"))
    tidied <- fit$tidied[[1]]
    if (is.null(tidied)) return(c(NA_real_, NA_real_))
    unlist(tidied[tidied$term == "A", c("estimate", "std.error")], use.names = FALSE)
  }, numeric(2))
}

line_column_names <- function(lines, prefix) {
  labels <- names(lines) %||% rep("", length(lines))
  labels[is.na(labels) | labels == ""] <- format(lines)[is.na(labels) | labels == ""]
  make.unique(paste0(prefix, trimws(labels)), sep = "_")
}

#' @exportS3Method recipes::prep
prep.step_line_intensities <- function(x, training, info = NULL, ...) {
  cols <- step_predictors(x, training, info)
  wl <- parse_wavelength(cols)
  if (length(cols) > 0 && anyNA(wl)) {
    stop("`step_line_intensities()` needs spectral columns named by their wavelengths, e.g. `",
         cols[is.na(wl)][1], "` is not.", call. = FALSE)
  }
  x$columns <- cols
  x$trained <- TRUE
  x
}

#' @exportS3Method recipes::bake
bake.step_line_intensities <- function(object, new_data, ...) {
  cols <- object$columns
  recipes::check_new_data(cols, object, new_data)
  if (length(cols) == 0) {
    return(new_data)
  }
  xmat <- step_matrix(new_data, cols)
  wl <- parse_wavelength(cols)
  values <- vapply(object$lines, function(center) {
    measure_line(xmat, wl, center, object$half_width, object$search, object$method,
                 object$baseline, NA_real_, NULL)$intensity
  }, numeric(nrow(xmat)))
  values <- matrix(values, nrow = nrow(xmat))
  colnames(values) <- line_column_names(object$lines, object$prefix)
  values <- tibble::as_tibble(values)
  values <- recipes::check_name(values, new_data, object, newname = names(values))
  new_data <- dplyr::bind_cols(new_data, values)
  if (!object$keep_original_cols) {
    new_data <- new_data[setdiff(names(new_data), cols)]
  }
  new_data
}

#' @export
print.step_line_intensities <- function(x, width = max(20, options()$width - 30), ...) {
  title <- paste0("Intensities of ", length(x$lines), " emission lines from ")
  recipes::print_step(x$columns, x$terms, x$trained, title, width)
  invisible(x)
}

#' @exportS3Method generics::tidy
tidy.step_line_intensities <- function(x, ...) {
  tibble::tibble(line = line_column_names(x$lines, x$prefix), wavelength = unname(x$lines),
                 method = x$method, id = x$id)
}

#' @exportS3Method generics::tunable
tunable.step_line_intensities <- function(x, ...) {
  tibble::tibble(name = character(0), call_info = list(), source = character(0),
                 component = character(0), component_id = character(0))
}

#' @exportS3Method generics::required_pkgs
required_pkgs.step_line_intensities <- function(x, ...) {
  c("specProc")
}

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.