A lightweight Python package for accurate mass (m/z)-based screening of plant metabolomics data against curated compound libraries using configurable parts-per-million (ppm) tolerance.
Designed for LC–MS and HRMS metabolomics workflows, the package provides a reusable command-line interface (CLI) and Python API for rapid putative metabolite identification while supporting flexible input formats from different mass spectrometry software.
High-resolution LC–MS metabolomics experiments routinely generate hundreds or thousands of detected features that require preliminary annotation against curated compound libraries.
Although this process is conceptually straightforward, it is often repeated using project-specific scripts that are difficult to maintain, reuse, or adapt to different datasets.
Plant Metabolite Identifier was developed to provide a lightweight, reusable, and extensible Python package that automates accurate mass (m/z) screening while remaining flexible enough to accommodate feature tables exported from different mass spectrometry platforms.
The package is intended for putative metabolite identification during the early stages of metabolomics analysis before confirmation using retention time (RT), MS/MS fragmentation, or authentic standards.
LC–MS Feature Table (.csv)
│
▼
Read Feature Table
│
▼
Reference Compound Library (.csv)
│
▼
Calculate ppm Error
│
▼
Filter Within ppm Tolerance
│
▼
Rank Candidate Matches
│
▼
detected_matches.csv
- Accurate mass (m/z) screening using configurable ppm tolerance
- Flexible CSV column mapping for compatibility with multiple MS software exports
- Command-line interface (CLI)
- Python API for integration into existing workflows
- Candidate ranking based on proximity to zero ppm error
- Lightweight implementation with minimal dependencies
The package:
- Reads a feature table exported from an LC–MS workflow.
- Reads a curated compound library.
- Calculates ppm error between every detected feature and reference compound.
- Retains compounds within the specified ppm tolerance.
- Sorts candidate matches by absolute ppm error.
- Exports a candidate identification table for downstream interpretation.
This package performs putative metabolite identification based on accurate mass only.
Final metabolite confirmation should include additional evidence such as:
- Retention time (RT)
- MS/MS fragmentation
- Authentic reference standards
- Isotope pattern evaluation
For every detected feature:
- Read the observed m/z.
- Compare against every compound in the reference library.
- Calculate the signed ppm error.
- Retain compounds within the selected ppm tolerance.
- Rank candidate matches by absolute ppm error.
- Export the ranked candidate list.
Mass spectrometers measure ions with small measurement errors.
Rather than comparing absolute m/z differences, metabolomics workflows typically use parts-per-million (ppm) because the acceptable error scales with ion mass and instrument accuracy.
Using ppm allows consistent matching across compounds of different molecular weights while remaining compatible with high-resolution mass spectrometry workflows.
plants_metabolite_identifier/
│
├── src/
│ └── pmidentifier/
│ ├── __init__.py
│ ├── __main__.py
│ ├── utils.py
│ ├── mz_matching.py
│ └── pipeline.py
│
├── data/
│
├── README.md
└── pyproject.toml
- Python
- Pandas
- Command Line Interface (CLI)
Clone the repository
git clone https://github.com/noankomah/plant_metabolite_identifier.git
cd plant_metabolite_identifierInstall the package
pip install -e .Dependencies
- pandas
plantmetor
plantmet \
--features FEATURES \
--library LIBRARY \
--out OUTPUT \
--ppm 10 \
--mode positiveExample
plantmet \
--features features.csv \
--library compounds.csv \
--out detected_matches.csv \
--ppm 10 \
--mode positiveThe package can also be integrated directly into Python workflows.
from pmidentifier.pipeline import run_mz_screening
run_mz_screening(
features_csv="features.csv",
library_csv="library.csv",
output_csv="detected_matches.csv",
ppm_tolerance=10.0,
mode="positive"
)Feature tables exported from different software often use different column names.
These can be mapped explicitly.
run_mz_screening(
features_csv="features.csv",
library_csv="library.csv",
output_csv="results.csv",
id_col="name",
mz_col="mzmed",
rt_col="rtmed",
compound_col="Compound",
theo_mz_col="Theo_mz",
adduct_col="Adduct"
)The package requires two CSV files.
Minimum required columns
- Feature ID
- Observed m/z
Optional
- Retention Time
Example
feature_id,mz,rt
F1,300.1234,5.20
F2,315.0987,6.10Minimum required columns
- Compound Name
- Theoretical m/z
- Adduct
Example
compound_name,adduct,theoretical_mz
Quinine,[M+H]+,325.1910
Cryptolepine,[M+H]+,233.1073The generated CSV contains one row for every candidate match.
Output columns include
- feature_id
- mz
- rt
- compound_name
- adduct
- theoretical_mz
- ppm_error
Candidate matches are ranked by absolute ppm error, allowing the closest matches to appear first.
Plant Metabolite Identifier can be used for
- Plant metabolomics
- Natural product screening
- Preliminary metabolite annotation
- Compound library screening
- High-resolution LC–MS workflows
- Research data preprocessing
- Default tolerance is 10 ppm, suitable for HRMS workflows.
- A single feature may produce multiple candidate matches.
- Results represent putative identifications only.
- Confirmation should include RT and/or MS/MS information.
Current
- ✅ Accurate mass (m/z) matching
- ✅ Flexible CSV column mapping
- ✅ Command-line interface
- ✅ Python API
Planned
- ⬜ Retention time filtering
- ⬜ Best-hit selection
- ⬜ Confidence scoring
- ⬜ Isotope pattern evaluation
- ⬜ MS/MS integration
- ⬜ GNPS compatibility
Contributions, feature suggestions, and bug reports are welcome.
Future improvements should prioritize maintaining lightweight performance while extending metabolomics functionality.
MIT License