paftacular

A Python library for parsing and serializing mzPAF (Peak Annotation Format), a standardized format for annotating mass spectrometry fragment ions in peptide/proteomics analysis. mzPAF is a specification from the Proteomics Standards Initiative (PSI) that provides a compact, human-readable notation for describing fragment ion types, chemical modifications, charge states, mass errors, and confidence scores.

Features

• mzPAF parsing: Handles parsing / serializing of mzPAF strings
• Properties: Supports calculating mass and composition of annotated ions
• Type annotations: Includes a py.typed marker for static type checking
• Caching: serialization and parsing results are cached for performance (when applicable)
• Peptacular: Optionally integrated with peptacular to enable parsing of included sequences and generation of mzPAF annotations

Installation

pip install paftacular
pip install paftacular[peptacular] # with peptacular integration
pip install paftacular[smiles]     # with SMILES support
pip install paftacular[all]        # with all optional dependencies

Quick Start

There are 3 parsing methods available:

• parse: Parses a single or multiple comma-separated mzPAF annotations. Returns a single PafAnnotation or a list of them.
• parse_multi: Parses multiple comma-separated mzPAF annotations. Always returns a list of PafAnnotation.
• parse_single: Parses a single mzPAF annotation. Returns a single PafAnnotation. Raises ValueError if multiple annotations are provided.

import paftacular as pft

# Parse a simple peptide ion
ann = pft.parse("y5")
print(ann.ion_type.series)  # y
print(ann.ion_type.position)  # 5

# Calculate masses
print(ann.mass())              # Monoisotopic mass by default
print(ann.serialize())         # Round-trip back to string

# Parse multiple ions
anns = pft.parse("y5-H2O^2/1.2ppm*0.95,b3^2")
for ann in anns:
  print(ann.charge)
  print(ann.mass_error.value)
  print(ann.confidence)

Documentation

Full documentation is available at Read the Docs.

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.

mzPAF Format

The mzPAF format uses compact notation:

[&][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.

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)