# Ms1 Spectrum Simulation

> Use when when you need to generate synthetic LC-MS/MS data to test fragmentation strategies, validate acquisition controllers, or benchmark peak-picking and spectral matching algorithms before deployment on real mass spectrometers.

- Skill: `holobiomicslab/ms1-spectrum-simulation` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/ms1-spectrum-simulation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/ms1-spectrum-simulation/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/ms1-spectrum-simulation

---


# ms1-spectrum-simulation

## Summary

Simulate realistic full-scan MS1 spectra from chemically diverse samples by applying a mass spectrometer controller to a virtual LC-MS environment. This skill enables prototyping and evaluation of MS acquisition strategies without access to real instrumentation.

## When to use

When you need to generate synthetic LC-MS/MS data to test fragmentation strategies, validate acquisition controllers, or benchmark peak-picking and spectral matching algorithms before deployment on real mass spectrometers. Use this skill when you have a defined set of chemical formulas or mixtures and want to see how they ionize and fragment under specified polarity and scan modes.

## When NOT to use

- You already have real LC-MS/MS data and want to replay it with different fragmentation strategies (use replay/re-acquisition workflows instead).
- You need tandem MS/MS fragmentation spectra; this skill generates MS1 only (set ms_levels > 1 and use a tandem controller for MS/MS).
- Your chemical set is very small (< 10 compounds) and you need microsecond-level scan-timing fidelity; virtual simulation trades hardware realism for flexibility.

## Inputs

- Chemical formula list or HMDB database connection
- Polarity specification (positive or negative)
- Retention time range (min_rt, max_rt in minutes)
- m/z range for chemical sampling (e.g., 100–1000)

## Outputs

- mzML format LC-MS/MS data file
- Simulated MS1 scan collection with m/z, intensity, and retention time
- Peak-picked features table (optional, via MZMine integration)

## How to apply

Initialize a DatabaseFormulaSampler to retrieve chemical formulas (e.g., from HMDB within m/z 100–1000); create a ChemicalMixtureCreator with ms_levels=1 to specify MS1-only acquisition. Configure an IndependentMassSpectrometer with your selected polarity (positive or negative) and attach a FullScanController to define the fragmentation strategy. Instantiate an Environment with the mass spectrometer, controller, and retention time range (e.g., min_rt=0, max_rt=1440). Execute env.run() to simulate the full LC-MS acquisition, then export the scans to mzML format using Environment.write_mzML(). Verify the output contains realistic peak intensities and isotope patterns by examining peak-picking results against MZMine parameters.

## Related tools

- **ViMMS** (Core simulation framework providing virtual mass spectrometer, controller, and environment for LC-MS/MS scan-level acquisition prototyping) — https://github.com/glasgowcompbio/vimms
- **DatabaseFormulaSampler** (Retrieves and samples chemical formulas from HMDB or other databases within specified m/z ranges to generate realistic chemical mixtures) — https://github.com/glasgowcompbio/vimms
- **ChemicalMixtureCreator** (Constructs chemical mixtures and specifies MS levels (MS1 only vs tandem MS/MS) for simulation) — https://github.com/glasgowcompbio/vimms
- **IndependentMassSpectrometer** (Instantiates a virtual mass spectrometer with specified polarity and ionization parameters) — https://github.com/glasgowcompbio/vimms
- **FullScanController** (Defines the fragmentation strategy and acquisition mode (MS1-only full-scan in this skill)) — https://github.com/glasgowcompbio/vimms
- **MZMine** (Performs peak picking and feature detection on simulated mzML output using defined intensity thresholds and m/z ranges)

## Examples

```
from vimms.ChemicalMixtureCreator import ChemicalMixtureCreator
from vimms.MassSpectrometer import IndependentMassSpectrometer
from vimms.Controller import FullScanController
from vimms.Environment import Environment
from vimms.Sampler import DatabaseFormulaSampler
mix = DatabaseFormulaSampler().sample(100, 1000)
ms = IndependentMassSpectrometer(ms_mode='positive', chemicals=mix.chemicals)
env = Environment(ms, FullScanController(), min_rt=0, max_rt=1440)
env.run()
env.write_mzML('output.mzML')
```

## Evaluation signals

- The output mzML file contains valid scans with non-zero intensity arrays and retention time metadata.
- Peak-picked features match the input chemical set size (73,822 unique formulas → ~73k peaks, allowing for ionization efficiency and dynamic range losses).
- Minimum intensity threshold (at_least_one_point_above=1.75E5) is satisfied for detected ROIs in the output.
- m/z range of detected peaks falls within the specified m/z window (e.g., 100–1000); no peaks outside this window.
- Isotope patterns and relative intensities are realistic (e.g., 13C isotopomer ~1% relative intensity for singly charged ions).

## Limitations

- Simulation assumes independent ionization of chemicals; does not model ion suppression or competitive ionization in complex mixtures.
- Virtual MS1 spectra depend on the underlying chemical database and ionization model; HMDB coverage is limited to known metabolites and does not include novel or modified compounds.
- Retention time prediction uses a simple model (linear or fixed rt per chemical); real LC chromatography is more complex and compound-dependent.
- No simulation of instrument artifacts (e.g., electronic noise, detector saturation, or scan-to-scan jitter) unless explicitly implemented in the IndependentMassSpectrometer.
- Peak matching to spectral libraries (e.g., GNPS-NIST14) requires additional matching threshold filtering (0.0–1.0 cosine similarity) outside this skill.

## Evidence

- [other] A DatabaseFormulaSampler successfully sampled 73,822 unique formulas from the HMDB database within the m/z range 100–1000, enabling generation of realistic chemical mixtures for MS1-only simulation.: "DatabaseFormulaSampler successfully sampled 73,822 unique formulas from the HMDB database within the m/z range 100–1000"
- [other] Use ChemicalMixtureCreator to generate a chemical mixture with ms_levels=1 (MS1 only). Instantiate IndependentMassSpectrometer with the generated chemicals in positive or negative polarity. Configure FullScanController as the fragmentation strategy.: "Use ChemicalMixtureCreator to generate a chemical mixture with ms_levels=1 (MS1 only). Instantiate IndependentMassSpectrometer with the generated chemicals in positive or negative polarity. Configure"
- [other] Create an Environment instance with the mass spectrometer, controller, and retention time range (e.g., min_rt=0, max_rt=1440). Execute env.run() to simulate the LC-MS acquisition process. Write the resulting scans to mzML format.: "Create an Environment instance with the mass spectrometer, controller, and retention time range (e.g., min_rt=0, max_rt=1440). Execute env.run() to simulate the LC-MS acquisition process. Write the"
- [readme] ViMMS, a flexible and modular framework designed to simulate fragmentation strategies in tandem mass spectrometry-based metabolomics.: "a flexible and modular framework designed to simulate fragmentation strategies in tandem mass spectrometry-based metabolomics"
- [other] The evaluation helpers rely on peak picking using MZMine parameters defined in PeakPicking.py. Minimum intensity threshold for ROI extraction at_least_one_point_above=min_ms1_intensity with default value 1.75E5.: "The evaluation helpers rely on peak picking using MZMine parameters. at_least_one_point_above=min_ms1_intensity with default value 1.75E5"