create_ume_formula_library: Create a molecular formula library for UME

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

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
)

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.

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".

References

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

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