neutral-mass-inference-from-ion-ensemble
License: restricted — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution.
Summary
Infer the neutral mass of a compound from an ensemble of observed ions (adducts and isotopologues) by fitting their measured m/z values against a theoretical khipu grid using linear regression. This skill recovers the ground-truth neutral mass from degenerate ion populations in untargeted LC-MS data.
When to use
You have a connected subnetwork of feature ions that have been validated as belonging to the same empirical compound (khipu instance), with isotope and adduct edges assigned, and you need to estimate the true neutral mass M0 rather than relying on any single observed m/z. This is especially valuable when the [M+H]+ or other primary adduct is weak, absent, or ambiguous.
When NOT to use
- Khipu tree has not yet been constructed or validated—you are still in the feature-pair matching phase.
- Only a single ion (e.g., one [M+H]+ peak) is available; regression requires multiple ions to be meaningful.
- The feature table contains unfiltered noise or low-SNR ions; pre-filter by SNR > 100 or equivalent before khipu construction if data quality is poor.
Inputs
- khipu instance (tree-structured subnetwork with assigned isotope and adduct edges)
- populated ion nodes with observed m/z values
- theoretical khipu grid (mass offsets for adduct types and isotope counts)
Outputs
- inferred neutral mass M0 (float, in Da)
- linear regression fit quality metrics (e.g., R-squared, residuals)
How to apply
After constructing a khipu tree with nodes assigned to isotope and adduct classes, collect all observed m/z values from the populated nodes. For each node, look up its theoretical m/z offset from the khipu grid (e.g., M0 + 1.007276 for [M+H]+, M0 + 2.010631 for M+1 13C [M+H]+). Set up a linear regression where the independent variable is the theoretical offset and the dependent variable is the observed m/z. Solve for the intercept, which is the neutral mass M0. Use only ions that passed redundancy inspection and tree optimization; exclude nodes flagged as mistakes or unresolved signals. The regression exploits all available ions simultaneously, reducing noise and increasing robustness compared to single-ion estimates.
Related tools
- networkx (Supports graph construction and connected-component analysis to identify and validate the ion subnetwork before neutral mass inference)
- mass2chem (Provides search functions and pattern library to match feature pairs to isotope and adduct patterns, which are prerequisite to tree construction and regression setup) — https://github.com/shuzhao-li-lab/mass2chem
- khipu (Weavor and Khipu classes) (Manages khipu instance construction, tree optimization, and encapsulates the neutral mass inference workflow via linear regression) — https://github.com/shuzhao-li-lab/khipu
- treelib (Provides tree visualization to inspect the final tree structure and confirm node assignments before regression)
Examples
khipu -i feature_table.tsv -o output_prefix --ppm 5 --rtol 10 -m pos
Evaluation signals
- Regression R² ≥ 0.95 (high fit quality across the ion ensemble) indicates robust neutral mass estimate.
- Residuals (observed m/z − predicted m/z for each ion) should be small and randomly distributed around zero, not systematically offset by ion type.
- Inferred M0 should be consistent across multiple independent runs on the same khipu instance (reproducibility).
- M0 should fall within ±5 ppm of any independently measured or reference mass for the same compound, validating against external ground truth when available.
- Exclusion of redundant or low-quality nodes from the regression should not cause large jumps in M0 estimate (stability under node removal).
Limitations
- Linear regression assumes all ions in the tree belong to the same neutral mass; if unresolved signals or false edges persist in the tree, M0 will be biased.
- Regression quality depends on diversity of observed adduct and isotope types; trees with only a few ion types or sparse populations may have high uncertainty.
- Systematic m/z calibration errors in the mass spectrometer are not corrected by this method and will shift M0 proportionally.
- Some ions may enter the initial network by mistakes or unresolved signals and are removed from the established khipu; these exclusions must occur before regression to avoid pulling M0 off-target.
- The method assumes the theoretical khipu grid (mass offsets for adducts, isotope shifts) is accurate; deviations due to instrumental noise or chemical artifacts will reduce fit quality.
Evidence
- [readme] Based on available ions and the theoretical 'khipu grid', the neutral mass can be obtained via linear regression: "Based on available ions and the theoretical "khipu grid", the neutral mass can be obtained via linear regression"
- [readme] Each subnetwork becomes a khipu instance. The subnetwork is inspected, redundant nodes removed, and converted to an optimal tree structure: "Each subnetwork becomes a khipu instance. The subnetwork is inspected, redundant nodes removed, and converted to an optimal tree structure"
- [readme] Some ions may come into the initial network by mistakes or unresolved signals. They are removed from the established khipu: "Some ions may come into the initial network by mistakes or unresolved signals. They are removed from the established khipu"
- [intro] Pre-annotation tool to annotate degenerate ions in relationships to the original compound and infer neutral mass: "Pre-annotation tool to annotate degenerate ions in relationships to the original compound and infer neutral mass"
1---2name: neutral-mass-inference-from-ion-ensemble-23description: Use when you have a connected subnetwork of feature ions that have been validated as belonging to the same empirical compound (khipu instance), with isotope and adduct edges assigned, and you need to estimate the true neutral mass M0 rather than relying on any single observed m/z.4license: CC-BY-4.05---67# neutral-mass-inference-from-ion-ensemble89> **License: restricted** — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution. <!-- asb-license-banner -->10## Summary1112Infer the neutral mass of a compound from an ensemble of observed ions (adducts and isotopologues) by fitting their measured m/z values against a theoretical khipu grid using linear regression. This skill recovers the ground-truth neutral mass from degenerate ion populations in untargeted LC-MS data.1314## When to use1516You have a connected subnetwork of feature ions that have been validated as belonging to the same empirical compound (khipu instance), with isotope and adduct edges assigned, and you need to estimate the true neutral mass M0 rather than relying on any single observed m/z. This is especially valuable when the [M+H]+ or other primary adduct is weak, absent, or ambiguous.1718## When NOT to use1920- Khipu tree has not yet been constructed or validated—you are still in the feature-pair matching phase.21- Only a single ion (e.g., one [M+H]+ peak) is available; regression requires multiple ions to be meaningful.22- The feature table contains unfiltered noise or low-SNR ions; pre-filter by SNR > 100 or equivalent before khipu construction if data quality is poor.2324## Inputs2526- khipu instance (tree-structured subnetwork with assigned isotope and adduct edges)27- populated ion nodes with observed m/z values28- theoretical khipu grid (mass offsets for adduct types and isotope counts)2930## Outputs3132- inferred neutral mass M0 (float, in Da)33- linear regression fit quality metrics (e.g., R-squared, residuals)3435## How to apply3637After constructing a khipu tree with nodes assigned to isotope and adduct classes, collect all observed m/z values from the populated nodes. For each node, look up its theoretical m/z offset from the khipu grid (e.g., M0 + 1.007276 for [M+H]+, M0 + 2.010631 for M+1 13C [M+H]+). Set up a linear regression where the independent variable is the theoretical offset and the dependent variable is the observed m/z. Solve for the intercept, which is the neutral mass M0. Use only ions that passed redundancy inspection and tree optimization; exclude nodes flagged as mistakes or unresolved signals. The regression exploits all available ions simultaneously, reducing noise and increasing robustness compared to single-ion estimates.3839## Related tools4041- **networkx** (Supports graph construction and connected-component analysis to identify and validate the ion subnetwork before neutral mass inference)42- **mass2chem** (Provides search functions and pattern library to match feature pairs to isotope and adduct patterns, which are prerequisite to tree construction and regression setup) — https://github.com/shuzhao-li-lab/mass2chem43- **khipu (Weavor and Khipu classes)** (Manages khipu instance construction, tree optimization, and encapsulates the neutral mass inference workflow via linear regression) — https://github.com/shuzhao-li-lab/khipu44- **treelib** (Provides tree visualization to inspect the final tree structure and confirm node assignments before regression)4546## Examples4748```49khipu -i feature_table.tsv -o output_prefix --ppm 5 --rtol 10 -m pos50```5152## Evaluation signals5354- Regression R² ≥ 0.95 (high fit quality across the ion ensemble) indicates robust neutral mass estimate.55- Residuals (observed m/z − predicted m/z for each ion) should be small and randomly distributed around zero, not systematically offset by ion type.56- Inferred M0 should be consistent across multiple independent runs on the same khipu instance (reproducibility).57- M0 should fall within ±5 ppm of any independently measured or reference mass for the same compound, validating against external ground truth when available.58- Exclusion of redundant or low-quality nodes from the regression should not cause large jumps in M0 estimate (stability under node removal).5960## Limitations6162- Linear regression assumes all ions in the tree belong to the same neutral mass; if unresolved signals or false edges persist in the tree, M0 will be biased.63- Regression quality depends on diversity of observed adduct and isotope types; trees with only a few ion types or sparse populations may have high uncertainty.64- Systematic m/z calibration errors in the mass spectrometer are not corrected by this method and will shift M0 proportionally.65- Some ions may enter the initial network by mistakes or unresolved signals and are removed from the established khipu; these exclusions must occur before regression to avoid pulling M0 off-target.66- The method assumes the theoretical khipu grid (mass offsets for adducts, isotope shifts) is accurate; deviations due to instrumental noise or chemical artifacts will reduce fit quality.6768## Evidence6970- [readme] Based on available ions and the theoretical 'khipu grid', the neutral mass can be obtained via linear regression: "Based on available ions and the theoretical "khipu grid", the neutral mass can be obtained via linear regression"71- [readme] Each subnetwork becomes a khipu instance. The subnetwork is inspected, redundant nodes removed, and converted to an optimal tree structure: "Each subnetwork becomes a khipu instance. The subnetwork is inspected, redundant nodes removed, and converted to an optimal tree structure"72- [readme] Some ions may come into the initial network by mistakes or unresolved signals. They are removed from the established khipu: "Some ions may come into the initial network by mistakes or unresolved signals. They are removed from the established khipu"73- [intro] Pre-annotation tool to annotate degenerate ions in relationships to the original compound and infer neutral mass: "Pre-annotation tool to annotate degenerate ions in relationships to the original compound and infer neutral mass"
HolobiomicsLab