calc_recalibrate_ms: Recalibrate mass spectra

In ume: Ultrahigh-Resolution Mass Spectrometry Data Evaluation for Complex Organic Matter

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,
  ...
)

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)

Details

Recalibration is based on a linear fit (lm(m ~ m_cal)), with slopes and intercepts computed individually for each spectrum. Optionally, spectra without sufficient calibrants can be corrected using median calibration parameters derived from other spectra.

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.

Author(s)

Boris P. Koch

See Also

Other calculations: calc_data_summary(), calc_dbe(), calc_eval_params(), calc_exact_mass(), calc_ideg(), calc_ma(), calc_neutral_mass(), calc_nm(), calc_norm_int(), calc_number_assignment(), calc_number_occurrence()

ume documentation built on Dec. 13, 2025, 1:06 a.m.