calc_recalibrate_ms: Recalibrate mass spectra

Description

This function performs an automated mass recalibration for peak lists using predefined or user-specified calibrant lists.

Calibration can be based on existing calibrant tables included in ume::known_mf (via the calibr_list argument) or on a user-provided set of molecular formulas (custom_calibr_list).

The function assigns calibrant peaks to each spectrum and evaluates their mass accuracy. Three independent outlier tests are applied to the assigned calibrants, and only those that pass all tests are used to calculate the recalibration model.

Recalibration is performed using a linear model (m ~ m_cal), and spectra with insufficient calibrant matches can be either excluded or corrected using extrapolated calibration parameters.

Usage

calc_recalibrate_ms(
  pl,
  col_spectrum_id = "file_id",
  calibr_list = c("cal_fa_neg", "cal_marine_dom_neg", "calibration", "marine_dom",
    "cal_marine_dom_pos", "cal_marine_pw_neg", "cal_SRFA_neg", "cal_SRFA_OL_neg",
    "E_coli_metabolome", "Post-column standard"),
  custom_calibr_list = NULL,
  min_no_calibrants = 1,
  outlier_removal = TRUE,
  insufficient_calibrants = c("extrapolate", "remove_spectrum"),
  verbose = FALSE,
  pol = c("neg", "pos", "neutral"),
  ma_dev,
  ...
)

Value

A list containing:

pl: Recalibrated peaklist.
check: Summary of the number of calibrants per spectrum.
cal_peaks: Assigned calibrant peaks and recalibration results.
cal_stats: Calibration statistics (slopes, intercepts, accuracy metrics).
fig_*: Interactive plotly figures comparing mass accuracy before and after recalibration.

Arguments

pl

data.table containing peak data. Mandatory columns include neutral molecular mass (mass), peak magnitude (i_magnitude), and a peak identifier (peak_id).

col_spectrum_id

Character. Name of the column that identifies individual spectra or samples (default: "file_id"). The peaklist must also contain a column named "mass".

calibr_list

Character string. Name of a predefined calibrant list stored in ume::known_mf (column category). Ignored if custom_calibr_list is provided.

custom_calibr_list

Character vector. Custom list of molecular formulas to be used as calibrants instead of a predefined list.

min_no_calibrants

Integer. Minimum number of calibrant peaks required per spectrum to perform recalibration (default: 3). If fewer calibrants are found, recalibration is skipped or handled according to insufficient_calibrants.

outlier_removal

Logical. If TRUE (default), mass-accuracy-based outlier detection is applied to the calibrants within each spectrum before recalibration.

insufficient_calibrants

Character. Defines how spectra with too few calibrants are handled:

"extrapolate": Apply the median calibration slope and intercept from spectra with at least two calibrants (default).

"remove_spectrum"

Remove spectra for which no calibrant peaks were identified.

verbose

logical; if TRUE, show progress messages.

...

Arguments passed on to assign_formulas, calc_neutral_mass, calc_ma_abs

formula_library: Molecular formula library: a predefined data.table used for assigning molecular formulas to a peak list and for mass calibration. The library requires a fixed format, including mass values for matching. Predefined libraries are available in the R package ume.formulas and further described in Leefmann et al. (2019). A standard library for marine dissolved organic matter is ume.formulas::lib_02. New libraries can be built using ume::create_ume_formula_library().

mz

Numeric vector of m/z values (> 0).

pol

Character: "neg", "pos", or "neutral".

m

Measured mass

ma_dev

Mass accuracy in +/- parts per million (ppm)

Author

Boris P. Koch

Details