unimodpy

unimodpy wraps the UNIMOD mass-spectrometry modifications database in a typed Python API, so proteomics tooling can look up modifications by ID, name, mass, or specificity without writing an OBO parser or re-deriving elemental formulas by hand. It ships with the full database bundled in, so it works fully offline.

Highlights

• Bundled, offline data — 1,561 UNIMOD terms shipped with the package; no network calls needed
• Zero core dependencies — pure Python, pip install and go
• Typed, immutable models with py.typed (PEP 561) for IDE autocomplete and static checking
• Rich lookups — by numeric ID, UNIMOD:N accession, exact name, or free-text search across names, definitions, and synonyms
• Full specificity data — site, position, and classification rules (with neutral losses) for every modification
• Formula and mass helpers computed for you (elemental composition dicts, ProForma-style formula strings)
• Round-trip export to TSV/CSV and back to OBO
• Online browser — search, sort, and inspect every term, no install required
• Optional local FastAPI + MCP server (pip install unimodpy[server]) to expose the database over HTTP or to LLM tools

Install

pip install unimodpy

Or with uv:

uv add unimodpy

Requires Python 3.12+. No third-party dependencies for the core package.

Quick Example

import unimodpy

db = unimodpy.load()          # bundled UNIMOD database, no download needed
print(len(db))                # 1561

# Lookup by integer ID, "UNIMOD:N" accession, or subscript
acetyl = db.get_by_id(1)
print(acetyl.id, acetyl.name, acetyl.delta_mono_mass, acetyl.proforma_formula)
# 1 Acetyl 42.010565 C2H2O

# Lookup by exact name (case-insensitive)
phospho = db.get_by_name("Phospho")

# Full-text search across name, definition, and synonyms
hits = db.search("glycosyl")
print(len(hits))              # 6

# Entries whose delta_mono_mass is within 0.01 Da of 79.966, on S, T or Y
for entry, error in db.search_mass(79.966, site="STY"):
    print(entry.name, round(error, 4))   # Phospho -0.0003, Sulfo 0.0092
db.search_mass(79.966331, tolerance=0.005)  # [(Phospho, ~0.0)]: Sulfo is 9.5 mDa away

# Per-site specificity rules (position, classification, neutral losses)
entry = db.get_by_name("Carbamidomethyl")
print(entry.dict_composition)       # {'H': 3, 'C': 2, 'N': 1, 'O': 1}
for spec in entry.specificities[:1]:
    print(spec.site, spec.position, spec.classification)
    # C Anywhere Chemical derivative

More

# Download the latest OBO and use it immediately
db = unimodpy.load(refresh=True)

# Or just download the file
path = unimodpy.download()                     # ~/.cache/unimodpy/UNIMOD.obo (reused if present)
path = unimodpy.download("/my/dir/UNIMOD.obo")  # custom destination
path = unimodpy.download(force=True)           # always re-download

# Write every entry to TSV (or CSV)
db.write_tsv("unimod.tsv")
db.write_tsv("unimod.csv", delimiter=",")

# Round-trip back to UNIMOD OBO format
db.write_obo("out/UNIMOD.obo")
db2 = unimodpy.parse_obo("out/UNIMOD.obo")  # identical entry count and fields

pip install unimodpy[server]
uvicorn unimodpy.server.app:app --reload

claude mcp add unimod http://localhost:8000/mcp --transport http

See CHANGELOG.md for release history.

Data Source

Term data comes from the UNIMOD protein modification database (Creasy & Cottrell, Proteomics 2004). See unimod.org for the database's own license and citation guidance.

Related Projects

Part of the tacular-omics family of proteomics PTM-vocabulary packages:

Citation

If unimodpy is useful in your research, please cite it — see CITATION.cff or use the "Cite this repository" button on GitHub. Releases are archived on Zenodo (DOI badge above).

License

MIT