# Empirical Compound Pre Annotation

> Use when 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.

- Skill: `holobiomicslab/empirical-compound-pre-annotation` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/empirical-compound-pre-annotation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/empirical-compound-pre-annotation/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/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."