Adduct fragment formula interpretation

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

Summary

This skill uses exact mass differences between correlated ion features to disambiguate and annotate in-source adducts and fragments (e.g., [M-H₂O+H]⁺, [M+nO+H]⁺) in direct-injection plasma mass spectrometry data. It refines temporal-correlation-identified candidate pairs by matching observed m/z deltas against a user-defined reference table within a specified mass accuracy tolerance.

When to use

Apply this skill after temporal correlation has identified candidate feature pairs with matching intensity profiles across time-resolved DBDI-MS experiments. Use it when you need to discriminate between multiple possible adduct/fragment interpretations for the same analyte—particularly when chromatographic separation is absent and in-source ionization produces multiple ion species per compound.

When NOT to use

• Data already include chromatographic retention time information—use orthogonal chromatographic dimension instead of temporal ionization correlation.
• Input feature table contains missing values (NaN)—impute intensities first to ensure uniform XIC length for mass difference calculation.
• No reference adduct/fragment table is available or cannot be defined for the ionization method—open-search mode may be used, but this skill requires a priori defined mass-difference motives.

Inputs

• Feature correlation table (output from pointwise correlation step with base_mz, match_mz, correlation coefficients)
• Mean m/z values for all features
• User-defined adduct/fragment reference table (DataFrame with deltamz and motive columns)
• Mass spectrometric data parameters (ppm_window matching instrument resolution)

Outputs

• Dictionary of refined candidate tables, one DataFrame per adduct type
• Each DataFrame contains: base_mz, base_index, match_mz, match_index, mzdiff, correlation coefficient, and adduct/fragment label

How to apply

Load the correlation-identified feature pairs (output from the temporal correlation step) and a user-supplied reference table listing expected mass-difference motives (e.g., [M-H₂O+H]⁺ → Δm/z = 18.01057 Da) with their symbolic labels. For each feature pair, calculate the observed mass difference (m/z_feature_B − m/z_feature_A). Compare this observed difference against all entries in the reference table using exact mass matching within the user-specified ppm tolerance (e.g., 2 ppm for high-resolution FT-ICR-MS). Assign adduct or fragment labels to pairs where a match is found. Record the mass accuracy (observed − theoretical) for each match. Output a refined candidate table listing feature pairs, observed mass differences, matched adduct/fragment annotations, and mass accuracy metrics for downstream validation.

Related tools

• DBDIpy (Python library implementing the mass-difference matching and adduct/fragment annotation workflow via the identify_adducts() function) — github.com/leopold-weidner/DBDIpy
• matchms (Ecosystem library integrated with DBDIpy for spectral data import, preprocessing, and MS2 spectral similarity scoring in subsequent refinement steps)

Examples

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 mass differences fall within the user-specified ppm tolerance; mass accuracy (observed − theoretical) is reported for each match.
• Feature pairs matched to adducts/fragments exhibit high correlation coefficients (default threshold ≥ 0.9 Pearson correlation) indicating co-elution during ionization.
• Matched adduct/fragment labels conform to known chemical rules (e.g., [M+nO+H]⁺ only pairs features with positive charge and oxygen additions; [M-H₂O+H]⁺ only pairs features with losses).
• Output table contains no ambiguous matches (each feature pair assigned to ≤1 adduct/fragment motive); if ambiguity exists, report mass accuracy for tie-breaking.
• Cross-validation with MS2 spectral similarity or external reference standards shows that annotated adduct pairs correlate with known or predicted fragmentation patterns.

Limitations

• Accuracy depends on the completeness and correctness of the user-supplied adduct/fragment reference table; missing or misspecified mass differences will result in false negatives.
• High-mass spectral noise or incomplete imputation can artificially inflate correlations, leading to spurious feature pairings before mass-difference filtering; noise reduction in preprocessing is critical.
• Mass accuracy tolerance (ppm_window) must be set appropriately for the instrument resolution; too-wide windows increase false-positive matches, too-narrow windows miss legitimate adducts.
• The skill does not distinguish between multiple ionization pathways producing the same theoretical mass difference (e.g., [M+H]⁺ vs. [M+NH₄]⁺ both produce m/z shifts that may overlap); MS2 spectral similarity or complementary ion-mobility data is needed for disambiguation.

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). 3. 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] 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-H₂O+H]⁺) and in-source generated adducts (eg. [M+nO+H]⁺)"
• [readme] 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 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] Missing values in our feature table will be imputed by a two-stage imputation algorithm. First, missing values within the detected signal region are interpolated in between. Second, a noisy baseline is generated for all XIC to be of uniform length: "Missing values in our feature table will be imputed by a two-stage imputation algorithm. First, missing values within the detected signal region are interpolated in between."