Empirical Compound Pre Annotation

empirical-compound-pre-annotation

Summary

Group co-eluting LC-MS features into empirical compounds by detecting isotopologues and adducts using mass tolerance and retention time clustering. This pre-annotation step transforms raw feature tables into higher-level metabolite representations suitable for MS1/MS2 annotation.

When to use

After feature detection from mzML files (e.g., via Asari) when you have a feature table with m/z, retention time, and intensity columns, and before MS1 or MS2 annotation. Use this when working with Orbitrap LC-MS data in positive or negative ionization mode and you need to collapse multiple isotopologues and adducts into single putative metabolite entities for downstream annotation and statistical analysis.

When NOT to use

• Input is already aggregated at the empirical compound or metabolite level (e.g., already annotated with HMDB IDs or chemical structures).
• Data are from GC-MS, GC-EI, or other non-LC-MS ionization modes not covered by default khipu adduct libraries.
• Retention time information is missing or unreliable (clustering will degrade without RT co-elution confirmation).

Inputs

• Feature table (TSV or CSV) with m/z, retention time, and intensity columns
• Ionization mode (positive or negative, inferred or specified)
• mzML or raw LC-MS metadata (optional, for parameter inference)

Outputs

• EmpCpd JSON file (empirical compounds with grouped features and pre-annotation labels)
• Grouped feature-to-compound mapping (internal to EmpCpd structure)

How to apply

Initialize khipu with default parameters tuned for Orbitrap LC-MS: m/z tolerance of 5 ppm, retention time tolerance of 2 seconds, charge states up to z=3, and isotope patterns including m+13C up to 3 carbons. Load the feature table and infer ionization mode (positive or negative) from the data or metadata. Apply feature grouping by matching m/z and retention time within these tolerances to identify co-eluting isotopologues and common adducts. Assign each grouped cluster a single empirical compound identifier with a pre-annotation label encoding the inferred adduct and isotope state. Serialize the grouped EmpCpd structure to JSON format and save to the experiment's annotations subdirectory for use in downstream annotation workflows.

Related tools

• khipu (Core grouping engine: clusters features into isotopologues and adducts using m/z and RT tolerance; assigns pre-annotation labels to empirical compounds) — https://github.com/shuzhao-li-lab/khipu
• Asari (Upstream feature detection tool that produces the feature table input to khipu pre-annotation) — https://github.com/shuzhao-li/asari
• mass2chem (Utility library for interpreting mass spectrometry data and adduct annotation rules) — https://github.com/shuzhao-li-lab/mass2chem
• metDataModel (Data model framework for representing empirical compounds and feature groupings in standard JSON format) — https://github.com/shuzhao-li-lab/metDataModel
• Python (Programming language for scripting khipu workflow and I/O operations)

Evaluation signals

• EmpCpd JSON file is created and contains valid JSON structure with grouped features and pre-annotation labels.
• Each empirical compound contains ≥1 feature; features within a compound have m/z differences ≤5 ppm and RT differences ≤2 seconds.
• Adduct and isotope state labels are correctly inferred (e.g., '[M+H]+', '[M+Na]+', 'M+13C1', etc.) and match expected ionization mode.
• Feature count in EmpCpd file is ≤ feature count in input table (clustering should not duplicate or lose features).
• JSON schema validation passes against metDataModel EmpCpd specification; no malformed or orphaned feature entries.

Limitations

• Default parameters (5 ppm m/z, 2 sec RT) are optimized for Orbitrap instruments and may not be appropriate for lower-resolution instruments (e.g., Quadrupole, Ion trap) or very high-resolution systems (e.g., FTICR) without tuning.
• GC-MS and other non-LC ionization modes are not yet supported; support under development.
• Internal spike-in standards for quality control flagging are not yet implemented.
• Clustering performance depends heavily on retention time accuracy; poor or missing RT data will cause false positive groupings across co-eluting metabolites with similar m/z.
• Pre-annotation labels do not constitute biological or chemical validation; they are inferred mass signatures requiring downstream MS1 or MS2 annotation for confirmation.

Evidence

• [other] Khipu constructs empirical compounds by grouping features as isotopes and adducts with default parameters: charges up to z=3, m+13C3 isotopologues, common adducts by chromatography mode, 5 ppm mz tolerance, and 2 sec rt tolerance for Orbitrap LC data.: "Khipu constructs empirical compounds by grouping features as isotopes and adducts with default parameters: charges up to z=3, m+13C3 isotopologues, common adducts by chromatography mode, 5 ppm mz"
• [other] Group features by applying m/z tolerance (5 ppm) and retention time tolerance (2 seconds) to identify co-eluting isotopologues and adducts.: "Group features by applying m/z tolerance (5 ppm) and retention time tolerance (2 seconds) to identify co-eluting isotopologues and adducts."
• [other] Assign each group to an empirical compound with a pre-annotation label indicating the inferred adduct and isotope state.: "Assign each group to an empirical compound with a pre-annotation label indicating the inferred adduct and isotope state."
• [intro] pre-annotation to group featues to empirical compounds (khipu): "pre-annotation to group featues to empirical compounds (khipu)"
• [readme] This includes feature tables that are optionally blank masked, normalized, batch corrected, annotated or otherwise curated by PCPFM and empirical compounds as a JSON file representing putative metabolites: "empirical compounds as a JSON file representing putative metabolites"
• [intro] We are working to add supports of GC and other data types.: "We are working to add supports of GC and other data types."