Fragmentation Strategy Comparison Across Datasets

---
name: fragmentation-strategy-comparison-across-datasets
description: Use when you have extracted a chemical mixture from a real mzML acquisition (e.g., Beer1pos), simulated the same chemicals through ViMMS using a chosen controller (e.
license: CC-BY-4.0
metadata:
  edam_operation: http://edamontology.org/operation_3644
  edam_topics:
  - http://edamontology.org/topic_3370
  - http://edamontology.org/topic_0121
  tools:
  - Python
  - OpenMS
  - ViMMS
  - ChemicalMixtureFromMZML
  techniques:
  - LC-MS
derived_from:
- doi: 10.21105/joss.03990
  title: vimms
- doi: 10.1021/acs.analchem.0c03895
  title: ''
evidence_spans:
- ViMMS is compatible with Python 3+
- Processes mzML output from a simulation (or real acquisition) to compute fragmentation coverage using OpenMS
claims: []
provenance:
  collection: https://w3id.org/holobiomicslab/asb-skill/collection/metabolomics/v2
  assembled_by: scripts/collect_metabolomics_collection.py
  sources:
  - build: coll_vimms
    doi: 10.21105/joss.03990
    title: vimms
  dedup_kept_from: coll_vimms
schema_version: 0.2.0
attribution:
  generator: AgenticScienceBuilder
  original_doi: 10.21105/joss.03990
  all_source_dois:
  - 10.21105/joss.03990
  - 10.1021/acs.analchem.0c03895
  zenodo_doi: 10.5281/zenodo.20794027
  curators: []
  promoter: Louis-Félix Nothias
  sponsor: CNRS & Université Côte d'Azur
---

# fragmentation-strategy-comparison-across-datasets

## Summary

Compare fragmentation coverage and intensity metrics between simulated and real LC-MS/MS data to validate whether a virtual acquisition strategy reproduces experimentally observed fragmentation patterns. This skill bridges simulation fidelity assessment by quantifying how well ViMMS-simulated Top-N (or other) controllers match real instrument behavior on the same chemical mixture.

## When to use

You have extracted a chemical mixture from a real mzML acquisition (e.g., Beer1pos), simulated the same chemicals through ViMMS using a chosen controller (e.g., TopNController with N=5), and now need to verify whether the simulated fragmentation strategy captures the same MS/MS coverage and peak intensity profiles as the original experimental run. Use this skill to validate simulation fidelity before deploying a new acquisition strategy on real instruments.

## When NOT to use

- The real mzML file contains only MS1 data (no MS/MS scans); fragmentation strategy comparison requires MS/MS spectra from both datasets.
- The simulated and real runs used different chemical mixtures or retention time windows; comparison is only meaningful when analyzing the same compounds in the same acquisition window.
- You have not yet run the ViMMS simulation or do not have mzML output from the virtual environment; comparison requires both real and simulated mzML files.

## Inputs

- Real mzML file from experimental LC-MS/MS acquisition (e.g., Beer1pos.mzML)
- Simulated mzML file generated by ViMMS Environment.write_mzML()
- Chemical mixture extracted from real mzML via ChemicalMixtureFromMZML
- Controller configuration parameters (N, isolation_width, intensity thresholds)

## Outputs

- Peak-matched dataset linking real and simulated MS/MS scans
- Fragmentation coverage report (proportion of compounds with MS/MS in each dataset)
- MS1 intensity comparison metrics (mean, median, std dev per dataset)
- Summary report with absolute and relative differences in coverage and intensity

## How to apply

Extract peaks from both the real and simulated mzML files using consistent OpenMS-based peak detection parameters (e.g., MZMine settings). Match MS1 peaks between datasets within a tight tolerance (1 ppm recommended) and MS2 fragment ions within 0.05 ppm, requiring a minimum of 3 matching peaks per compound. Compute fragmentation coverage as the proportion of MS/MS scans acquired in simulation versus the real data, and compare MS1 intensity distributions. Calculate summary statistics (mean, median, standard deviation) for both datasets and report absolute and relative differences. Use evaluation helpers built into ViMMS that rely on peak picking with standardized parameters to ensure reproducibility. Document the isolation width, N value, intensity thresholds (e.g., min_ms1_intensity = 1.75E5), and ROI builder parameters (e.g., min_roi_intensity=0, min_roi_length=3) used in the simulation, as these directly influence whether simulated coverage matches real data.

## Related tools

- **ViMMS** (Framework for simulating fragmentation strategies and generating simulated mzML files; the Environment class and TopNController configure the acquisition parameters to be compared) — https://github.com/glasgowcompbio/vimms
- **OpenMS** (Processes mzML output from both real and simulated acquisitions to compute fragmentation coverage and extract peak intensities using consistent peak detection parameters)
- **ChemicalMixtureFromMZML** (Extracts unknown chemicals (with retention times and m/z values) from the real mzML file to create the chemical list used in ViMMS simulation, ensuring the same compounds are analyzed in both datasets) — https://github.com/glasgowcompbio/vimms
- **Python** (Primary programming environment for running ViMMS simulations, executing peak detection workflows, and computing comparison metrics)

## Examples

```
from vimms.ChemicalMixtureCreator import ChemicalMixtureFromMZML; from vimms.MassSpectrometer import IndependentMassSpectrometer; from vimms.Controller import TopNController; from vimms.Environment import Environment; chemicals = ChemicalMixtureFromMZML('Beer1pos.mzML'); ms = IndependentMassSpectrometer(polarity='positive', chemicals=chemicals); controller = TopNController('positive', N=5, isolation_width=1); env = Environment(ms, controller, min_time=0, max_time=1200); env.run(); env.write_mzML('simulated_beer.mzML')
```

## Evaluation signals

- MS1 peaks matched between real and simulated mzML within ±1 ppm tolerance; number of matched peaks vs. total peaks in each dataset should be reported.
- MS2 fragment ions matched within ±0.05 ppm with minimum 3 matching fragments per compound; matching ratio ≥0.8 suggests good fragmentation fidelity.
- Fragmentation coverage (proportion of compounds with MS/MS in real vs. simulated) should be ≥0.9 and differ by <10% to indicate the strategy captured most target analytes.
- MS1 intensity distributions (mean, median, std dev) should have relative differences <20% between real and simulated data when using the same peak picking parameters.
- Documentation of all parameters (N, isolation_width, min_ms1_intensity, min_roi_intensity, matching tolerances) allows reproducibility and comparison with other strategies.

## Limitations

- Peak picking and matching fidelity depend critically on consistent OpenMS parameters between real and simulated datasets; mismatched peak detection settings will inflate apparent differences.
- The simulation assumes the chemical mixture extracted from mzML is complete and accurate; missing or incorrectly annotated compounds will reduce apparent coverage.
- Simulated intensity distributions may not perfectly match real data if the virtual mass spectrometer model (e.g., IndependentMassSpectrometer) does not faithfully replicate instrument noise, saturation, or dynamic range.
- Fragmentation coverage comparison is most meaningful when the isolation width, collision energy, and other instrument parameters in the simulation match the real acquisition settings; mismatch will confound strategy fidelity with parameter differences.
- MS/MS spectral complexity (number of fragments, intensity distribution) is harder to simulate than MS1; simulated spectra may be more uniform than real fragmentation patterns.

## Evidence

- [other] Can ViMMS simulate Top-N MS/MS acquisition on real beer samples and reproduce the fragmentation coverage observed in the original experimental data?: "Can ViMMS simulate Top-N MS/MS acquisition on real beer samples and reproduce the fragmentation coverage observed in the original experimental data?"
- [other] Extract peaks from both real and simulated mzML files using OpenMS-based peak detection with consistent parameters. Compare fragmentation coverage and intensity metrics between real and simulated datasets and generate a summary report.: "Extract peaks from both real and simulated mzML files using OpenMS-based peak detection with consistent parameters. Compare fragmentation coverage and intensity metrics between real and simulated"
- [results] Filter spectra matching with MS1 tolerance 1 ppm, MS2 tolerance 0.05 ppm, minimum 3 matching peaks: "Filter spectra matching with MS1 tolerance 1 ppm, MS2 tolerance 0.05 ppm, minimum 3 matching peaks"
- [intro] devising new methods is often challenging due to the absence of a structured environment where researchers can prototype, compare, and optimize strategies before testing on real equipment: "devising new methods is often challenging due to the absence of a structured environment where researchers can prototype, compare, and optimize strategies before testing on real equipment"
- [other] The evaluation helpers rely on peak picking using MZMine parameters defined in `PeakPicking.py`: "The evaluation helpers rely on peak picking using MZMine parameters defined in `PeakPicking.py`"