psimodpy

psimodpy wraps the PSI-MOD protein modification ontology in a typed Python API, so proteomics tooling can look up modifications by ID, name, mass, or amino acid without writing an OBO parser or re-deriving elemental formulas by hand. It ships with the full ontology bundled in, so it works fully offline.

Highlights

• Bundled, offline data — 2,116 PSI-MOD 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, MOD:NNNNN accession, exact name, free-text search, amino-acid origin, or ontology parent/child relationships
• 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 with clickable parent/child links, no install required
• Optional local FastAPI + MCP server (pip install psimodpy[server]) to expose the database over HTTP or to LLM tools

Install

pip install psimodpy

Or with uv:

uv add psimodpy

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

Quick Example

import psimodpy

db = psimodpy.load()          # bundled PSI-MOD database, no download needed
print(len(db))                # 2116

# Lookup by numeric ID or "MOD:NNNNN" accession
entry = db[46]
print(entry.name)             # O-phospho-L-serine
print(entry.origin)           # S
print(entry.diff_mono)        # 79.966331
print(entry.dict_composition)  # {'H': 1, 'O': 3, 'P': 1}
print(entry.proforma_formula)   # HO3P

# Lookup by exact name (case-insensitive)
same_entry = db.get_by_name("O-phospho-L-serine")

# Full-text search across names, definitions, and synonyms
hits = db.search("phospho")
print(len(hits))              # 99

# Every modification known to occur on a given amino acid
ser_mods = db.get_by_origin("S")
print(len(ser_mods))          # 154

# Entries whose monoisotopic mass difference is within 0.01 Da of 79.966, on S, T or Y
for entry, error in db.search_mass(79.966, site="STY")[:3]:
    print(entry.name, round(error, 4))   # O-phospho-L-serine -0.0003 ...
db.search_mass(42.010565, site="A", position="protein n-term")  # [(N-acetyl-L-alanine, ~0.0)]

More

# Filter obsolete or non-slim terms
slim = db.filter(slim_only=True, include_obsolete=False)

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

# Round-trip back to PSI-MOD OBO format
db.write_obo("out/psi-mod.obo")
db2 = psimodpy.parse_obo("out/psi-mod.obo")  # identical entry count and fields

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

claude mcp add psi-mod http://localhost:8000/mcp --transport http

See CHANGELOG.md for release history.

Data Source

Term data comes from the HUPO-PSI PSI-MOD controlled vocabulary, maintained by the HUPO Proteomics Standards Initiative. See that repository for the ontology's own license and citation guidance.

Related Projects

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

Citation

If psimodpy 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