Lcms feature probability scoring

lcms-feature-probability-scoring

Summary

Apply Bayesian inference to assign annotation probabilities to LC/MS features by integrating biochemical relations, isotope patterns, and adduct formation. This skill produces a ranked feature table with posterior probabilities for candidate metabolites, enabling confidence-calibrated metabolomics annotation.

When to use

You have an untargeted LC/MS feature table (m/z, retention time, intensity columns) and need to move beyond single-hit matching to probabilistic annotation. Use this skill when you want to leverage prior knowledge about expected adducts, isotope signatures, and metabolic pathway connectivity to disambiguate features that map to multiple database entries.

When NOT to use

• Your data is already manually curated or single-hit matched to a reference library with high confidence (posterior probability >0.95); probabilistic re-scoring adds no value.
• The LC/MS features come from a targeted method with a small, highly specific compound list; Bayesian integration of broad database knowledge introduces noise.
• You lack retention time calibration or expected adduct information for your instrument/sample; the method requires these priors to function; generic defaults will underperform.

Inputs

• LC/MS feature table (CSV/TSV with m/z, retention time in seconds, intensity columns)
• Adducts database (CSV: name, calc formula, charge, mass, ion_mode, formula_add, formula_ded, multiplicity)
• MS¹ compound database (CSV: id, name, formula, inchi, smiles, RT range, adductsPos, adductsNeg, pk prior score, reactions list)
• Optional: MS² spectral database (for fragment annotation cross-validation)
• Optional: biochemical reactions network (for pathway-based probability refinement)

Outputs

• Annotated feature table with posterior annotation probabilities per feature
• Ranked list of candidate metabolites per feature with assigned adduct and probability score
• Feature-to-reaction mappings (if biochemical relations enabled)

How to apply

Load your LC/MS feature data (m/z, retention time, intensity) and configure three database files: an adducts CSV specifying ion-mode-specific mass shifts and charge states; an MS¹ database with compound ID, formula, retention time windows (if known), applicable adducts per ionization mode, and prior knowledge (pk) scores between 0–1 reflecting likelihood the compound appears in your sample; optionally, a reactions file for biochemical relation lookup. Run Bayesian inference via ipaPy2, which computes posterior annotation probabilities for each feature by: (1) enumerating all possible [compound, adduct] pairs consistent with the observed m/z within mass tolerance; (2) scoring each pair using observed isotope pattern fit (13C, ¹⁸O signatures); (3) incorporating prior knowledge and retention time plausibility; (4) integrating biochemical pathway context (e.g., compounds co-occurring in known reactions receive higher joint probability). Output is an annotated feature table ranked by posterior probability, with top candidate metabolites, adduct assignments, and confidence scores.

Related tools

• ipaPy2 (Bayesian inference engine for computing posterior annotation probabilities by integrating adduct, isotope, and biochemical likelihood scores) — https://github.com/francescodc87/ipaPy2
• Python (Scripting language for data loading, database configuration, and output parsing)

Examples

import pandas as pd
from ipaPy2 import IPA
adducts = pd.read_csv('DB/adducts.csv')
db = pd.read_csv('DB/IPA_MS1.csv')
features = pd.read_csv('features.csv')  # m/z, RT, intensity
ipa = IPA(adducts=adducts, ms1_db=db)
result = ipa.annotate(features, ppm_tol=5, rt_window_scale=1.0)
result.to_csv('annotated_features.csv')

Evaluation signals

• All features in input table appear in output with assigned probabilities; no rows silently dropped (data integrity check).
• Posterior probabilities for each feature sum to ≤1.0 and top candidate has probability >0.5 for majority of well-ionizable compounds (probability calibration).
• Features with m/z matching multiple database entries show lower individual probabilities than features with unique m/z matches (Bayesian discrimination working).
• Isotope pattern scores for assigned adducts are within ±5 ppm of theoretical m/z; features with poor isotope fit receive lower posterior scores (isotope refinement validated).
• Known biochemical reaction pairs (e.g., ATP and ADP in same pathway) show positively correlated posteriors when co-detected (pathway coherence check).

Limitations

• Method requires accurate mass calibration (±5 ppm or better for meaningful isotope discrimination); poor calibration degrades isotope pattern scoring and posterior confidence.
• Prior knowledge (pk scores) and retention time windows must be empirically tuned to your specific instrument, chromatography, and sample type; generic database defaults will underperform on novel matrices.
• Biochemical relation integration assumes reaction networks are complete and accurate; missing or erroneous pathway data can mislead probability estimates.
• No changelog documented in repository; version stability and backward compatibility not explicitly tracked.
• Performance scales with database size; large custom databases (>10,000 entries) may incur computational overhead; sparse adduct/isotope filtering recommended.

Evidence

• [other] IPA is a Bayesian annotation method for LC/MS data that integrates three key information sources: biochemical relations, isotope patterns, and adduct formation to compute annotation probabilities.: "IPA is a Bayesian annotation method for LC/MS data that integrates three key information sources: biochemical relations, isotope patterns, and adduct formation to compute annotation probabilities."
• [other] Run Bayesian inference to compute posterior annotation probabilities for each feature, integrating biochemical plausibility, observed isotope patterns, and predicted adduct formation.: "Run Bayesian inference to compute posterior annotation probabilities for each feature, integrating biochemical plausibility, observed isotope patterns, and predicted adduct formation."
• [readme] The IPA method requires a pandas dataframe containing the database against which the annotation is performed. This dataframe must contain the following columns in this exact order (optional columns can have empty fields): id, name, formula, inchi, smiles, RT, adductsPos, adductsNeg, description, pk, MS2, reactions: "The IPA method requires a pandas dataframe containing the database against which the annotation is performed. This dataframe must contain the following columns in this exact order (optional columns"
• [readme] One of the most powerful features of the IPA method is that it is able to integrate the knowledge gained from previous experiments in the annotation process.: "One of the most powerful features of the IPA method is that it is able to integrate the knowledge gained from previous experiments in the annotation process."
• [readme] the pk has to be between 1 (compound highly likely to be present in the sample) and 0 (compound cannot be present in the sample).: "the pk has to be between 1 (compound highly likely to be present in the sample) and 0 (compound cannot be present in the sample)."