# Precursor Mass Difference Calculation

> Use when when comparing two MS/MS spectra using modified cosine similarity and the precursor m/z values differ, indicating potential neutral losses, adduct variations, or analogs with different substituents.

- Skill: `holobiomicslab/precursor-mass-difference-calculation` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/precursor-mass-difference-calculation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/precursor-mass-difference-calculation/raw
- Safety review: pending
- 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/precursor-mass-difference-calculation

---


# precursor-mass-difference-calculation

## Summary

Calculate the mass offset between precursor ions of two MS/MS spectra to enable alignment of peaks under the modified cosine similarity measure. This step is essential for detecting structurally related molecules that differ in mass.

## When to use

When comparing two MS/MS spectra using modified cosine similarity and the precursor m/z values differ, indicating potential neutral losses, adduct variations, or analogs with different substituents. You need this calculation before attempting to align peaks across spectra with non-zero mass offsets.

## When NOT to use

- Input spectra have identical or negligibly different precursor m/z values (use standard cosine similarity instead)
- Comparing spectra where mass differences are artifacts of measurement error rather than chemical modification (apply mass calibration first)
- Neutral loss similarity is being used instead of modified cosine similarity, as it does not require this offset calculation

## Inputs

- MS/MS spectrum (query) with precursor_mz field
- MS/MS spectrum (reference) with precursor_mz field

## Outputs

- precursor mass difference (float, in Da)
- mass offset parameter for peak alignment

## How to apply

Extract the precursor m/z value from both the query spectrum and the reference spectrum. Subtract the reference precursor m/z from the query precursor m/z to obtain the mass difference (in Da). This offset is then used during peak matching: peaks are considered aligned if m/z_query matches m/z_reference + mass_difference within the specified tolerance. The mass difference accommodates the shift in the m/z axis caused by different precursor masses, allowing the modified cosine algorithm to score aligned peak intensities correctly. Typically this tolerance is 0.1 Da or specified by the instrument calibration.

## Related tools

- **spectrum_utils** (Load and parse MS/MS spectra with precursor_mz annotation; extract precursor charge and m/z fields)
- **cosine_neutral_loss repository** (Reference implementation of modified cosine similarity scoring that uses the precursor mass difference for peak alignment) — https://github.com/bittremieux/cosine_neutral_loss

## Examples

```
import spectrum_utils.spectrum as sus; spectrum1 = sus.MsmsSpectrum.from_usi(usi1); spectrum2 = sus.MsmsSpectrum.from_usi(usi2); mass_diff = spectrum1.precursor_mz - spectrum2.precursor_mz; print(f'Precursor mass difference: {mass_diff} Da')
```

## Evaluation signals

- Precursor mass difference is a scalar float, typically in range ±500 Da for MS/MS comparisons
- When mass difference is applied as offset during peak matching, the number of matched peaks should increase relative to standard (non-offset) cosine similarity for true analogs
- Peak alignment consistency: verify that m/z_query == m/z_reference + mass_difference holds for matched peak pairs within specified tolerance
- Modified cosine score should be higher for mass-offset analogs compared to standard cosine score computed without offset
- Mass difference should be reproducible and stable across repeated calculations for the same spectrum pair

## Limitations

- Precursor mass difference assumes both spectra originate from the same ionization method and charge state; different charge states require normalization first
- Very large mass differences (>1000 Da) may indicate data quality issues or misidentified precursor ions rather than true analogs
- The calculation does not account for measurement uncertainty; alignment tolerance must be set appropriately for instrument resolution
- Modified cosine similarity with mass offset is designed for discovery of structurally related molecules; it may produce spuriously high scores for unrelated spectra with coincidental mass differences

## Evidence

- [other] Extract precursor m/z values from both spectra. 3. Calculate the precursor mass difference between the two spectra. 4. Match peaks between spectra allowing for the precursor mass offset (modified cosine: peaks at m/z_query and m/z_reference + mass_difference are considered aligned).: "Extract precursor m/z values from both spectra. 3. Calculate the precursor mass difference between the two spectra. 4. Match peaks between spectra allowing for the precursor mass offset"
- [other] Modified cosine similarity is a spectrum similarity measure implemented in the repository alongside cosine similarity and neutral loss similarity for comparing MS/MS spectra in the discovery of structurally related molecules.: "Modified cosine similarity is a spectrum similarity measure implemented in the repository alongside cosine similarity and neutral loss similarity for comparing MS/MS spectra in the discovery of"
- [readme] Modified cosine similarity <br/>   Watrous, J. _et al_. Mass spectral molecular networking of living microbial colonies. _Proceedings of the National Academy of Sciences_ **109**, E1743–E1752 (2012).: "Modified cosine similarity ... Mass spectral molecular networking of living microbial colonies"
- [readme] spectrum1.precursor_charge = 1
    spectrum1 = spectrum1.set_mz_range(0, spectrum1.precursor_mz): "spectrum1.precursor_charge = 1; spectrum1 = spectrum1.set_mz_range(0, spectrum1.precursor_mz)"