tacular

tacular is a lookup library for the reference data every mass-spec/proteomics tool needs: amino acids, elements and isotopes, and post-translational modification ontologies (UNIMOD, PSI-MOD, RESID, XLMOD, GNOme, UniProt-PTM). It has no runtime dependencies, so it's an easy way to add "what modification has a delta mass of X" or "what's the monoisotopic mass of alanine" to any Python project. It's also the shared data layer behind peptacular (ProForma peptide sequences) and paftacular (mzPAF fragment annotations).

Why tacular?

• Six PTM ontologies in one interface — UNIMOD, PSI-MOD, RESID, XLMOD, GNOme, and UniProt-PTM, all queryable by id, name, or approximate mass.
• Amino acid, element, ion-type, neutral-loss, protease, and mzPAF reference molecule lookups, through the same simple LOOKUP[key] interface.
• No runtime dependencies.
• Refreshable without reinstalling: data ships baked into the package, and the tacular update CLI can pull the latest ontology release into a per-user cache on demand.
• Typed (py.typed) dataclasses for every entry.

Install

pip install tacular

Quick example

import tacular as t

# Look up amino acids and elements by code or name
alanine = t.AA_LOOKUP["A"]
print(alanine.monoisotopic_mass)  # 71.0371137851

carbon_13 = t.ELEMENT_LOOKUP["13C"]
print(carbon_13.mass)  # 13.00335483507

# Identify a modification from an observed mass shift
hits = t.UNIMOD_LOOKUP.query_mass(79.9663, tolerance=0.001)
print(hits[0].name)  # Phospho
print([m.name for m in t.UNIMOD_LOOKUP.query_mass(79.9663, tolerance=10, tolerance_unit="ppm")])  # ['Phospho']

# Mass tolerance helpers (units are "da" or "ppm")
print(round(t.ppm_error(1000.01, 1000.0), 6))  # 10.0
print(t.within_tolerance(1000.005, 1000.0, 10, tolerance_unit="ppm"))  # True

Every lookup has the same interface: LOOKUP[key], .get(key, default), in, len, .keys(), .values() and .items(). A miss raises tacular.TacularKeyError, which is both a KeyError and a ValueError. Physical constants such as PROTON_MASS are in tacular.constants.

What else it can do

• Query PSI-MOD, RESID, XLMOD, GNOme, and UniProt-PTM the same way as UNIMOD above.

• Convert and compare mass errors: ppm_error, da_to_ppm, ppm_to_da, tolerance_window and within_tolerance (tacular.tolerance).

• Isobaric tags and SILAC labels: t.ISOBARIC_TAG_LOOKUP["TMT10"].reporter_mzs, t.SILAC_LOOKUP.get_set("heavy"), with UNIMOD ids and masses computed from the element table.

• Look up fragment ion types, common neutral losses, mzPAF reference molecules, and protease cleavage patterns.

• Refresh any ontology to its latest upstream release without reinstalling:

  tacular update                 # refresh all six ontologies (includes GNOme, a ~129 MB download)
  tacular update unimod xlmod    # refresh a subset (skips GNOme unless named)
  tacular status                 # show bundled vs. cached versions
  tacular clear                  # revert to the bundled data
  

  The refresh takes effect the first time a Python process uses that ontology (e.g. t.UNIMOD_LOOKUP); an ontology already loaded in a running process keeps its data. See the docs for the full CLI reference (including --offline, verbosity flags, and cache environment variables) and the complete lookup API.

Documentation

• Full docs: tacular.readthedocs.io
• Changelog: CHANGELOG.md
• Upgrading from 1.x: Migrating to 2.0 lists every renamed or removed name
• Architecture and contributing (also useful for AI coding agents): CLAUDE.md (AGENTS.md points here for tools that look for that filename instead)
• Data-generation pipeline (regenerating the bundled ontology snapshots): data_gen/README.md

Funding

Supported by NIH grants R01AG077046, R01MH132570, R01MH100175, R01HL165168 and U01AG088679.