Reconstruct the mass-difference open-search step to assign candidate adduct/fragment species
Summary
A refinement step that uses exact mass differences to disambiguate ion-species relationships identified through temporal correlation in direct-injection mass spectrometry. It matches observed m/z differences against a user-defined reference table of in-source fragments and adducts to assign chemical labels and assess mass accuracy.
When to use
Apply this skill after temporal correlation has identified feature pairs with matching intensity profiles across direct-injection MS experiments. Use it when you have a list of candidate ion-species pairs (from correlation step) and need to determine whether each pair represents a known adduct or in-source fragment relationship rather than unrelated species.
When NOT to use
- Input feature pairs have not yet been temporally correlated or do not have high correlation coefficients (threshold typically ≥ 0.9); use correlation step first.
- No reference table of in-source fragments and adducts is available or defined for your ionization method and analyte class.
- Mass spectrometry data lacks sufficient resolution to distinguish exact mass differences within the specified ppm tolerance; use coarser mass-window matching instead.
Inputs
- Feature pair table (output from correlation step, containing base_mz, match_mz, correlation coefficient)
- User-defined adduct/fragment reference DataFrame with columns: deltamz (exact mass difference), motive (chemical annotation, e.g. 'O', 'O2', 'H2O', 'O3')
- Mass spectrometry resolution parameter (ppm_window or mass_error tolerance)
Outputs
- Refined candidate table with columns: base_mz, base_index, match_mz, match_index, observed_mzdiff, matched_adduct_label, mass_accuracy_ppm
- Dictionary of DataFrames (one per adduct/fragment type) containing validated feature pair assignments
How to apply
Load the correlation-identified feature pairs and a user-supplied adduct/fragment reference table containing exact mass differences (e.g., [M-H2O+H]+ = 18.01057, [M+nO+H]+ = 15.99491 for each n). 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 (typically 2 ppm for high-resolution FT-ICR-MS). Assign adduct or fragment labels only to feature pairs where the observed mass difference falls within tolerance of a reference entry. Record mass accuracy for each match. Filter out feature pairs with no valid reference match.
Related tools
- DBDIpy (Open-source Python library implementing the mass-difference refinement step via identify_adducts() function with exact mass matching and custom_adducts parameter) — https://github.com/leopold-weidner/DBDIpy
- Python (Core language for DataFrame manipulation and exact mass difference calculations)
- matchms (Ecosystem library integrated with DBDIpy for spectral import/export and preprocessing)
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
- All matched feature pairs have observed mass differences within user-specified ppm tolerance of at least one reference adduct/fragment entry
- Mass accuracy (calculated as abs(observed_mzdiff − reference_deltamz) / reference_deltamz * 1e6) is consistently <5 ppm for high-resolution instruments
- No feature pairs are assigned multiple conflicting adduct labels; each pair maps to at most one reference entry
- Refined table contains only feature pairs where correlation coefficient (from prior step) exceeds threshold (typically 0.9) AND mass difference matches reference list
- Output dictionary structure matches input adduct/fragment categories; each key corresponds to a 'motive' from the reference table
Limitations
- Requires a priori definition of expected adduct and fragment species; cannot discover truly novel mass losses or gains not in the reference table
- Exact mass matching is sensitive to instrument calibration drift; systematic mass errors >specified ppm tolerance will cause valid assignments to be rejected
- High-abundance background ions or isobaric species may create spurious feature pairs with matching temporal profiles but non-biological mass differences
- The DBDIpy implementation (v2.0) is still under development; advanced plotting and runtime optimization are listed as ongoing work
Evidence
- [other] 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]+): "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).: "For each feature pair, calculate the observed mass difference (m/z_feature_B − m/z_feature_A). 3. Match the observed mass difference against the reference adduct/fragment list using exact mass"
- [readme] mass spectrometric data from direct injection analysis is hard to interpret as missing chromatographic separation complicates identification of fragments and adducts: "Mass spectrometric data from direct injection analysis is hard to interpret as missing chromatographic separation complicates identification of fragments and adducts"
- [readme] calculation of pointwise correlation identifies features with matching temporal intensity profiles; (exact) mass differences are used to refine the nature of potential candidates: "calculation of pointwise correlation identifies features with matching temporal intensity profiles through the experiment. - (exact) mass differences are used to refine the nature of potential"
- [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)"
1---2name: feature-pair-mass-refinement3description: Use when after temporal correlation has identified feature pairs with matching intensity profiles across direct-injection MS experiments.4license: CC-BY-4.05---67# Reconstruct the mass-difference open-search step to assign candidate adduct/fragment species89## Summary1011A refinement step that uses exact mass differences to disambiguate ion-species relationships identified through temporal correlation in direct-injection mass spectrometry. It matches observed m/z differences against a user-defined reference table of in-source fragments and adducts to assign chemical labels and assess mass accuracy.1213## When to use1415Apply this skill after temporal correlation has identified feature pairs with matching intensity profiles across direct-injection MS experiments. Use it when you have a list of candidate ion-species pairs (from correlation step) and need to determine whether each pair represents a known adduct or in-source fragment relationship rather than unrelated species.1617## When NOT to use1819- Input feature pairs have not yet been temporally correlated or do not have high correlation coefficients (threshold typically ≥ 0.9); use correlation step first.20- No reference table of in-source fragments and adducts is available or defined for your ionization method and analyte class.21- Mass spectrometry data lacks sufficient resolution to distinguish exact mass differences within the specified ppm tolerance; use coarser mass-window matching instead.2223## Inputs2425- Feature pair table (output from correlation step, containing base_mz, match_mz, correlation coefficient)26- User-defined adduct/fragment reference DataFrame with columns: deltamz (exact mass difference), motive (chemical annotation, e.g. 'O', 'O2', 'H2O', 'O3')27- Mass spectrometry resolution parameter (ppm_window or mass_error tolerance)2829## Outputs3031- Refined candidate table with columns: base_mz, base_index, match_mz, match_index, observed_mzdiff, matched_adduct_label, mass_accuracy_ppm32- Dictionary of DataFrames (one per adduct/fragment type) containing validated feature pair assignments3334## How to apply3536Load the correlation-identified feature pairs and a user-supplied adduct/fragment reference table containing exact mass differences (e.g., [M-H2O+H]+ = 18.01057, [M+nO+H]+ = 15.99491 for each n). 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 (typically 2 ppm for high-resolution FT-ICR-MS). Assign adduct or fragment labels only to feature pairs where the observed mass difference falls within tolerance of a reference entry. Record mass accuracy for each match. Filter out feature pairs with no valid reference match.3738## Related tools3940- **DBDIpy** (Open-source Python library implementing the mass-difference refinement step via identify_adducts() function with exact mass matching and custom_adducts parameter) — https://github.com/leopold-weidner/DBDIpy41- **Python** (Core language for DataFrame manipulation and exact mass difference calculations)42- **matchms** (Ecosystem library integrated with DBDIpy for spectral import/export and preprocessing)4344## Examples4546```47adduct_rule = pd.DataFrame({'deltamz': [47.984744], 'motive': ['O3']})48search_res = dbdi.identify_adducts(df=specs_imputed, masses=feature_mz, custom_adducts=adduct_rule, method='pearson', threshold=0.9, mass_error=2)49```5051## Evaluation signals5253- All matched feature pairs have observed mass differences within user-specified ppm tolerance of at least one reference adduct/fragment entry54- Mass accuracy (calculated as abs(observed_mzdiff − reference_deltamz) / reference_deltamz * 1e6) is consistently <5 ppm for high-resolution instruments55- No feature pairs are assigned multiple conflicting adduct labels; each pair maps to at most one reference entry56- Refined table contains only feature pairs where correlation coefficient (from prior step) exceeds threshold (typically 0.9) AND mass difference matches reference list57- Output dictionary structure matches input adduct/fragment categories; each key corresponds to a 'motive' from the reference table5859## Limitations6061- Requires a priori definition of expected adduct and fragment species; cannot discover truly novel mass losses or gains not in the reference table62- Exact mass matching is sensitive to instrument calibration drift; systematic mass errors >specified ppm tolerance will cause valid assignments to be rejected63- High-abundance background ions or isobaric species may create spurious feature pairs with matching temporal profiles but non-biological mass differences64- The DBDIpy implementation (v2.0) is still under development; advanced plotting and runtime optimization are listed as ongoing work6566## Evidence6768- [other] 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]+): "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]+)"69- [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).: "For each feature pair, calculate the observed mass difference (m/z_feature_B − m/z_feature_A). 3. Match the observed mass difference against the reference adduct/fragment list using exact mass"70- [readme] mass spectrometric data from direct injection analysis is hard to interpret as missing chromatographic separation complicates identification of fragments and adducts: "Mass spectrometric data from direct injection analysis is hard to interpret as missing chromatographic separation complicates identification of fragments and adducts"71- [readme] calculation of pointwise correlation identifies features with matching temporal intensity profiles; (exact) mass differences are used to refine the nature of potential candidates: "calculation of pointwise correlation identifies features with matching temporal intensity profiles through the experiment. - (exact) mass differences are used to refine the nature of potential"72- [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)"
HolobiomicsLab 