# Mass Range Constraint Application

> Use when when generating a virtual chemical mixture for LC-MS/MS simulation, or when sampling molecular formulas from a metabolite database (such as HMDB), you need to restrict the sample to a specific m/z window that matches your instrument's acquisition range or your analytical focus.

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

---


# mass-range-constraint-application

## Summary

Apply mass-to-charge (m/z) range constraints to filter chemical formulas or compounds from metabolomics databases or samplers. This skill ensures that only molecules within a specified mass window are considered for simulation or analysis, which is essential for focusing acquisition strategies on the target mass range of the instrument.

## When to use

When generating a virtual chemical mixture for LC-MS/MS simulation, or when sampling molecular formulas from a metabolite database (such as HMDB), you need to restrict the sample to a specific m/z window that matches your instrument's acquisition range or your analytical focus. This is particularly important before instantiating a formula sampler or creating chemical objects to avoid processing irrelevant out-of-range molecules.

## When NOT to use

- Input is already a pre-filtered chemical mixture or mzML file with specific m/z data — re-filtering may lose or corrupt existing intensity/RT metadata.
- The analytical goal requires exploring the full mass range or comparing across multiple non-overlapping windows — applying a single fixed range would exclude relevant molecules.
- Database or formula sampler does not expose m/z filtering parameters — use alternative filtering steps (e.g., post-hoc filtering on computed m/z values) instead.

## Inputs

- HMDB database (pickle or zip file with metabolite records)
- Formula sampler configuration (min_mz, max_mz parameters)
- Raw molecular formula collection or metabolite list

## Outputs

- Filtered set of unique molecular formulas within the m/z range
- Count or metadata of molecules passing the mass constraint
- Chemical objects or mixture ready for downstream simulation

## How to apply

Specify the `min_mz` and `max_mz` parameters when instantiating a formula sampler (e.g., `DatabaseFormulaSampler` or `UniformMZFormulaSampler`) or when loading chemical mixtures. For example, set `min_mz=100` and `max_mz=1000` to restrict to that window. The sampler's internal filtering logic will apply these bounds and return only unique molecular formulas that fall within the specified m/z range. After instantiation, execute the sampler and count or validate the filtered result to confirm the expected number of molecules pass the constraint (as in task_004, which verified 73,822 unique formulas in the 100–1000 m/z range for HMDB).

## Related tools

- **VIMMS** (Hosts and executes DatabaseFormulaSampler and UniformMZFormulaSampler classes that accept and apply m/z range constraints during chemical mixture generation) — https://github.com/glasgowcompbio/vimms
- **HMDB** (Source metabolite database that is loaded and filtered by m/z range constraints to generate virtual chemical objects)
- **Python** (Programming environment in which m/z constraint parameters are specified and sampler methods are invoked)

## Examples

```
from vimms.ChemicalMixtureCreator import ChemicalMixtureCreator
from vimms.VimsController import DatabaseFormulaSampler
sampler = DatabaseFormulaSampler(hmdb, min_mz=100, max_mz=1000)
cmc = ChemicalMixtureCreator(sampler)
chemicals = cmc.sample(100, ms_levels=2)
```

## Evaluation signals

- The count of unique filtered formulas matches the expected or reported count (e.g., 73,822 for HMDB at m/z 100–1000).
- All formulas in the filtered output have m/z values strictly within [min_mz, max_mz]; spot-check by computing or inspecting representative formula monoisotopic masses.
- No out-of-range formulas appear in the sampled chemical objects when displayed or logged during instantiation.
- Downstream simulation (e.g., Environment.run()) processes only chemicals within the constrained range, verifiable via scan metadata or ms1_mz fields.
- Reducing min_mz or max_mz yields proportionally fewer filtered molecules; expanding the range yields more (monotonic behavior).

## Limitations

- The m/z filtering is performed at instantiation time; changing the range requires re-instantiation of the sampler.
- Database accuracy depends on the underlying chemical formula accuracy in HMDB or other source — incorrect or missing formulas in the database will not be corrected by this filter.
- Very tight m/z windows (e.g., <100 Da) may yield very few or no molecules, limiting statistical power in downstream simulation.
- The filter applies to neutral mass formulas; actual observed m/z depends on ionization mode (positive/negative) and adducts, which are not accounted for by the range constraint alone.

## Evidence

- [results] DatabaseFormulaSampler(hmdb, min_mz=100, max_mz=1000): "Create database formula sampler with m/z range 100-1000"
- [other] The DatabaseFormulaSampler successfully filters the HMDB database and reports 73,822 unique formulas when applied to chemical formulae in the m/z range 100–1000.: "finding from task_004 demonstrating validation of m/z-constrained filtering"
- [other] formula_sampler = UniformMZFormulaSampler(min_mz=100, max_mz=600): "# 1. Generate chemicals
formula_sampler = UniformMZFormulaSampler(min_mz=100, max_mz=600)"
- [intro] a flexible and modular framework designed to simulate fragmentation strategies in tandem mass spectrometry-based metabolomics: "VIMMS provides a framework to simulate fragmentation strategies in tandem mass spectrometry-based metabolomics"
- [results] chemical objects are generated by sampling from metabolites in the HMDB database: "Generate chemical objects by sampling from metabolites in HMDB database"