Metadata-Version: 2.5
Name: paftacular
Version: 1.4.0
Summary: Parse, serialize, and analyze HUPO-PSI mzPAF peak annotations
Project-URL: Homepage, https://github.com/tacular-omics/paftacular
Project-URL: Documentation, https://paftacular.readthedocs.io/
Project-URL: Repository, https://github.com/tacular-omics/paftacular
Project-URL: Issues, https://github.com/tacular-omics/paftacular/issues
Project-URL: Changelog, https://github.com/tacular-omics/paftacular/blob/main/CHANGELOG.md
Project-URL: DOI, https://doi.org/10.5281/zenodo.19076277
Author-email: "Patrick T. Garrett" <pgarrett@scripps.edu>, "John R. Yates III" <jyates@scripps.edu>
Maintainer-email: "Patrick T. Garrett" <pgarrett@scripps.edu>
License-Expression: MIT
License-File: LICENSE
Keywords: mass-spectrometry,mzpaf,peak-annotation,proteomics,psi
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: tacular<2,>=1.2
Provides-Extra: all
Requires-Dist: mcp<3,>=2.1.1; extra == 'all'
Requires-Dist: peptacular<5,>=4.2; extra == 'all'
Requires-Dist: pysmiles>=2.0.1; extra == 'all'
Provides-Extra: mcp
Requires-Dist: mcp<3,>=2.1.1; extra == 'mcp'
Requires-Dist: peptacular<5,>=4.2; extra == 'mcp'
Provides-Extra: peptacular
Requires-Dist: peptacular<5,>=4.2; extra == 'peptacular'
Provides-Extra: smiles
Requires-Dist: pysmiles>=2.0.1; extra == 'smiles'
Description-Content-Type: text/markdown

# paftacular

<div align="center">
  <img src="https://raw.githubusercontent.com/tacular-omics/paftacular/main/paftacular_logo.png" alt="Paftacular Logo" width="400" style="margin: 50px;"/>

[![Python package](https://github.com/tacular-omics/paftacular/actions/workflows/ci.yml/badge.svg)](https://github.com/tacular-omics/paftacular/actions/workflows/ci.yml)
[![codecov](https://codecov.io/github/tacular-omics/paftacular/graph/badge.svg?token=lZDTvRrnuq)](https://codecov.io/github/tacular-omics/paftacular)
[![Documentation Status](https://readthedocs.org/projects/paftacular/badge/?version=latest)](https://paftacular.readthedocs.io/en/latest/?badge=latest)
[![PyPI version](https://badge.fury.io/py/paftacular.svg)](https://badge.fury.io/py/paftacular)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19076277.svg)](https://doi.org/10.5281/zenodo.19076277)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-g.svg)](https://opensource.org/licenses/MIT)

</div>

paftacular parses and serializes **mzPAF** (Peak Annotation Format), the
[HUPO-PSI](https://www.psidev.info/) 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](https://github.com/tacular-omics/tacular)'s chemistry lookups,
and optionally integrates with [peptacular](https://github.com/tacular-omics/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,
  alongside a compact `as_dict()` display format.
- **Typed** (`py.typed`) and cached: repeated modifier/ion components share
  bounded instance caches.

## Install

```bash
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

```python
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.mass())  # 19.017841466812 (offset only; no sequence context)

# Parse several comma-separated annotations at once
anns = pft.parse("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 3 parsing entry points: `parse` (single or comma-separated, returns
one `PafAnnotation` or a list), `parse_multi` (always a list), and
`parse_single` (always exactly one, raises `ValueError` otherwise).

## What else it can do

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

```python
import paftacular as pft

ann = pft.parse_single("y2").resolve("PEPTIDE")
print(ann.sequence, ann.mz())  # DE 263.087377579912
```

Round-trip fragments generated by [peptacular](https://github.com/tacular-omics/peptacular)
straight back into `PafAnnotation` objects:

```python
import peptacular as pt
import paftacular as pft

fragments = pt.fragment("PEPTIDE", ion_types=("b", "y"), charges=[1])
ann = pft.parse_single(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:

```python
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_single("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](https://github.com/tacular-omics/paftacular/blob/main/docs/mcp.rst)
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](https://www.psidev.info/mzpaf) for full details.

## Documentation

- Full docs: [paftacular.readthedocs.io](https://paftacular.readthedocs.io/)
- Changelog: [CHANGELOG.md](https://github.com/tacular-omics/paftacular/blob/main/CHANGELOG.md)

## Citation

If you use paftacular in research, cite the archived software release. Machine-readable citation metadata is available in [`CITATION.cff`](https://github.com/tacular-omics/paftacular/blob/main/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](https://doi.org/10.5281/zenodo.19076277); individual releases also receive version-specific DOIs from Zenodo.

## License

paftacular is distributed under the [MIT License](https://github.com/tacular-omics/paftacular/blob/main/LICENSE). The bundled mzPAF specification remains under its own PSI copyright and distribution terms; see [third-party notices](https://github.com/tacular-omics/paftacular/blob/main/THIRD_PARTY_NOTICES.md).

## Contributing

See [CONTRIBUTING.md](https://github.com/tacular-omics/paftacular/blob/main/CONTRIBUTING.md) for development setup, issue reporting, support, and pull-request guidance. Project governance is described in [GOVERNANCE.md](https://github.com/tacular-omics/paftacular/blob/main/GOVERNANCE.md), and security reports are handled according to [SECURITY.md](https://github.com/tacular-omics/paftacular/blob/main/SECURITY.md).

**Author:** Patrick Garrett (pgarrett@scripps.edu)
