Chemical Formula Extraction And Filtering

chemical-formula-extraction-and-filtering

Summary

Extract and filter chemical molecular formulas from a metabolite database (HMDB) by applying mass-to-charge ratio (m/z) range and MS level constraints, then deduplicate to obtain a curated set of unique formulas suitable for metabolomics simulation or sampling.

When to use

When you have a loaded metabolite database (e.g., hmdb_compounds.p pickle file) and need to constrain the chemical space to a specific instrumental m/z range (e.g., 100–1000 Da) and MS acquisition level before running virtual mass spectrometry simulations or designing data-dependent acquisition strategies.

When NOT to use

• Input database is already formatted as a deduplicated feature table or matrix; use direct indexing instead.
• m/z range is instrument-independent (e.g., you are performing untargeted discovery across all accessible masses); applying a fixed range will discard relevant chemistry.
• Database records lack explicit ms_levels field or are not in pickle format; verify schema compatibility first.

Inputs

• HMDB compounds database (Python pickle file: hmdb_compounds.p)
• m/z range bounds (min_mz, max_mz as floats or integers)
• MS level filter specification (ms_levels integer or list)

Outputs

• Filtered, deduplicated set of unique molecular formulas
• Count of unique molecular formulas
• Summary report (e.g., JSON, CSV, or log file with filter statistics)

How to apply

Load the HMDB compounds database using Python pickle deserialization. Apply a minimum m/z filter (min_mz=100) and maximum m/z filter (max_mz=1000) to retain only formulas whose monoisotopic mass falls within the instrumental range. Filter to retain only MS level 1 (MS1) compounds by selecting records with ms_levels=1, eliminating fragmentation-only entries. Deduplicate the filtered result set to obtain unique molecular formula entries. Count the total unique formulas and record in a summary report. The rationale is to ensure the virtual environment samples only from chemically plausible, instrument-accessible molecules.

Related tools

• ViMMS (Virtual Metabolomics Mass Spectrometer) (Framework that uses the DatabaseFormulaSampler to load and filter HMDB formulas for chemical sampling in tandem MS simulation and DDA strategy prototyping) — https://github.com/glasgowcompbio/vimms
• Python pickle (Standard library for deserializing the hmdb_compounds.p database file into Python objects)

Examples

from vimms.ChemicalSamplers import DatabaseFormulaSampler; import pickle; db = pickle.load(open('hmdb_compounds.p', 'rb')); sampler = DatabaseFormulaSampler(db, min_mz=100, max_mz=1000, ms_level=1); unique_formulas = set(sampler.formulas); print(f'Unique formulas: {len(unique_formulas)}')

Evaluation signals

• Returned count of unique formulas matches expected cardinality for the m/z range (e.g., 73,822 for m/z 100–1000 in HMDB); verify against a manually spot-checked subset or prior runs.
• No duplicate formulas in the deduplicated output; perform set cardinality check: len(unique_formulas) == len(set(unique_formulas)).
• All retained formulas have m/z values strictly within [min_mz, max_mz] bounds; sample formulas and verify min(mz_values) >= 100 and max(mz_values) <= 1000.
• All retained formulas have ms_levels == 1; verify that any formula with ms_levels > 1 or ms_levels == 0 was filtered out.
• Summary report contains filter step metadata (input record count, pre-filter count, post-filter count, deduplication count, final count) to audit data loss at each stage.

Limitations

• HMDB pickle format is version-dependent; schema changes between HMDB releases may require field name updates (e.g., ms_levels vs. msn_level).
• The m/z filter assumes monoisotopic mass; isotope-resolved or adduct-specific m/z (e.g., [M+H]+, [M+Na]+) is not explicitly handled in this workflow and may require post-filtering.
• Deduplication is performed on the formula string only, not on the full chemical structure; isomers with identical molecular formula will collapse to a single entry.
• Performance scales linearly with database size; for very large databases (> 1M compounds), consider chunking or lazy loading to avoid memory exhaustion.

Evidence

• [other] When the DatabaseFormulaSampler filters the HMDB database for formulas with m/z between 100 and 1000, it yields 73822 unique molecular formulas.: "When the DatabaseFormulaSampler filters the HMDB database for formulas with m/z between 100 and 1000, it yields 73822 unique molecular formulas."
• [other] 1. Load the HMDB compounds database (hmdb_compounds.p) using Python pickle. 2. Apply m/z range filter (min_mz=100, max_mz=1000) to retain only formulas within the specified range. 3. Filter to retain only MS level 1 compounds by selecting those with ms_levels=1. 4. De-duplicate the filtered formula set to obtain unique molecular formula entries. 5. Count the total number of unique formulas and record in a summary report.: "Load the HMDB compounds database (hmdb_compounds.p) using Python pickle. Apply m/z range filter (min_mz=100, max_mz=1000) to retain only formulas within the specified range."
• [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"
• [intro] 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"
• [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"