Peptacular

Peptacular parses ProForma 2.1 peptide sequences and calculates their masses, fragments, and isotopic distributions. It's for anyone working with peptide-level proteomics data in Python who wants exact masses and fragment ions without hand-rolling ProForma parsing and mass tables. It's built on tacular's lookup data, and its fragments export directly as mzPAF strings readable by paftacular.

Why peptacular?

• Full ProForma 2.1 parsing into a chainable, editable ProFormaAnnotation object — or use the functional API directly on strings.
• Mass, m/z, composition, and predicted isotopic distributions, with monoisotopic and average mass support.
• Enzymatic digestion with missed cleavages, semi-specific, and non-specific modes.
• Fragment ion generation for 20+ ion types, exportable straight to mzPAF strings for paftacular.
• Batch-friendly: functional API calls on lists of sequences parallelize automatically, with streaming FASTA/gzip input and per-item error collection.
• Type-annotated throughout, plus optional Pyteomics, psm_utils, AlphaBase, and MCP integrations.

Install

pip install peptacular

Optional integrations install as extras:

pip install "peptacular[pyteomics]"
pip install "peptacular[psm-utils]"
pip install "peptacular[alphabase]"
pip install "peptacular[mcp]"

See the interoperability guide for supported conversions.

Quick example

import peptacular as pt

# Parse a sequence into a ProFormaAnnotation
peptide = pt.parse("PEM[Oxidation]TIDE")

# Calculate mass and m/z
print(peptide.mass())              # 849.3426002717299
print(peptide.mz(charge=2))        # 425.67857658818554

# Chained edits return a modified annotation
print(peptide.set_charge(2).set_peptide_name("Peptacular").serialize())
# (>Peptacular)PEM[Oxidation]TIDE/2

What else it can do

Digest a protein and generate fragment ions that round-trip through paftacular's mzPAF parser:

import peptacular as pt

trypsin = pt.PROTEASE_LOOKUP["trypsin"]
peptides = pt.digest("MKVLATSAGERTIDEK", enzyme_regex=trypsin.regex, missed_cleavages=1)
print([seq for seq, _ in peptides])
# ['MK', 'MKVLATSAGER', 'VLATSAGER', 'VLATSAGERTIDEK', 'TIDEK']

fragments = pt.fragment("PEPTIDE", ion_types=("b", "y"), charges=[1])
print(fragments[1].to_mzpaf())  # b2{PE}

The functional API operates on lists directly, auto-parallelizing for larger batches:

import peptacular as pt

peptides = ["[Acetyl]-PEPTIDES", "<13C>ARE", "SICK/2"]
print(pt.mass(peptides))               # [928.4025574375299, 388.23835027296, 451.245357946571]
print(pt.mz(peptides, charge=2))       # [465.20855517108555, 195.12645158880056, 225.6226789732855]

For streaming input and per-item error collection instead of a raised exception, see the streaming guide:

import peptacular as pt

results = pt.batch("mass", ["PEPTIDE", "PEP[UnknownModification]TIDE"], errors="collect")
print(results[0].value)                # 799.3599640328299
print(results[1].error.code)           # unresolved_modification

Raised errors are typed and all subclass pt.PeptacularError (a ValueError): invalid ProForma raises pt.ProFormaFormatError, an unresolved modification pt.UnknownModificationError, and so on. See the streaming guide for the full list.

Local MCP integration

Peptacular includes 12 optional MCP tools for agents to inspect annotations, calculate theoretical properties, digest protein sequences, and transform annotations. Calls accept small inline batches and return results directly, with no stored data or job setup. Install with pip install "peptacular[mcp]", then check the installation:

peptacular-mcp --check

See the local MCP guide for client setup, tool examples, and limits.

Documentation

• Full docs: peptacular.readthedocs.io
• Changelog: CHANGELOG.md
• ProForma 2.1 compliance status: PROFORMA_COMPLIANCE.md
• Contributing: CONTRIBUTING.md

License

MIT

Citation

Working on a JOSS submission, but in the meantime use:

https://doi.org/10.5281/zenodo.15054278