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: typed.py file 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)  # IonSeries.Y
print(ann.ion_type.position)  # 5

# Calculate masses
print(ann.monoisotopic_mass)   # Calculated mass
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.

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

MIT

Contributing

Contributions welcome! Please submit a Pull Request.

Author: Patrick Garrett (pgarrett@scripps.edu)