# tacular

> Python library of lookups for MS-proteomics reference data: post-translational
> modification ontologies (UNIMOD, PSI-MOD, RESID, XLMOD, GNOme, UniProt-PTM),
> amino acids, elements/isotopes, fragment ion types, neutral losses, proteases,
> monosaccharides, and mzPAF reference molecules. No runtime dependencies.

Install with `pip install tacular` (Python >= 3.12). Each data type exposes a
module-level `*_LOOKUP` singleton (e.g. `tacular.UNIMOD_LOOKUP`,
`tacular.ELEMENT_LOOKUP`), queryable by id, name, or (for ontologies) approximate
mass: `import tacular as t; t.UNIMOD_LOOKUP["Phospho"].monoisotopic_mass`;
`t.UNIMOD_LOOKUP.query_mass(79.9663, tolerance=10, tolerance_unit="ppm")` (or `tolerance=0.001` in Da).
Tolerance helpers: `t.ppm_error(observed, theoretical)`, `t.da_to_ppm(delta, mz)`,
`t.ppm_to_da(delta_ppm, mz)`, `t.tolerance_window(mass, tol, *, tolerance_unit="da"|"ppm") -> (lo, hi)`,
`t.within_tolerance(observed, theoretical, tol, *, tolerance_unit=...)`.
Quantitative labels: `t.ISOBARIC_TAG_LOOKUP["TMT18"]` (TMT 0/2/6/10/11, TMTpro 0/16/18,
iTRAQ 4/8: `.channels`, `.reporter_mzs`, `.query_reporter("127N").mz`, `.unimod_id`) and
`t.SILAC_LOOKUP["Lys8"]` (Lys4/6/8, Arg6/10; `.get_set("light"|"medium"|"heavy")`).
Ontology data ships baked into the package and can be refreshed to the latest
upstream release without reinstalling via the `tacular update` CLI. Every error is a
`tacular.TacularError` (a `ValueError`); a lookup miss is `TacularKeyError` (also a
`KeyError`). Masses: `info.get_mass(monoisotopic=True)`; constants such as
`PROTON_MASS` are in `tacular.constants`.

tacular is the shared data layer for `peptacular` (ProForma peptides) and
`paftacular` (mzPAF fragment annotations). It does not depend on them, and they
are not authoritative for tacular's own mass data.

## Docs

- [llms-full.txt](https://raw.githubusercontent.com/tacular-omics/tacular/main/llms-full.txt): self-contained usage guide for agents: every public name with signature, examples, CLI, gotchas
- [README](https://github.com/tacular-omics/tacular/blob/main/README.md): installation, quick example, `tacular update` CLI
- [Quick start](https://tacular.readthedocs.io/en/latest/quickstart.html): tested examples for every lookup
- [Installation](https://tacular.readthedocs.io/en/latest/installation.html): install options
- [CHANGELOG](https://github.com/tacular-omics/tacular/blob/main/CHANGELOG.md): release notes
- [Migrating to 2.0](https://tacular.readthedocs.io/en/latest/migration.html): every renamed/removed 1.x name and its replacement

## API

- [API reference index](https://tacular.readthedocs.io/en/latest/api/index.html): Sphinx autodoc for all lookups
- [Modifications](https://tacular.readthedocs.io/en/latest/api/modifications.html): UNIMOD, PSI-MOD, RESID, XLMOD, GNOme, UniProt-PTM lookups
- [Elements](https://tacular.readthedocs.io/en/latest/api/elements.html): elements and isotopes, `parse_composition`
- [Amino acids](https://tacular.readthedocs.io/en/latest/api/amino_acids.html): `AA_LOOKUP`, `AminoAcid`
- [Base classes](https://tacular.readthedocs.io/en/latest/api/base_classes.html): `OboEntity`, `OntologyLookup`, `TacularError` / `TacularKeyError`, `tacular.constants`

## Optional

- [CLAUDE.md](https://github.com/tacular-omics/tacular/blob/main/CLAUDE.md): guide for coding agents working on tacular itself (architecture, conventions, data-correctness gotchas)
- [data_gen/README.md](https://github.com/tacular-omics/tacular/blob/main/data_gen/README.md): how ontology data is regenerated, and known upstream data-quality issues
- [jsons/](https://github.com/tacular-omics/tacular/tree/main/jsons): JSON snapshots of every lookup for non-Python consumers
- [mzPAF specification](https://github.com/HUPO-PSI/mzpaf): source of the fragment-ion conventions (only the default internal type `by` is in the mzPAF grammar)
- [GitHub](https://github.com/tacular-omics/tacular) and [PyPI](https://pypi.org/project/tacular/)
