# paftacular

> Python library for HUPO-PSI mzPAF, the Peak Annotation Format for mass spectrometry
> fragment ions (`y5-H2O^2/1.2ppm*0.95`, `b2{PE}`, `IK[Acetyl]`, `p^2`): strict parsing and
> round-trip serialization, plus ion mass, m/z and elemental composition.

Install with `pip install paftacular` (Python >= 3.12). Import as `pft`. Parse with
`pft.parse_single()` (exactly one annotation) or `pft.parse_multi()` (comma-separated list).
`pft.iter_parse()` and `pft.parse_batch()` keep a structured `PafParseError` per bad record.
Build annotations with the `PafAnnotation.make_*` factories. `mass()` is the charged-species
mass in Da and `mz()` is m/z.

Without sequence context, peptide, internal and precursor ions give only the ion offset and
modifiers (`y5` alone is 19.018 Da). Embed the fragment sequence (`y2{DE}`) or call
`ann.resolve("PEPTIDE")` with the full ProForma analyte for complete masses. That needs the
`peptacular` extra. `to_dict()` / `PafAnnotation.from_dict()` is versioned, lossless
interchange. `as_dict()` is a display format only.

Extras: `peptacular` (sequence masses, `resolve()`, `to_mzpaf()` from peptacular fragments),
`smiles` (`s{...}` ions via pysmiles), `mcp` (local MCP server `paftacular-mcp` with nine
tools), `all`. paftacular is part of tacular-omics: chemistry data comes from `tacular`, and
peptacular fragments export mzPAF strings that paftacular parses.

## Docs

- [llms-full.txt](https://raw.githubusercontent.com/tacular-omics/paftacular/main/llms-full.txt): self-contained usage guide for agents, covering every public name, verified examples, the MCP server and gotchas
- [README](https://github.com/tacular-omics/paftacular/blob/main/README.md): overview, install, quick examples
- [Quickstart](https://paftacular.readthedocs.io/en/latest/quickstart.html): parsing, mass and serialization in five minutes
- [Usage guide](https://paftacular.readthedocs.io/en/latest/usage.html): the full grammar, factories, resolution, batch errors, interchange and calculation conventions
- [Installation](https://paftacular.readthedocs.io/en/latest/installation.html): extras and optional dependencies
- [Changelog](https://github.com/tacular-omics/paftacular/blob/main/CHANGELOG.md): release notes

## API

- [API reference](https://paftacular.readthedocs.io/en/latest/api.html): Sphinx autodoc for the public package
- [MCP server](https://paftacular.readthedocs.io/en/latest/mcp.html): the nine `paftacular-mcp` tools, resources, prompts, client setup and limits

## Optional

- [CLAUDE.md](https://github.com/tacular-omics/paftacular/blob/main/CLAUDE.md): guide for coding agents working on paftacular itself
- [mzPAF specification](https://www.psidev.info/mzpaf): the HUPO-PSI standard, also at [github.com/HUPO-PSI/mzPAF](https://github.com/HUPO-PSI/mzPAF)
- [tacular](https://github.com/tacular-omics/tacular): required reference data (elements, amino acids, modifications, ion offsets)
- [peptacular](https://github.com/tacular-omics/peptacular): optional ProForma library for sequence context and fragment generation
- [GitHub](https://github.com/tacular-omics/paftacular) and [PyPI](https://pypi.org/project/paftacular/)
