# Lc Ms Scan Acquisition Orchestration

> Use when when you have a curated list of chemical compounds (real or virtual), a defined fragmentation strategy (e.g., Top-N, exclusion lists), and need to simulate how that strategy will acquire MS1 and MS2 scans over a defined retention-time window.

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

---


# LC-MS Scan Acquisition Orchestration

## Summary

Orchestrate a complete tandem mass spectrometry (MS/MS) simulation control loop by coupling a virtual mass spectrometer, chemical library, and fragmentation strategy controller within an Environment instance. This skill enables rapid prototyping and evaluation of data-dependent acquisition (DDA) strategies before testing on real LC-MS/MS hardware.

## When to use

When you have a curated list of chemical compounds (real or virtual), a defined fragmentation strategy (e.g., Top-N, exclusion lists), and need to simulate how that strategy will acquire MS1 and MS2 scans over a defined retention-time window. Use this skill to generate synthetic mzML scan data and assess whether your controller and isolation parameters will achieve desired fragmentation coverage without access to physical instrumentation.

## When NOT to use

- You are testing acquisition directly on physical LC-MS/MS hardware (use this skill only for simulation prior to instrument time).
- Your chemical library is empty or contains no compounds in the target m/z range (filter and validate chemicals before orchestration).
- You need real-time instrument control or closed-loop feedback (VIMMS is a simulation framework, not a live instrument driver).

## Inputs

- Chemical compound list with m/z, intensity, and fragmentation properties (output of ChemicalMixtureCreator or ChemicalMixtureFromMZML)
- Fragmentation strategy parameters (isolation window, m/z tolerance, retention-time tolerance, MS1 intensity threshold, Top-N fragment count)
- Ionization mode (positive or negative polarity)

## Outputs

- Scans list containing MS1 and MS2 scan records with m/z, intensity, and fragmentation metadata
- mzML-formatted mass spectrometry data file (via write_mzML()) compatible with downstream peak picking and metabolite matching

## How to apply

Instantiate three core components: (1) Generate virtual chemicals by sampling m/z formulae (e.g., UniformMZFormulaSampler or DatabaseFormulaSampler for empirical HMDB data) across your target mass range, requesting both MS1 and MS2 levels via ChemicalMixtureCreator; (2) Create an IndependentMassSpectrometer instance in your desired polarity (positive or negative) with the chemical list; (3) Configure a Controller (e.g., TopNController) specifying fragmentation parameters: number of fragments per survey scan (N), isolation window width (typically 1 Da), m/z tolerance (e.g., 10 ppm), retention-time tolerance (e.g., 15 s), and MS1 intensity threshold (e.g., 1.75E5). (4) Construct an Environment spanning your desired retention-time range (e.g., 0–1440 s), attach both the mass spectrometer and controller, and invoke env.run() to execute the orchestrated acquisition loop. (5) Export the resulting scan list via write_mzML() and verify that both MS1 and MS2 scan records are present and non-empty.

## Related tools

- **ViMMS** (Core framework providing Environment, IndependentMassSpectrometer, and Controller classes for orchestrating the MS/MS acquisition loop and generating synthetic mzML scans) — https://github.com/glasgowcompbio/vimms
- **UniformMZFormulaSampler** (Chemical formula sampler for generating virtual compounds across a specified m/z range (e.g., 100–500 Da) without empirical data) — https://github.com/glasgowcompbio/vimms
- **DatabaseFormulaSampler** (Chemical formula sampler for generating compounds by sampling from metabolite databases (e.g., HMDB) within a specified m/z window) — https://github.com/glasgowcompbio/vimms
- **ChemicalMixtureCreator** (Utility to batch-generate chemical objects from formula samplers with specified MS levels (MS1, MS2)) — https://github.com/glasgowcompbio/vimms
- **TopNController** (Fragmentation strategy controller implementing data-dependent acquisition by selecting top N most abundant precursors for MS2 fragmentation) — https://github.com/glasgowcompbio/vimms
- **Environment** (Master orchestrator class that coordinates the mass spectrometer and controller over a retention-time window, executes the acquisition loop via env.run(), and exports mzML) — https://github.com/glasgowcompbio/vimms
- **OpenMS** (Post-processing tool to compute fragmentation coverage and validate acquisition results from mzML output)

## Examples

```
from vimms.Common import POSITIVE; from vimms.ChemicalSamplers import UniformMZFormulaSampler, ChemicalMixtureCreator; from vimms.MassSpectrometer import IndependentMassSpectrometer; from vimms.Controller import TopNController; from vimms.Environment import Environment; sampler = UniformMZFormulaSampler(min_mz=100, max_mz=500); cmc = ChemicalMixtureCreator(sampler); chemicals = cmc.sample(100, ms_levels=2); ms = IndependentMassSpectrometer(POSITIVE, chemicals); controller = TopNController(POSITIVE, N=3, isolation_width=1, mz_tol=10, rt_tol=15, min_ms1_intensity=1.75e5); env = Environment(ms, controller, min_time=0, max_time=1440); env.run(); env.write_mzML('output.mzML')
```

## Evaluation signals

- Scans list is non-empty and contains both MS1 and MS2 scan records (schema check).
- All MS1 scans have intensity above the configured threshold (e.g., 1.75E5); all MS2 scans are linked to valid MS1 precursors within m/z tolerance and retention-time window.
- MS2 count equals or approximates N × (number of survey scans), confirming the TopNController is fragmenting the expected number of precursors per cycle.
- mzML output file is valid and parseable by downstream tools (e.g., OpenMS peak picking, MZMine).
- Retention-time span of scans matches the configured Environment window (e.g., 0–1440 s with no gaps or out-of-range records).

## Limitations

- Simulation assumes perfect ionization and no ion suppression effects; intensity profiles are idealized and may not reflect real competitive ionization in complex mixtures.
- No chromatographic peak shape or retention-time variation; all chemical features are treated as point objects at fixed retention times.
- Controller logic is deterministic and does not model instrument variability, dead time, or queue-based scan scheduling delays observed in real hardware.
- Requires manual parameterization of isolation window, m/z tolerance, and intensity threshold; no automated optimization provided by the framework itself (optimization is performed via external comparison workflows).

## Evidence

- [other] The Environment class orchestrates three components: Chemicals are generated via samplers (e.g., DatabaseFormulaSampler), passed to an IndependentMassSpectrometer instance, and controlled by a fragmentation strategy Controller; the Environment runs this loop and produces a scan list via write_mzML output.: "The Environment class orchestrates three components: Chemicals are generated via samplers (e.g., DatabaseFormulaSampler), passed to an IndependentMassSpectrometer instance, and controlled by a"
- [readme] 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"
- [readme] 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] Generate 100 virtual chemicals by sampling m/z uniformly between 100–500 Da using UniformMZFormulaSampler and ChemicalMixtureCreator, requesting both MS1 and MS2 levels.: "Generate 100 virtual chemicals by sampling m/z uniformly between 100–500 Da using UniformMZFormulaSampler and ChemicalMixtureCreator, requesting both MS1 and MS2 levels."
- [other] Instantiate an IndependentMassSpectrometer in positive-ion mode with the generated chemical list.: "Instantiate an IndependentMassSpectrometer in positive-ion mode with the generated chemical list."
- [other] Configure a TopNController with N=3 fragments per survey scan, 1 Da isolation window, 10 ppm m/z tolerance, 15 s retention-time tolerance, and 1.75E5 minimum MS1 intensity threshold.: "Configure a TopNController with N=3 fragments per survey scan, 1 Da isolation window, 10 ppm m/z tolerance, 15 s retention-time tolerance, and 1.75E5 minimum MS1 intensity threshold."
- [other] Construct an Environment orchestrator spanning 0–1440 s, attach both the mass spectrometer and controller, and invoke env.run() to execute the fixed simulation control loop.: "Construct an Environment orchestrator spanning 0–1440 s, attach both the mass spectrometer and controller, and invoke env.run() to execute the fixed simulation control loop."
- [other] Verify the resulting scans list is non-empty and contains both MS1 and MS2 scan records.: "Verify the resulting scans list is non-empty and contains both MS1 and MS2 scan records."
- [other] The `Environment` class provides `write_mzML` to export the generated scans: "The `Environment` class provides `write_mzML` to export the generated scans"