# Feature Pair Mass Refinement

> Use when after temporal correlation has identified feature pairs with matching intensity profiles across direct-injection MS experiments.

- Skill: `holobiomicslab/feature-pair-mass-refinement` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/feature-pair-mass-refinement`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/feature-pair-mass-refinement/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/feature-pair-mass-refinement

---


# 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)"