adduct-mass-calculation-and-matching
Summary
Calculate theoretical m/z values for molecular adducts (M+H, M+NH4, M+Na, M+K, etc.) and match them against observed mass spectrometry peaks within specified mass accuracy tolerance. This skill is essential for validating detected peaks in non-targeted LC-HRMS workflows and for generating reliable benchmark datasets with known adduct composition.
When to use
When you have a list of target molecules with known molecular formulas and need to extract and validate their peaks from centroided mzML files, or when assessing whether detected peaks in a mass spectrometry run correspond to expected adducts of known metabolites. Specifically apply this when generating benchmark datasets to validate non-targeted data pre-processing tools (XCMS, MZmine, MS-DIAL, etc.).
When NOT to use
- Input data are not centroided (peak-picked) — first convert via MSconvert or equivalent tool.
- Molecular formula contains trailing zeros (e.g., 'C12H8N0S2') — formulas must be cleaned before submission.
- You lack retention time boundaries (user.rtmin/user.rtmax) for target compounds — this skill requires prior manual curation or external RT database to set boundaries.
Inputs
- Centroided mzML files (LC-HRMS data)
- Target molecule file (CSV with columns: molecule, SumForm_c, main_adduct, user.rtmin, user.rtmax, and optional adduct_c)
- Instrument resolution specification (e.g., 'OrbitrapXL,Velos,VelosPro_R60000@400' or custom CSV with R and m/z columns)
- List of adducts to match (e.g., M+H, M+NH4, M+Na, M+K)
Outputs
- Benchmark dataset (CSV) with detected peaks linked to target molecules, including validated adducts and isotopologues
- Peak annotations with calculated m/z, isotopologue ratio metrics, and peak shape quality scores
- Summary statistics: number of molecules detected, number of features (adducts + isotopologues), total peak count
How to apply
Use enviPat to predict all isotopologues for each target molecule under the specified instrument resolution (e.g., OrbitrapXL/Velos at R=60000 @ 400 m/z). For each adduct specified (main_adduct and additional adducts), calculate the theoretical m/z and isotopic pattern. Extract ion chromatograms (EICs) centered on these m/z values within the mass accuracy window (e.g., ±6 ppm or ±5 ppm as specified). Match observed peaks to theoretical m/z by requiring: (1) detection of the most abundant isotopologue AND at least one additional isotopologue, (2) peak shape correlation ≥0.85 with the most abundant isotopologue, and (3) isotopologue abundance ratios within 30% of predicted values. Reject adducts if fewer than two isotopologues are detected. Apply this iteratively across all target molecules and sample files.
Related tools
- mzRAPP (Orchestrates adduct mass calculation, isotopologue prediction, EIC extraction, and peak matching via the 'Generate Benchmark' tab; handles multi-adduct validation and isotope filtering) — https://github.com/YasinEl/mzRAPP
- enviPat (Predicts isotopologue patterns and calculates theoretical m/z values for all adducts under instrument-specific mass resolution; provides isotope abundance ratios for validation)
- R (Runtime environment for calling mzRAPP functions programmatically (e.g., library(mzRAPP); callmzRAPP()))
- MSconvert (Converts vendor mass spectrometry formats to centroided mzML for input to adduct matching pipeline) — http://proteowizard.sourceforge.net/tools.shtml
Examples
library(mzRAPP); callmzRAPP() # Then navigate to Generate Benchmark tab, select 30 _POS.mzML files, sample-group CSV, target CSV; set instrument to OrbitrapXL,Velos,VelosPro_R60000@400; select adducts M+NH4, M+Na, M+K; set mass accuracy 5 ppm, mass precision 6 ppm; execute and export benchmark CSV.
Evaluation signals
- All main_adducts for target molecules are detected; if a main_adduct is not found, no secondary adducts should be accepted for that molecule.
- Isotopologue abundance ratios fall within ±30% of enviPat predictions; deviations beyond this threshold indicate degraded data quality or mismatched peaks.
- Peak shape correlation coefficient ≥0.85 between low-abundance and most-abundant isotopologue, indicating coherent chromatographic behavior.
- For the MTBLS267 benchmark (30 _POS.mzML files, OrbitrapXL/Velos/VelosPro, M+NH4/M+Na/M+K adducts), expect ~47 molecules, ~157 features, ~2870 total peaks after filtering.
- Number of detected peaks aligns with expectations from prior processing runs (e.g., 83–99% detection rate post-alignment, depending on tool used).
Limitations
- Adducts will only be added to the benchmark if at least two isotopologues of the respective adduct can be detected; rare or low-abundance adducts may be missed.
- Retention time boundaries (user.rtmin/user.rtmax) must be manually curated or provided externally; mzRAPP can refine them to 5% peak height intersections, but cannot discover them de novo.
- Mass resolution specification must match the actual instrument used; incorrect resolution will cause systematic mismatches between theoretical and observed m/z.
- Isotopologue filtering removes peaks with correlation <0.85 or ratio bias >30%; this may exclude valid low-abundance isotopologues in noisy samples.
- Centroiding is required; profile-mode data will fail or produce unreliable results.
Evidence
- [readme] mzRAPP extracts and validates chromatographic peaks for which boundaries are provided for all (enviPat predicted) isotopologues: "mzRAPP extracts and validates chromatographic peaks for which boundaries are provided for all (enviPat predicted) isotopologues of those target molecules directly from mzML files"
- [readme] Isotopologue peaks with area/height >30% off predicted or Pearson correlation <0.85 are removed: "Isotopologue peaks with an area or height which is more than 30% off the predicted value or a Pearson Correlation coef < 0.85 (as compared to the highest isotopologue) are removed"
- [readme] Only isotopologues where most abundant and at least one additional isotopologue are found are kept: "Only isotopologues for which the theoretically most abundant and at least one additional isotopologue are found are considered for the final benchmark"
- [readme] If main_adduct not detected, other adducts are not accepted; adducts must satisfy isotope criteria: "If the main_adduct is not detected also other adducts wont be accepted. Therefore it makes sense to select the most trusted adduct (generally M+H or M-H) as main adduct"
- [methods] MTBLS267 benchmark generation produced 47 molecules with 157 features and 2870 peaks: "Processing all 30 mzML files generates a benchmark containing 47 different molecules with 157 different features including all adducts and isotopologues, resulting in 2870 peaks in total"
- [methods] Mass accuracy and precision parameters are specified in ppm: "Configure extraction parameters: lowest isotopologue 0.05, minimum 6 scans per peak, 6 ppm mass precision, 5 ppm mass accuracy"
- [readme] Target file must include molecular composition, main adduct, and retention time boundaries: "molecule: names of target molecules (should be unique identifiers) ... SumForm_c: Molecular composition of the neutral molecule ... main_adduct: One main adduct has to be defined for each molecule"
- [readme] Adducts are only added if at least two isotopologues are detected: "adducts will only be added if at least two isotoplogues of the respective adduct can be detected"
1---2name: adduct-mass-calculation-and-matching3description: Use when when you have a list of target molecules with known molecular formulas and need to extract and validate their peaks from centroided mzML files, or when assessing whether detected peaks in a mass spectrometry run correspond to expected adducts of known metabolites.4license: CC-BY-4.05---67# adduct-mass-calculation-and-matching89## Summary1011Calculate theoretical m/z values for molecular adducts (M+H, M+NH4, M+Na, M+K, etc.) and match them against observed mass spectrometry peaks within specified mass accuracy tolerance. This skill is essential for validating detected peaks in non-targeted LC-HRMS workflows and for generating reliable benchmark datasets with known adduct composition.1213## When to use1415When you have a list of target molecules with known molecular formulas and need to extract and validate their peaks from centroided mzML files, or when assessing whether detected peaks in a mass spectrometry run correspond to expected adducts of known metabolites. Specifically apply this when generating benchmark datasets to validate non-targeted data pre-processing tools (XCMS, MZmine, MS-DIAL, etc.).1617## When NOT to use1819- Input data are not centroided (peak-picked) — first convert via MSconvert or equivalent tool.20- Molecular formula contains trailing zeros (e.g., 'C12H8N0S2') — formulas must be cleaned before submission.21- You lack retention time boundaries (user.rtmin/user.rtmax) for target compounds — this skill requires prior manual curation or external RT database to set boundaries.2223## Inputs2425- Centroided mzML files (LC-HRMS data)26- Target molecule file (CSV with columns: molecule, SumForm_c, main_adduct, user.rtmin, user.rtmax, and optional adduct_c)27- Instrument resolution specification (e.g., 'OrbitrapXL,Velos,VelosPro_R60000@400' or custom CSV with R and m/z columns)28- List of adducts to match (e.g., M+H, M+NH4, M+Na, M+K)2930## Outputs3132- Benchmark dataset (CSV) with detected peaks linked to target molecules, including validated adducts and isotopologues33- Peak annotations with calculated m/z, isotopologue ratio metrics, and peak shape quality scores34- Summary statistics: number of molecules detected, number of features (adducts + isotopologues), total peak count3536## How to apply3738Use enviPat to predict all isotopologues for each target molecule under the specified instrument resolution (e.g., OrbitrapXL/Velos at R=60000 @ 400 m/z). For each adduct specified (main_adduct and additional adducts), calculate the theoretical m/z and isotopic pattern. Extract ion chromatograms (EICs) centered on these m/z values within the mass accuracy window (e.g., ±6 ppm or ±5 ppm as specified). Match observed peaks to theoretical m/z by requiring: (1) detection of the most abundant isotopologue AND at least one additional isotopologue, (2) peak shape correlation ≥0.85 with the most abundant isotopologue, and (3) isotopologue abundance ratios within 30% of predicted values. Reject adducts if fewer than two isotopologues are detected. Apply this iteratively across all target molecules and sample files.3940## Related tools4142- **mzRAPP** (Orchestrates adduct mass calculation, isotopologue prediction, EIC extraction, and peak matching via the 'Generate Benchmark' tab; handles multi-adduct validation and isotope filtering) — https://github.com/YasinEl/mzRAPP43- **enviPat** (Predicts isotopologue patterns and calculates theoretical m/z values for all adducts under instrument-specific mass resolution; provides isotope abundance ratios for validation)44- **R** (Runtime environment for calling mzRAPP functions programmatically (e.g., library(mzRAPP); callmzRAPP()))45- **MSconvert** (Converts vendor mass spectrometry formats to centroided mzML for input to adduct matching pipeline) — http://proteowizard.sourceforge.net/tools.shtml4647## Examples4849```50library(mzRAPP); callmzRAPP() # Then navigate to Generate Benchmark tab, select 30 _POS.mzML files, sample-group CSV, target CSV; set instrument to OrbitrapXL,Velos,VelosPro_R60000@400; select adducts M+NH4, M+Na, M+K; set mass accuracy 5 ppm, mass precision 6 ppm; execute and export benchmark CSV.51```5253## Evaluation signals5455- All main_adducts for target molecules are detected; if a main_adduct is not found, no secondary adducts should be accepted for that molecule.56- Isotopologue abundance ratios fall within ±30% of enviPat predictions; deviations beyond this threshold indicate degraded data quality or mismatched peaks.57- Peak shape correlation coefficient ≥0.85 between low-abundance and most-abundant isotopologue, indicating coherent chromatographic behavior.58- For the MTBLS267 benchmark (30 _POS.mzML files, OrbitrapXL/Velos/VelosPro, M+NH4/M+Na/M+K adducts), expect ~47 molecules, ~157 features, ~2870 total peaks after filtering.59- Number of detected peaks aligns with expectations from prior processing runs (e.g., 83–99% detection rate post-alignment, depending on tool used).6061## Limitations6263- Adducts will only be added to the benchmark if at least two isotopologues of the respective adduct can be detected; rare or low-abundance adducts may be missed.64- Retention time boundaries (user.rtmin/user.rtmax) must be manually curated or provided externally; mzRAPP can refine them to 5% peak height intersections, but cannot discover them de novo.65- Mass resolution specification must match the actual instrument used; incorrect resolution will cause systematic mismatches between theoretical and observed m/z.66- Isotopologue filtering removes peaks with correlation <0.85 or ratio bias >30%; this may exclude valid low-abundance isotopologues in noisy samples.67- Centroiding is required; profile-mode data will fail or produce unreliable results.6869## Evidence7071- [readme] mzRAPP extracts and validates chromatographic peaks for which boundaries are provided for all (enviPat predicted) isotopologues: "mzRAPP extracts and validates chromatographic peaks for which boundaries are provided for all (enviPat predicted) isotopologues of those target molecules directly from mzML files"72- [readme] Isotopologue peaks with area/height >30% off predicted or Pearson correlation <0.85 are removed: "Isotopologue peaks with an area or height which is more than 30% off the predicted value or a Pearson Correlation coef < 0.85 (as compared to the highest isotopologue) are removed"73- [readme] Only isotopologues where most abundant and at least one additional isotopologue are found are kept: "Only isotopologues for which the theoretically most abundant and at least one additional isotopologue are found are considered for the final benchmark"74- [readme] If main_adduct not detected, other adducts are not accepted; adducts must satisfy isotope criteria: "If the main_adduct is not detected also other adducts wont be accepted. Therefore it makes sense to select the most trusted adduct (generally M+H or M-H) as main adduct"75- [methods] MTBLS267 benchmark generation produced 47 molecules with 157 features and 2870 peaks: "Processing all 30 mzML files generates a benchmark containing 47 different molecules with 157 different features including all adducts and isotopologues, resulting in 2870 peaks in total"76- [methods] Mass accuracy and precision parameters are specified in ppm: "Configure extraction parameters: lowest isotopologue 0.05, minimum 6 scans per peak, 6 ppm mass precision, 5 ppm mass accuracy"77- [readme] Target file must include molecular composition, main adduct, and retention time boundaries: "molecule: names of target molecules (should be unique identifiers) ... SumForm_c: Molecular composition of the neutral molecule ... main_adduct: One main adduct has to be defined for each molecule"78- [readme] Adducts are only added if at least two isotopologues are detected: "adducts will only be added if at least two isotoplogues of the respective adduct can be detected"
HolobiomicsLab 