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

TSV/CSV columns

write_tsv writes one row per entry with the following columns, in this order. Missing values are empty cells. Multi-valued cells use "; " between values, independently of whether the file delimiter is a tab or comma.

Column	Contents
id	Accession in UNIMOD:N form.
name	Modification name.
definition	Modification definition.
synonyms	Synonyms joined with "; ".
comment	Free-text comment.
record_id	Numeric UNIMOD record ID.
delta_mono_mass	Monoisotopic mass difference in Da.
delta_avge_mass	Average mass difference in Da.
delta_composition	UNIMOD's elemental-composition string.
username_of_poster	Submitter username.
group_of_poster	Submitter group.
date_time_posted	Submission timestamp as YYYY-MM-DD HH:MM:SS.
date_time_modified	Last modification timestamp in the same format.
approved	1 if approved, 0 if not, or empty if unspecified.
is_a	Parent accession in UNIMOD:N form.
specificities	Every site:position:classification triple, including hidden ones, joined with "; ".
specificities_hidden	One 1 (hidden) or 0 (visible) per specificity, in the same order, joined with "; ".

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

This starts a FastAPI app exposing the database as both a JSON REST API (GET /api/entries/{id}, /api/search, /api/entries/by-name/{name}, …) and an MCP endpoint at POST /mcp with get_by_id, get_by_name, and search tools, for pointing LLM clients directly at UNIMOD:

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

This is the beginning of the README. Read the rest at the original. Read the full README ↗