Mass difference adduct matching

Reconstruct the mass-difference open-search step to assign candidate adduct/fragment species

Summary

This skill uses exact mass differences between correlated feature pairs to refine and disambiguate ion-species relationships in direct-injection mass spectrometry by matching observed m/z deltas against a user-defined reference table of in-source fragments and adducts. It serves as a second refinement layer after temporal correlation, annotating feature pairs with specific adduct or fragment identities and reporting mass accuracy.

When to use

Apply this skill after correlation-based feature pairing has identified feature groups with matching temporal intensity profiles through direct-injection or plasma ionization mass spectrometry experiments. You have a set of putative feature-pair candidates and need to assign specific chemical identities (e.g., [M-H₂O+H]⁺, [M+nO+H]⁺) to each pair by comparing the observed m/z difference to reference adduct/fragment masses.

When NOT to use

• Input already contains manual or database-curated adduct identities and no refinement is needed.
• Feature pairs lack significant temporal correlation (correlation coefficient below user threshold, e.g., < 0.9); mass-difference matching alone cannot establish chemical relationships without temporal evidence.
• Mass spectrometer resolution and mass calibration are poor (mass error >> user-specified ppm tolerance); exact mass differences cannot be reliably resolved.

Inputs

• Feature-pair table from temporal correlation (columns: base_mz, base_index, match_mz, match_index, correlation coefficient)
• User-defined adduct/fragment reference DataFrame (columns: deltamz, motive/ion_formula)
• ppm tolerance parameter (float, typically 2–5 ppm depending on MS resolution)
• Extracted ion chromatogram (XIC) intensities or feature table (for optional validation)

Outputs

• Refined candidate table with columns: base_mz, base_index, match_mz, match_index, observed_mzdiff, matched_adduct/fragment_label, mass_accuracy_ppm, correlation_coefficient
• Dictionary or nested structure indexed by adduct type, each entry containing annotated feature pairs

How to apply

Load the correlation-identified feature pairs (output from temporal correlation step) alongside a user-supplied adduct/fragment mass-difference reference table. For each feature pair, calculate the observed mass difference (m/z_feature_B − m/z_feature_A). Match the observed mass difference against the reference list using exact mass matching within a user-specified ppm tolerance (e.g., 2 ppm for high-resolution instrumentation). Assign adduct or fragment labels to feature pairs where a match is found, recording the mass accuracy (observed − expected mass difference). Output a refined candidate table that lists feature pairs, observed mass differences, matched adduct/fragment annotations, and mass accuracy metrics. The rationale is that chemical adducts and in-source fragments have precise, predictable mass signatures; matching these signatures confirms the ion-species relationship and reduces false-positive correlations.

Related tools

• DBDIpy (Primary library implementing the mass-difference refinement step via identify_adducts() function; handles mass matching, adduct lookup, and result annotation for DBDI-MS and plasma ionization datasets.) — https://github.com/leopold-weidner/DBDIpy
• matchms (Supporting library integrated into DBDIpy for spectral import/export and alignment; provides the ecosystem for preprocessing and comparing mass spectrometric data.)
• Python (Runtime environment for executing DBDIpy and performing DataFrame operations (pandas) for mass-difference calculation and matching.)

Examples

adduct_rule = pd.DataFrame({'deltamz': [47.984744], 'motive': ['O3']}); search_res = dbdi.identify_adducts(df=specs_imputed, masses=feature_mz, custom_adducts=adduct_rule, method='pearson', threshold=0.9, mass_error=2)

Evaluation signals

• Mass accuracy of matched adduct/fragment pairs should be ≤ user-specified ppm tolerance (e.g., observed − expected Δm/z < 2 ppm for high-resolution FT-ICR-MS).
• Annotated feature pairs should show chemical plausibility: e.g., [M+O+H]⁺ pairs should have match_mz > base_mz by ~15.995 Da; [M-H₂O+H]⁺ pairs should have match_mz < base_mz by ~18.011 Da.
• Correlation coefficients of matched pairs should remain ≥ threshold used in prior temporal-correlation step (e.g., ≥ 0.9 for Pearson correlation); mass matching should not include low-correlation false positives.
• Output table should contain no duplicate feature-pair–adduct assignments (each pair matched to at most one adduct type, or multiple only if genuinely ambiguous within tolerance).
• Comparison of matched adduct counts across adduct types should align with known ionization chemistry: e.g., oxygen-addition adducts ([M+O+H]⁺, [M+2O+H]⁺) more prevalent in DBDI than in ESI, consistent with plasma oxidation.

Limitations

• Mass-difference matching is ambiguous when multiple adducts or fragments have similar Δm/z values (e.g., [M+NH₄]⁺ vs. [M+H₂O+H]⁺); user must choose appropriate ppm tolerance and reference-table specificity to resolve.
• Skill assumes temporal correlation has already identified genuine feature pairs; poor correlation thresholds in the prior step will propagate false-positive pairs into mass-difference matching.
• User must define the reference adduct/fragment table; omitted or misspecified adduct masses will result in unmatched feature pairs, reducing coverage. Custom adducts must be user-supplied; the method does not enumerate novel or unexpected in-source modifications.
• Mass calibration errors and resolution limitations of the MS instrument directly limit achievable ppm accuracy; instruments with poor mass calibration (> 5–10 ppm drift) may yield unreliable matches even with relaxed tolerance settings.

Evidence

• [other] DBDIpy implements a second refinement step in which exact mass differences are compared against a user-definable list of in-source fragments (e.g., [M-H2O+H]+) and adducts (e.g., [M+nO+H]+) to refine the nature of potential ion-species candidates identified by temporal correlation.: "DBDIpy implements a second refinement step in which exact mass differences are compared against a user-definable list of in-source fragments (e.g., [M-H2O+H]+) and adducts (e.g., [M+nO+H]+)"
• [other] For each feature pair, calculate the observed mass difference (m/z_feature_B − m/z_feature_A). Match the observed mass difference against the reference adduct/fragment list using exact mass matching (within user-specified ppm tolerance).: "calculate the observed mass difference (m/z_feature_B − m/z_feature_A). Match the observed mass difference against the reference adduct/fragment list using exact mass matching (within user-specified"
• [readme] Mass spectrometric data from direct injection analysis is hard to interpret as missing chromatographic separation complicates identification of fragments and adducts generated during the ionization process: "Mass spectrometric data from direct injection analysis is hard to interpret as missing chromatographic separation complicates identification of fragments and adducts"
• [readme] DBDIpy's core functionality relys on putative identification of in-source fragments (eg. [M-H₂O+H]⁺) and in-source generated adducts (eg. [M+nO+H]⁺).: "DBDIpy's core functionality relys on putative identification of in-source fragments (eg. [M-H2O+H]+) and in-source generated adducts (eg. [M+nO+H]+)"
• [readme] (exact) mass differences are used to refine the nature of potential candidates: "(exact) mass differences are used to refine the nature of potential candidates"
• [readme] search_res = dbdi.identify_adducts(df = specs_imputed, masses = feature_mz, custom_adducts = adduct_rule, method = "pearson", threshold = 0.9, mass_error = 2): "identify_adducts(df = specs_imputed, masses = feature_mz, custom_adducts = adduct_rule, method = "pearson", threshold = 0.9, mass_error = 2)"