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"