🧬 molidmapper

Map & merge molecular identifiers across public databases.

---

Why This Exists

Molecular biology datasets often use different identifier systems — PubChem CIDs, ChEMBL IDs, DrugBank IDs, gene symbols, UniProt accessions — making integration tedious. molidmapper provides a fast, well-tested CLI and Python API to merge datasets by identifier, detect identifier types, and report coverage statistics.

What It Does

• Heuristically detect identifier types (PubChem CID, ChEMBL ID, DrugBank ID, InChIKey, gene symbol, UniProt ID)
• Merge CSV files by identifier columns with configurable join keys
• Report coverage statistics and mapping results in markdown
• Normalize identifiers for consistent matching

Installation

Requires Python ≥ 3.10.

# From source (recommended for now)
git clone https://github.com/SaveenaSolanki/molidmapper.git
cd molidmapper
pip install -e ".[dev]"

PyPI release is planned. For now, install from source.

conda / mamba

conda env create -f environment.yml
conda activate molidmapper

CLI Usage

# Show help
molid-map --help

# Map identifiers
molid-map map-ids \
    --input compounds.csv \
    --mapping pubchem_names.csv \
    --out results/mapped.csv \
    --report results/report.md

# Custom join columns
molid-map map-ids \
    -i input.csv -m mapping.csv \
    -o out.csv \
    --left-on chembl_id --right-on chembl_id

Python API

from molidmapper.core import detect_id_type, merge_mappings, compute_coverage
from molidmapper.io import read_input_csv, read_mapping_csv

# Detect identifier type
print(detect_id_type("CHEMBL25"))     # chembl_id
print(detect_id_type("2244"))         # pubchem_cid
print(detect_id_type("EGFR"))         # gene_symbol

# Merge datasets
input_df = read_input_csv("compounds.csv")
mapping_df = read_mapping_csv("pubchem_names.csv")
merged = merge_mappings(input_df, mapping_df,
                        left_on="pubchem_cid",
                        right_on="pubchem_cid")

# Check coverage
stats = compute_coverage(merged, ["pubchem_cid", "chembl_id", "gene_symbol"])
for col, s in stats.items():
    print(f"{col}: {s['pct_filled']}%")

Example

Input (examples/demo_input.csv)

compound_id	pubchem_cid	chembl_id	gene_symbol
C1	2244
C2		CHEMBL25	PTGS2
C3	3672		EGFR
C4
C5	1983

Mapping (examples/demo_mapping.csv)

pubchem_cid	standard_name	target_class
2244	Aspirin	NSAID
3672	Ibuprofen	NSAID
1983	Acetaminophen	Analgesic

Run demo

bash examples/run_demo.sh

Outputs a merged CSV with standard_name and target_class joined for C1, C3, C5, plus a markdown report with coverage stats.

Development

# Run tests
pytest

# With coverage
pytest --cov=molidmapper --cov-report=html

# Lint
ruff check src/ tests/

Data & Privacy

This repository contains generic utility code and toy/public-data examples only — no unpublished datasets, internal lab data, trained models, or confidential project assets. All processing is local.

License

MIT — part of the CompBio Toolkit Suite.