paftacular

paftacular parses and serializes mzPAF (Peak Annotation Format), the HUPO-PSI standard for describing MS/MS fragment ion annotations — ion type, modifications, charge state, mass error, and confidence — as a compact string. It's for anyone reading or writing fragment annotations from spectral libraries or search-engine output who wants a strict, round-trippable parser instead of ad hoc string splitting. It's built on tacular's chemistry lookups, and optionally integrates with peptacular for full peptide-sequence context — peptacular's own fragment generator emits mzPAF strings that paftacular parses directly.

Why paftacular?

• Strict mzPAF parsing and serialization, single or comma-separated batches, with precise, zero-based error locations on invalid input.
• Mass and elemental composition for parsed ions, with or without a resolved peptide sequence.
• Optional peptacular integration: resolve a fragment against a full ProForma analyte for complete mass/m/z, or round-trip fragments generated by peptacular straight back into PafAnnotation objects.
• Versioned JSON interchange (to_dict/from_dict) for durable storage.
• Typed (py.typed) and fast: repeated ion and modifier text shares immutable components through bounded parser caches.

Install

pip install paftacular
pip install paftacular[peptacular]  # resolve fragments against full sequences
pip install paftacular[smiles]      # SMILES support
pip install paftacular[mcp]         # local MCP server for AI agents
pip install paftacular[all]         # everything

Quick example

import paftacular as pft

# Parse a peptide fragment-ion annotation
ann = pft.parse("y5")
print(ann.ion_type.series, ann.ion_type.position)  # y 5
print(ann.get_mass())  # 19.017841150651 (offset only, no sequence context)

# Parse several comma-separated annotations at once
anns = pft.parse_multi("y5-H2O^2/1.2ppm*0.95,b3^2")
for a in anns:
    print(a.charge, a.confidence)
# 2 0.95
# 2 None

There are 2 parsing entry points: parse (exactly one annotation, raises PafParseError otherwise) and parse_multi (comma-separated, always a list). Every error caused by bad input is a PaftacularError, which is a ValueError. Upgrading from 1.x? See the migration guide.

What else it can do

Resolve a fragment against a full peptide with paftacular[peptacular] installed:

import paftacular as pft

ann = pft.parse("y2").resolve("PEPTIDE")
print(ann.sequence, ann.mz())  # DE 263.087377263751

Round-trip fragments generated by peptacular straight back into PafAnnotation objects:

import peptacular as pt
import paftacular as pft

fragments = pt.fragment("PEPTIDE", ion_types=("b", "y"), charges=[1])
ann = pft.parse(fragments[1].to_mzpaf())
print(ann.ion_type.series, ann.ion_type.position)  # b 2

Batch-parse with per-item error handling, and interchange via versioned JSON:

import json
import paftacular as pft

for result in pft.iter_parse(["y2,b3", "invalid", "p^2"]):
    if result.ok:
        print(result.index, len(result.annotations))
    else:
        print(result.index, result.error.position, result.error.reason)

ann = pft.parse("y2/0.000001ppm")
restored = pft.PafAnnotation.from_dict(json.loads(json.dumps(ann.to_dict())))
assert restored == ann

AI agent integration (MCP)

Install with pip install "paftacular[mcp]", then configure your MCP client to launch paftacular-mcp. The server provides nine tools for parsing, construction, sequence resolution, calculations, fragment generation, and m/z matching, plus scientific reference resources and analysis prompts. The mcp extra includes peptide support (paftacular[mcp,smiles] adds SMILES too); the base library needs no MCP dependencies. See the MCP guide for configuration and examples.

mzPAF format

[&][analyte@]ion_type[modifications][^charge][/mass_error][*confidence]

Examples: y5, b2{PEP}, y5-H2O^2, y5/1.2ppm*0.95

See the PSI mzPAF specification for full details.

Documentation

• Full docs: paftacular.readthedocs.io
• Changelog: CHANGELOG.md

Citation

If you use paftacular in research, cite the archived software release. Machine-readable citation metadata is available in CITATION.cff; GitHub's Cite this repository menu can render it as APA or BibTeX. The stable DOI for all versions is 10.5281/zenodo.19076277; individual releases also receive version-specific DOIs from Zenodo.

License

paftacular is distributed under the MIT License. The bundled mzPAF specification remains under its own PSI copyright and distribution terms; see third-party notices.

Contributing

See CONTRIBUTING.md for development setup, issue reporting, support, and pull-request guidance. Project governance is described in GOVERNANCE.md, and security reports are handled according to SECURITY.md.

Author: Patrick Garrett (pgarrett@scripps.edu)