Molecular Formula Inference From Adducts

---
name: molecular-formula-inference-from-adducts
description: Use when when you have grouped features consolidated into empirical compounds
  (EmpCpds) with inferred adduct assignments from khipu, and need to perform MS1-level
  annotation by matching neutral formulas against JMS-compliant reference libraries
  (HMDB, LMSD).
license: CC-BY-4.0
metadata:
  edam_operation: http://edamontology.org/operation_3629
  edam_topics:
  - http://edamontology.org/topic_3172
  - http://edamontology.org/topic_0593
  tools:
  - HMDB
  - LIPID MAP
  - khipu
  - Python
  - LIPID MAP (LMSD)
  - JMS (Json's Metabolite Services)
  techniques:
  - LC-MS
  license_tier: open
  provenance_tier: literature
derived_from:
- doi: 10.1371/journal.pcbi.1011912
  title: pcpfm
evidence_spans:
- we recommend that you download the JMS-compliant versions of the HMDB and LMSD using
  the `download extras` command
- perform MS1 annotation using an authentic compound library, a public database (e.g.
  HMDB, LIPID MAP), or custom database
- pre-annotation to group featues to empirical compounds (khipu)
- Python-Centric Pipeline for Metabolomics
claims: []
provenance:
  collection: https://w3id.org/holobiomicslab/asb-skill/collection/metabolomics/v2
  assembled_by: scripts/collect_metabolomics_collection.py
  sources:
  - build: coll_pcpfm_cq
    doi: 10.1371/journal.pcbi.1011912
    title: pcpfm
  dedup_kept_from: coll_pcpfm_cq
schema_version: 0.2.0
attribution:
  generator: AgenticScienceBuilder
  original_doi: 10.1371/journal.pcbi.1011912
  all_source_dois:
  - 10.1371/journal.pcbi.1011912
  zenodo_doi: 10.5281/zenodo.20794027
  curators: []
  promoter: Louis-Félix Nothias
  sponsor: CNRS & Université Côte d'Azur
---

# molecular-formula-inference-from-adducts

## Summary

Infer neutral molecular formulas from empirical compound (EmpCpd) parameters—including observed m/z, charge state, and ionization mode—to enable Level 4 MS1 annotation against reference databases. This skill is essential for bridging feature-level mass spectrometry data to chemical structure identity without requiring explicit mass tolerance specification.

## When to use

When you have grouped features consolidated into empirical compounds (EmpCpds) with inferred adduct assignments from khipu, and need to perform MS1-level annotation by matching neutral formulas against JMS-compliant reference libraries (HMDB, LMSD). Apply this skill before querying external databases, as the inferred formula becomes the search key.

## When NOT to use

- Input EmpCpds are singletons or have unresolved/ambiguous adduct assignments (formula cannot be reliably inferred).
- Raw feature table has not yet been grouped into empirical compounds via khipu.
- You are performing MS2 annotation (use matchms and spectral databases instead of formula-based queries).
- Reference databases have not been downloaded and indexed (run 'pcpfm download_extras' first).

## Inputs

- empirical compound (EmpCpd) object with grouped features
- EmpCpd adduct assignments from khipu pre-annotation
- observed m/z values and charge states
- ionization mode and adduct type parameters

## Outputs

- inferred neutral molecular formulas (one per non-singleton EmpCpd)
- Level 4 candidate annotations (database entries matching inferred formulas)
- annotated EmpCpd object stored under user-specified moniker

## How to apply

Starting from a pre-built EmpCpd object (containing grouped features with molecular formulas and adduct assignments generated by khipu), extract the inferred neutral formula for each EmpCpd by reversing the ionization and adduction process applied during grouping. The formula inference uses EmpCpd construction parameters (e.g., m/z, charge, adduct type) without requiring explicit mass-to-charge tolerance specification—the formula itself defines the database search space. Only EmpCpds with resolvable adducts (non-singleton compounds) can be annotated at Level 4; singleton empirical compounds are excluded because their adducts cannot be reliably inferred. Once formulas are derived, query the appropriate JMS-compliant database (HMDB or LMSD, downloaded via 'pcpfm download_extras') and retrieve all entries matching each inferred formula, assigning them as Level 4 candidate annotations.

## Related tools

- **khipu** (pre-annotation tool that groups features into empirical compounds and assigns adducts; outputs inferred formulas and adduct information used as input for formula inference and Level 4 annotation) — https://github.com/shuzhao-li-lab/khipu
- **HMDB** (JMS-compliant reference database queried using inferred formulas to retrieve Level 4 candidate annotations for metabolite identification)
- **LIPID MAP (LMSD)** (JMS-compliant lipid structure reference database queried alongside HMDB using inferred formulas for comprehensive Level 4 annotation coverage)
- **Python** (implementation language for formula inference logic and database query integration within PCPFM pipeline) — https://github.com/shuzhao-li-lab/PythonCentricPipelineForMetabolomics
- **JMS (Json's Metabolite Services)** (standardized interface and data model enabling lookup and retrieval from JMS-compliant HMDB and LMSD databases using inferred formulas) — https://github.com/shuzhao-li-lab/JMS

## Evaluation signals

- All non-singleton EmpCpds have an inferred neutral molecular formula with no missing or NaN values.
- Inferred formulas are chemically valid (correct element composition, plausible molecular weight, match EmpCpd m/z and charge state when re-ionized).
- Database queries return at least one matching entry for each inferred formula (or explicitly report zero matches for formulae absent in HMDB/LMSD).
- Level 4 annotations are stored in the output EmpCpd object with associated database entry IDs and metadata (e.g., compound name, common name, chemical class).
- Singleton EmpCpds are consistently excluded from Level 4 annotation with clear documentation of exclusion reason.

## Limitations

- Singleton empirical compounds cannot be annotated at Level 4 because their adducts cannot be inferred; these require alternative annotation strategies (e.g., MS2 matching or manual curation).
- Formula inference depends entirely on accuracy of khipu-assigned adducts; incorrect adduct assignments propagate to incorrect formula inferences and failed or erroneous database matches.
- Reference databases (HMDB, LMSD) must be downloaded and indexed locally via 'pcpfm download_extras'; the JMS-compliant versions are not redistributed with the package.
- No explicit m/z tolerance is applied during formula-based querying; ambiguity arises only if multiple distinct neutral formulas can produce the same observed m/z under the assigned adduct—a rare but possible edge case.
- Support for non-standard or custom adducts not explicitly handled by khipu may result in formula inference failures.

## Evidence

- [other] Level 4 annotation infers formulas from EmpCpd parameters without requiring explicit mz tolerance specification, as the search uses the inferred formula from the EmpCpd which will be determined by the parameters used for construction.: "Level 4 annotation infers formulas from EmpCpd parameters without requiring explicit mz tolerance specification, as the search uses the inferred formula from the EmpCpd which will be determined by"
- [other] Singleton empirical compounds are not currently annotated at Level 4 since their adducts cannot be inferred.: "Singleton empirical compounds are not currently annotated at Level 4 since their adducts cannot be inferred."
- [other] Load the pre-built empCpd object (moniker specified by user) containing grouped features with inferred molecular formulas and adduct assignments from khipu.: "Load the pre-built empCpd object (moniker specified by user) containing grouped features with inferred molecular formulas and adduct assignments from khipu."
- [other] Query the JMS-compliant HMDB and LMSD reference databases downloaded via 'pcpfm download_extras' using the inferred formula from each empCpd (no explicit mz tolerance applied; formula determines the search).: "Query the JMS-compliant HMDB and LMSD reference databases downloaded via 'pcpfm download_extras' using the inferred formula from each empCpd (no explicit mz tolerance applied; formula determines the"
- [other] Retrieve all database entries matching the inferred formula and assign them as Level 4 candidate annotations to the corresponding empCpd.: "Retrieve all database entries matching the inferred formula and assign them as Level 4 candidate annotations to the corresponding empCpd."
- [readme] a JMS-compliant version of the HMDB and LMSD can be download: "a JMS-compliant version of the HMDB and LMSD can be download"