R/peak_fit.R

Defines functions fit_curve fit_spectra fit_parameters line_estimates fit_one peak_parameters check_fixed guess_peak long_spectra fit_range peak_fit

Documented in peak_fit

#' @title Peak Fitting
#'
#' @author Christian L. Goueguel
#'
#' @description
#' Fitting of a single spectral line by lineshape functions with variable parameters.
#'
#' @details
#' The function uses `minpack.lm::nlsLM`, which is based on the Levenberg-Marquardt
#' algorithm for searching the minimum value of the square of the sum of the residuals.
#' Each spectrum (row of `x`) is fitted separately with the model
#' \deqn{y = y_0 + A \cdot f(x; x_c, w)}
#' where \eqn{f} is a unit-area Gaussian, Lorentzian, Voigt or pseudo-Voigt profile
#' (see [gaussian_profile()], [lorentzian_profile()], [voigt_profile()] and
#' [pseudo_voigt_profile()]). The fitted parameters are `y0`, `xc`, `A` and the
#' width(s) `wG` and/or `wL` (full widths at half maximum). The Voigt profile
#' is evaluated exactly in C++; the pseudo-Voigt (Thompson-Cox-Hastings)
#' approximation is faster but accurate to about 1\%.
#'
#' Initial values that are not supplied are estimated from the data: the peak
#' center from the position of the maximum, the width from the full width at
#' half maximum, and the area from the integrated intensity above the minimum.
#' The center is constrained to the fitted wavelength range and the widths and
#' area to positive values. If the fit of a spectrum fails, a warning is issued
#' and the corresponding `fit`, `tidied` and `augmented` entries are `NULL`.
#'
#' The Gaussian and Lorentzian widths of a Voigt profile are strongly
#' correlated, so a free fit determines the Lorentzian (Stark) width poorly
#' when the line is narrow. In a LIBS plasma, the Gaussian width is the
#' instrumental width, combined with the Doppler width in quadrature,
#' \eqn{w_G = \sqrt{w_{inst}^2 + w_D^2}}, and can be held fixed with
#' `fixed = "wG"` and the value of `wG`. The instrumental width is the width
#' of a line of a low-pressure lamp (mercury, argon), whose Stark and
#' Doppler widths are negligible, fitted with a Gaussian profile at a nearby
#' wavelength; the Doppler width is given by [doppler_width()]. A fixed width
#' is listed in `tidied` without standard error.
#'
#' @param x A data frame or tibble of spectra, one spectrum per row. Column
#'   names are the wavelengths (e.g. `"396.15"`); an optional identifier column
#'   can be given with `id`.
#' @param profile A character specifying the lineshape function to be used:
#' "lorentzian", "gaussian", "voigt" (exact) or "pseudo_voigt".
#' @param wL A numeric specifying the Lorentzian full width at half maximum (initial guess)
#' @param wG A numeric specifying the Gaussian full width at half maximum (initial guess)
#' @param A A numeric specifying the peak area (initial guess)
#' @param wavelength The wavelength range of the fit, `c(min, max)` in nm, or
#'   `NULL` (default) for all the channels.
#' @param id A character specifying the name of the column holding the spectra id (optional)
#' @param max_iter A numeric specifying the maximum number of iteration (200 by default)
#' @param fixed The widths held at their given values (`wG`, `wL`) instead
#'   of being fitted: `"wG"`, `"wL"` or both. Default is `NULL` (all
#'   widths fitted).
#' @param max.iter,wlgth.min,wlgth.max `r lifecycle::badge("deprecated")` Use
#'   `max_iter`, and `wavelength = c(wlgth.min, wlgth.max)`.
#'
#' @return A tibble with one row per spectrum and the columns:
#'  - `id` column (or `spectrum`, the row number, when `id = NULL`),
#'  - `data`: the fitted data (`x`, `y`),
#'  - `fit`: the `nls` model object, of class `specproc_peak_fit` (see
#'    [tidy()][specproc-tidy] and [glance()][specproc-tidy]),
#'  - `tidied`: the estimated parameters with their standard errors,
#'  - `augmented`: the data with fitted values (`.fitted`) and residuals (`.resid`).
#'
#' @export peak_fit
#'
#' @examples
#' data(forageLIBS)
#' mean_spectrum <- colMeans(forageLIBS[-(1:14)])
#' wl <- as.numeric(names(mean_spectrum))
#' # the H-alpha line of the hydrogen of the samples, Stark-broadened
#' halpha <- tibble::as_tibble(as.list(mean_spectrum[wl > 653.5 & wl < 659.5]))
#' res <- peak_fit(halpha, profile = "lorentzian")
#' res$tidied[[1]]
#'
#' # a Voigt line whose Gaussian width (instrument and Doppler) is known
#' x <- seq(395, 397, by = 0.01)
#' set.seed(1)
#' y <- voigt_profile(x, y0 = 10, xc = 396, wG = 0.08, wL = 0.05, A = 50) +
#'   rnorm(length(x), sd = 2)
#' line <- tibble::as_tibble(as.list(stats::setNames(y, x)))
#' peak_fit(line, profile = "voigt", wG = 0.08, fixed = "wG")$tidied[[1]]
peak_fit <- function(
    x,
    profile = "voigt",
    wL = NULL,
    wG = NULL,
    A = NULL,
    wavelength = NULL,
    id = NULL,
    max_iter = 200,
    fixed = NULL,
    max.iter = deprecated(),
    wlgth.min = deprecated(),
    wlgth.max = deprecated()) {
  max_iter <- renamed_arg(max.iter, max_iter, "peak_fit", "max.iter", "max_iter")
  wavelength <- fit_range(wavelength, wlgth.min, wlgth.max, "peak_fit")

  if (missing(x)) {
    stop("Missing 'data' argument.")
  }
  if (!is.data.frame(x)) {
    stop("Input 'data' must be a data frame or tibble.")
  }
  if (!is.character(profile) || length(profile) != 1 ||
      !tolower(profile) %in% lineshapes) {
    stop("The profile function must be: 'lorentzian', 'gaussian', 'voigt' or 'pseudo_voigt'")
  }
  if (!is.numeric(max_iter)) {
    stop("Maximum number of iteration must be numeric")
  }

  spectra <- long_spectra(x, id, wavelength)
  fit_spectra(spectra, peaks = NA_real_, profiles = tolower(profile),
              wL = wL, wG = wG, A = A, max_iter = max_iter, single = TRUE, fixed = fixed)
}


lineshapes <- c("gaussian", "lorentzian", "voigt", "pseudo_voigt")

# The wavelength range of a fit, from `wavelength` or from the former
# arguments `wlgth.min` and `wlgth.max`.
fit_range <- function(wavelength, wlgth.min, wlgth.max, fn, user_env = rlang::caller_env(2)) {
  details <- "Give the range as `wavelength = c(min, max)`."
  lo <- renamed_arg(wlgth.min, NULL, fn, "wlgth.min", "wavelength", details, user_env)
  hi <- renamed_arg(wlgth.max, NULL, fn, "wlgth.max", "wavelength", details, user_env)
  if (is.null(lo) && is.null(hi)) {
    return(wavelength)
  }
  c(if (is.null(lo)) -Inf else lo, if (is.null(hi)) Inf else hi)
}

# Splits a wide data frame of spectra into a list of (x, y) tibbles, one per
# spectrum, restricted to the wavelength range `wavelength`.
long_spectra <- function(x, id, wavelength) {
  if (!is.null(id)) {
    if (!is.character(id) || length(id) != 1 || !id %in% names(x)) {
      stop("'id' must be the name of a column of 'x'.", call. = FALSE)
    }
    ids <- x[[id]]
    x <- x[setdiff(names(x), id)]
    id_name <- id
  } else {
    ids <- seq_len(nrow(x))
    id_name <- "spectrum"
  }
  if (!all(vapply(x, is.numeric, logical(1)))) {
    stop("All spectral columns of 'x' must be numeric.", call. = FALSE)
  }
  wl <- parse_wavelength(names(x))
  if (anyNA(wl)) {
    stop("Column names of 'x' must be wavelengths (numeric values).", call. = FALSE)
  }

  if (is.null(wavelength)) wavelength <- c(-Inf, Inf)
  if (!is.numeric(wavelength) || length(wavelength) != 2 || anyNA(wavelength) ||
      wavelength[1] >= wavelength[2]) {
    stop("'wavelength' must be a range c(min, max), with min < max.", call. = FALSE)
  }
  lo <- wavelength[1]
  hi <- wavelength[2]
  keep <- wl >= lo & wl <= hi
  if (sum(keep) < 5) {
    stop("Fewer than 5 data points in the selected wavelength range.", call. = FALSE)
  }
  ord <- order(wl[keep])
  wl <- wl[keep][ord]
  m <- as.matrix(x[keep])[, ord, drop = FALSE]

  data <- lapply(seq_len(nrow(m)), function(i) {
    ok <- !is.na(m[i, ])
    tibble::tibble(x = wl[ok], y = unname(m[i, ok]))
  })
  list(ids = ids, id_name = id_name, data = data)
}

# Initial guesses for one peak from the data around `xc`.
guess_peak <- function(x, y, xc = NA_real_) {
  y0 <- min(y)
  i <- if (is.na(xc)) which.max(y) else which.min(abs(x - xc))
  xc <- x[i]
  h <- y[i] - y0
  step <- stats::median(diff(x))
  half <- y - y0 >= h / 2
  lo <- i
  while (lo > 1 && half[lo - 1]) lo <- lo - 1
  hi <- i
  while (hi < length(x) && half[hi + 1]) hi <- hi + 1
  fwhm <- max(x[hi] - x[lo], 2 * step)
  list(xc = xc, fwhm = fwhm, A = max(h, .Machine$double.eps) * fwhm * 1.064, step = step)
}

# Checks the widths held fixed (`fixed`) against the profiles and the given
# widths.
check_fixed <- function(fixed, profiles, wL, wG) {
  if (is.null(fixed) || length(fixed) == 0) return(character())
  if (!is.character(fixed) || !all(fixed %in% c("wG", "wL")) || anyDuplicated(fixed)) {
    stop("'fixed' must be \"wG\", \"wL\" or both.", call. = FALSE)
  }
  has_width <- list(wG = c("gaussian", "voigt", "pseudo_voigt"),
                    wL = c("lorentzian", "voigt", "pseudo_voigt"))
  for (w in fixed) {
    if (is.null(if (w == "wG") wG else wL)) {
      stop("A fixed width needs its value: give '", w, "'.", call. = FALSE)
    }
    if (!any(profiles %in% has_width[[w]])) {
      stop("'fixed = \"", w, "\"' needs a profile with a ",
           if (w == "wG") "Gaussian" else "Lorentzian", " width.", call. = FALSE)
    }
  }
  fixed
}

# Builds the parameter specification of the multi-peak model: the fitted
# parameters (start values and bounds), the model terms, and the definition
# of each parameter of each line (y0, xc, wG, wL, A) as an expression of the
# fitted parameters: a parameter of its own, a fixed value (`fixed`), or a
# function of a parameter shared by a group of lines (`centers`: the lines
# keep the separations of `peaks` and move by a common shift; `widths`: the
# lines share their widths; `area_ratios`: the areas are in fixed ratios).
# `centers` and `widths` give a group number per line (NA for a free line).
peak_parameters <- function(data, peaks, profiles, wL, wG, A, single, fixed = character(),
                            centers = NULL, widths = NULL, area_ratios = NULL) {
  k <- length(profiles)
  pick <- function(v, i) if (is.null(v)) NA_real_ else if (length(v) == 1) v else v[i]
  x <- data$x
  y <- data$y
  sfx <- function(nm, i) if (single) nm else paste0(nm, "_", i)
  num <- function(v) sprintf("%.17g", v)
  # the name of a parameter shared by the lines `members`
  shared <- function(base, members) {
    if (length(members) == k) base else paste(c(base, members), collapse = "_")
  }
  guesses <- lapply(seq_len(k), function(i) guess_peak(x, y, if (single) NA_real_ else peaks[i]))

  start <- list(y0 = min(y))
  lower <- c(y0 = -Inf)
  upper <- c(y0 = Inf)
  add <- function(nm, value, lo, hi) {
    if (is.null(start[[nm]])) {
      start[[nm]] <<- value
      lower[nm] <<- lo
      upper[nm] <<- hi
    }
    nm
  }
  center <- function(i) {
    g <- if (is.null(centers)) NA else centers[i]
    if (is.na(g)) {
      return(add(sfx("xc", i), if (single) guesses[[i]]$xc else peaks[i], min(x), max(x)))
    }
    members <- which(centers == g)
    if (min(peaks[members]) < min(x) || max(peaks[members]) > max(x)) {
      stop("The lines locked together must lie within the fitted wavelength range.",
           call. = FALSE)
    }
    shift <- add(shared("shift", members), 0, min(x) - min(peaks[members]),
                 max(x) - max(peaks[members]))
    paste(num(peaks[i]), "+", shift)
  }
  width <- function(type, i, guess) {
    value <- pick(if (type == "wG") wG else wL, i)
    if (type %in% fixed) return(num(value))
    g <- if (is.null(widths)) NA else widths[i]
    members <- if (is.na(g)) i else which(widths == g)
    nm <- if (length(members) > 1) shared(type, members) else sfx(type, i)
    add(nm, ifelse(is.na(value), guess, value), stats::median(diff(x)) / 100, Inf)
  }
  area <- function(i) {
    r <- if (is.null(area_ratios)) NA_real_ else area_ratios[i]
    if (is.na(r)) {
      return(add(sfx("A", i), ifelse(is.na(pick(A, i)), guesses[[i]]$A, pick(A, i)), 0, Inf))
    }
    members <- which(!is.na(area_ratios))
    first <- stats::median(vapply(members, function(j) guesses[[j]]$A / area_ratios[j], numeric(1)))
    paste(num(r), "*", add(shared("A", members), first, 0, Inf))
  }
  wrap <- function(e) if (grepl(" ", e, fixed = TRUE)) paste0("(", e, ")") else e

  definitions <- c(y0 = "y0")
  terms <- character(k)
  for (i in seq_len(k)) {
    xc <- center(i)
    w <- switch(
      profiles[i],
      gaussian = c(wG = width("wG", i, guesses[[i]]$fwhm)),
      lorentzian = c(wL = width("wL", i, guesses[[i]]$fwhm)),
      c(wG = width("wG", i, guesses[[i]]$fwhm / 2), wL = width("wL", i, guesses[[i]]$fwhm / 2))
    )
    a <- area(i)
    definitions[sfx(c("xc", names(w), "A"), i)] <- c(xc, w, a)
    terms[i] <- sprintf("%s * profile_%s(x, %s)", wrap(a), profiles[i],
                        paste(c(xc, w), collapse = ", "))
  }
  list(start = start, lower = lower[names(start)], upper = upper[names(start)], terms = terms,
       definitions = definitions)
}

fit_one <- function(data, peaks, profiles, wL, wG, A, max_iter, single, fixed = character(),
                    centers = NULL, widths = NULL, area_ratios = NULL) {
  spec <- peak_parameters(data, peaks, profiles, wL, wG, A, single, fixed, centers, widths,
                          area_ratios)
  form <- stats::as.formula(
    paste("y ~ y0 +", paste(spec$terms, collapse = " + ")),
    env = environment(profile_gaussian)
  )
  fit <- minpack.lm::nlsLM(
    form,
    data = data,
    start = spec$start,
    lower = spec$lower,
    upper = spec$upper,
    control = minpack.lm::nls.lm.control(maxiter = max_iter)
  )
  class(fit) <- c("specproc_peak_fit", class(fit))
  attr(fit, "peak_terms") <- spec$terms
  attr(fit, "definitions") <- spec$definitions

  fitted <- stats::fitted(fit)
  augmented <- tibble::tibble(
    x = data$x, y = data$y,
    .fitted = as.numeric(fitted),
    .resid = data$y - as.numeric(fitted)
  )
  if (!single) {
    par <- as.list(stats::coef(fit))
    env <- list2env(c(par, list(x = data$x)), parent = environment(profile_gaussian))
    for (i in seq_along(spec$terms)) {
      augmented[[paste0(".peak_", i)]] <- eval(str2lang(spec$terms[i]), env)
    }
  }
  list(fit = fit, tidied = fit_parameters(fit), augmented = augmented)
}

# Values of the parameters of the lines (the definitions of the fit) and
# their covariance matrix, propagated from the fitted parameters (the
# definitions are linear in them). `constant` marks the fixed values.
line_estimates <- function(fit) {
  coefs <- stats::coef(fit)
  cov <- tryCatch(stats::vcov(fit), error = function(e) NULL)
  defs <- attr(fit, "definitions")
  if (is.null(defs)) {   # fits made before the definitions were kept
    return(list(estimate = coefs, vcov = cov, constant = rep(FALSE, length(coefs))))
  }
  exprs <- lapply(defs, str2lang)
  value <- function(b) {
    env <- as.list(b)
    vapply(exprs, function(e) eval(e, env, baseenv()), numeric(1))
  }
  estimate <- value(coefs)
  jacobian <- matrix(vapply(seq_along(coefs), function(j) {
    h <- 1e-6 * max(1, abs(coefs[[j]]))
    up <- dn <- coefs
    up[j] <- up[j] + h
    dn[j] <- dn[j] - h
    (value(up) - value(dn)) / (2 * h)
  }, numeric(length(defs))), nrow = length(defs), dimnames = list(names(defs), names(coefs)))
  list(estimate = estimate,
       vcov = if (is.null(cov)) NULL else jacobian %*% cov %*% t(jacobian),
       constant = rowSums(jacobian != 0) == 0)
}

# The tidied parameters of a fit: those of each line, with their standard
# errors (none for a fixed value), and the common shifts of locked centers.
fit_parameters <- function(fit) {
  le <- line_estimates(fit)
  estimate <- le$estimate
  se <- if (is.null(le$vcov)) rep(NA_real_, length(estimate)) else sqrt(pmax(diag(le$vcov), 0))
  se[le$constant] <- NA_real_
  shifts <- grep("^shift", names(stats::coef(fit)), value = TRUE)
  if (length(shifts) > 0) {
    cov <- tryCatch(stats::vcov(fit), error = function(e) NULL)
    estimate <- c(estimate, stats::coef(fit)[shifts])
    se <- c(se, if (is.null(cov)) rep(NA_real_, length(shifts)) else
      sqrt(pmax(diag(cov)[shifts], 0)))
  }
  statistic <- estimate / se
  tibble::tibble(term = names(estimate), estimate = estimate, std.error = unname(se),
                 statistic = unname(statistic),
                 p.value = unname(2 * stats::pt(-abs(statistic), stats::df.residual(fit))))
}

fit_spectra <- function(spectra, peaks, profiles, wL, wG, A, max_iter, single,
                        fixed = character(), centers = NULL, widths = NULL,
                        area_ratios = NULL) {
  for (v in list(wL, wG, A)) {
    if (!is.null(v) && (!is.numeric(v) || !length(v) %in% c(1, length(profiles)) || any(v <= 0))) {
      stop("'wL', 'wG' and 'A' must be positive numbers, either one value or one per peak.",
           call. = FALSE)
    }
  }
  fixed <- check_fixed(fixed, profiles, wL, wG)
  results <- lapply(seq_along(spectra$data), function(i) {
    tryCatch(
      fit_one(spectra$data[[i]], peaks, profiles, wL, wG, A, max_iter, single, fixed, centers,
              widths, area_ratios),
      error = function(e) {
        warning("Fitting failed for ", spectra$id_name, " '", spectra$ids[i], "': ",
                conditionMessage(e), call. = FALSE)
        list(fit = NULL, tidied = NULL, augmented = NULL)
      }
    )
  })
  out <- tibble::tibble(
    !!spectra$id_name := spectra$ids,
    data = spectra$data,
    fit = lapply(results, `[[`, "fit"),
    tidied = lapply(results, `[[`, "tidied"),
    augmented = lapply(results, `[[`, "augmented")
  )
  out
}

# Evaluates a fitted line model, and each line of a multi-peak model, on a
# grid of wavelengths (used to draw smooth curves in plot_fit()).
fit_curve <- function(fit, x) {
  par <- as.list(stats::coef(fit))
  env <- list2env(c(par, list(x = x)), parent = environment(profile_gaussian))
  terms <- attr(fit, "peak_terms")
  out <- tibble::tibble(x = x, .fitted = as.numeric(stats::predict(fit, newdata = data.frame(x = x))))
  if (length(terms) > 1) {
    for (i in seq_along(terms)) {
      out[[paste0(".peak_", i)]] <- par$y0 + eval(str2lang(terms[i]), env)
    }
  }
  out
}

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.