# Hmdb Formula Sampling

> Use when when you need to create in silico LC-MS/MS experiments with diverse chemical backgrounds for testing fragmentation strategies or acquisition controllers, and you want the chemical diversity to reflect real metabolomic samples. Use this when you have a target m/z range (e.

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

---


# HMDB Formula Sampling

## Summary

Sample diverse molecular formulas from the Human Metabolome Database (HMDB) within a specified m/z range to generate chemically realistic mixtures for LC-MS simulation. This skill enables rapid prototyping of MS acquisition strategies on representative chemical backgrounds without requiring real samples.

## When to use

When you need to create in silico LC-MS/MS experiments with diverse chemical backgrounds for testing fragmentation strategies or acquisition controllers, and you want the chemical diversity to reflect real metabolomic samples. Use this when you have a target m/z range (e.g., 100–1000) and want to ensure your simulated experiment includes realistic chemical complexity before validating on real instruments.

## When NOT to use

- When you need targeted analysis of specific metabolites (e.g., known disease biomarkers); HMDB sampling produces unbiased chemical diversity, not a curated set.
- When you require only a small, highly curated chemical background; HMDB sampling returns tens of thousands of formulas, which may add unnecessary computational overhead for simple validation studies.
- When you need to match a specific real sample's chemical composition; sampling from HMDB does not preserve the actual relative abundances or co-occurrence patterns of a measured sample.

## Inputs

- m/z range boundaries (min_mz, max_mz as floats)
- HMDB database access (local or remote)
- DatabaseFormulaSampler instance (ViMMS)

## Outputs

- List of sampled molecular formulas (unique, stratified across m/z range)
- Chemical mixture object (ChemicalMixtureCreator output)
- Chemical objects compatible with IndependentMassSpectrometer

## How to apply

Initialize a DatabaseFormulaSampler configured to retrieve molecular formulas from the HMDB database, specifying your m/z range boundaries (e.g., min_mz=100, max_mz=1000). The sampler will return a large set of unique molecular formulas stratified across that range. Pass these formulas to a ChemicalMixtureCreator with ms_levels=1 to generate MS1-only chemical mixtures, then feed the resulting Chemical objects into an IndependentMassSpectrometer instance (configured for your desired ionization polarity). The sampler successfully retrieved 73,822 unique HMDB formulas in the 100–1000 m/z range in the source study, providing sufficient chemical diversity for realistic full-scan simulations. Success is confirmed when the returned formula set spans the requested m/z range without gaps and the resulting chemical mixture can be instantiated without schema errors.

## Related tools

- **ViMMS (Virtual Metabolomics Mass Spectrometer)** (Framework providing DatabaseFormulaSampler, ChemicalMixtureCreator, IndependentMassSpectrometer, and Environment classes for chemical generation and LC-MS simulation) — https://github.com/glasgowcompbio/vimms
- **HMDB (Human Metabolome Database)** (Source database of molecular formulas and compound metadata used by DatabaseFormulaSampler)

## Examples

```
from vimms.ChemicalSampler import DatabaseFormulaSampler; sampler = DatabaseFormulaSampler(min_mz=100, max_mz=1000); formulas = sampler.sample()
```

## Evaluation signals

- Number of unique formulas returned matches expected cardinality (~73,822 for m/z 100–1000)
- All sampled formulas fall within the specified m/z bounds (min_mz ≤ each formula m/z ≤ max_mz)
- No duplicate formulas in the returned set
- ChemicalMixtureCreator successfully instantiates with sampled formulas without schema or type errors
- Resulting Chemical objects are compatible with IndependentMassSpectrometer (match expected attribute schema)

## Limitations

- HMDB sampling is unbiased and does not reflect the actual relative abundances or co-occurrence patterns observed in real biological samples, potentially resulting in artificial peak patterns.
- The diversity and size of the sampled set depends on HMDB database version and maintenance status; outdated or incomplete HMDB snapshots may yield fewer formulas or miss recently discovered metabolites.
- Sampling is performed at the formula level only; no structural stereoisomers or ionization adducts are distinguished during sampling, which may under-represent the true chromatographic and MS complexity of real samples.

## 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.: "A DatabaseFormulaSampler successfully sampled 73,822 unique formulas from the HMDB database within the m/z range 100–1000"
- [other] Chemicals can be sampled from databases such as HMDB or from specific distributions: "Chemicals can be sampled from databases such as HMDB or from specific distributions"
- [other] Initialize a DatabaseFormulaSampler to retrieve chemical formulas from the HMDB database.: "Initialize a DatabaseFormulaSampler to retrieve chemical formulas from the HMDB database"
- [other] Use ChemicalMixtureCreator to generate a chemical mixture with ms_levels=1 (MS1 only).: "Use ChemicalMixtureCreator to generate a chemical mixture with ms_levels=1 (MS1 only)"
- [results] hmdb_compounds.p - Human Metabolome Database metabolite database extracted for simulation: "Human Metabolome Database metabolite database extracted for simulation"