create_ume_formula_library: Create a molecular formula library for UME

Description

Generates all combinations of element / isotope counts between min_formula and max_formula, filtered by mass, DBE, element ratios, and heuristic rules (Kind & Fiehn 2007).

Usage

create_ume_formula_library(
  max_formula,
  min_formula = "C1H1",
  lib_version = 99,
  masses = ume::masses,
  max_mass = 152,
  ratio_filter = TRUE,
  heu_filter = TRUE,
  max_oc = 1.2,
  max_hc = 3.1,
  max_nc = 1.3,
  max_pc = 0.3,
  max_sc = 0.8,
  verbose = FALSE
)

Value

A data.table containing the generated molecular formula library. The returned object has class "ume_library" and includes one row per molecular formula, with columns for:

elemental and isotopic counts (e.g., 12C, 13C, 1H, 16O, ...)
double bond equivalent (dbe)
exact mass (mass)
molecular formula string (mf)
a unique versioned key (vkey)

Additional metadata is stored as attributes:

"lib_version": numeric version identifier
"min_formula": user-supplied minimum formula
"max_formula": user-supplied maximum formula
"max_mass": maximum allowed exact mass
"filters": list describing applied ratio and heuristic filters
"call": the matched function call

The object inherits from both "ume_library" and "data.table".

Arguments

max_formula: Character. Maximum element/isotope counts, e.g. "C20H40O10" or "C1000\[13C1\]H2000".
min_formula: Character. Minimum element/isotope counts (default "C1H1").
lib_version: Integer. Library version identifier (default 99).
masses: A data.table. Defaults to ume::masses (based on NIST data) containing isotope information for elements, including nominal and exact mass, relative abundance, and Hill system order.
max_mass: Numeric. Maximum allowed exact mass.
ratio_filter: Logical. Apply O/C, H/C, N/C, P/C, S/C filters.
heu_filter: Logical. Apply Kind - Fiehn heuristic rules.
max_oc: Maximum oxygen / carbon ratio in a molecule; (UM_orig: 1.5; 7 rules: 1.2)
max_hc: Maximum hydrogen / carbon ratio in a molecule; (UM_orig: ; 7 rules: 1.2)
max_nc: Maximum nitrogen / carbon ratio in a molecule; (UM_orig: 0.5; 7 rules: 1.3)
max_pc: Maximum phosphorus / carbon ratio in a molecule; (UM_orig: 3; 7 rules: 0.3)
max_sc: Maximum sulfur / carbon ratio in a molecule; (UM_orig: 4; 7 rules: 0.8)
verbose: Logical. Print progress messages.

References

Kind T., Fiehn O. (2007). Seven Golden Rules for heuristic filtering of molecular formulas obtained by accurate mass spectrometry. BMC Bioinformatics, 8, 105. tools:::Rd_expr_doi("10.1186/1471-2105-8-105")