API Reference

Annotation

class paftacular.annotation.CommonAnnotationParams[source]

Bases: TypedDict

Common parameters shared across all annotation factory methods

adducts: list[Adduct | str] | None

analyte_reference: int | None

charge: int

confidence: float | None

is_auxiliary: bool

isotopes: list[IsotopeSpecification | str | int] | None

mass_error: float | None

mass_error_unit: Literal['da', 'ppm']

neutral_losses: list[NeutralLoss | str] | None

class paftacular.annotation.PafAnnotation(ion_type, analyte_reference=None, is_auxiliary=False, neutral_losses=(), isotopes=(), adducts=(), charge=1, mass_error=None, confidence=None)[source]

Bases: object

Fragment ion annotation following mzPAF specification

Parameters:

ion_type (PeptideIon | InternalFragment | ImmoniumIon | ReferenceIon | NamedCompound | ChemicalFormula | SMILESCompound | UnknownIon | PrecursorIon)
analyte_reference (int | None)
is_auxiliary (bool)
neutral_losses (tuple[NeutralLoss, ...])
isotopes (tuple[IsotopeSpecification, ...])
adducts (tuple[Adduct, ...])
charge (int)
mass_error (MassError | None)
confidence (float | None)

adducts: tuple[Adduct, ...]

analyte_reference: int | None

as_dict()[source]

Convert the annotation to a dictionary representation

Return type:: dict

charge: int

comp(calculate_sequence=True)[source]

Calculate the elemental composition of the annotated ion including modifications

Return type:: Counter[ElementInfo]
Parameters:: calculate_sequence (bool)

confidence: float | None

dict_composition(calculate_sequence=True)[source]

Get the elemental composition as a dictionary of element symbols to counts

Return type:: dict[str, int]
Parameters:: calculate_sequence (bool)

formula(calculate_sequence=True)[source]

Get the chemical formula string of the annotated ion

Return type:: str
Parameters:: calculate_sequence (bool)

ion_type: PeptideIon | InternalFragment | ImmoniumIon | ReferenceIon | NamedCompound | ChemicalFormula | SMILESCompound | UnknownIon | PrecursorIon

is_auxiliary: bool

isotopes: tuple[IsotopeSpecification, ...]

static make_formula(formula, **kwargs)[source]

Create a PafAnnotation for a chemical formula

Return type:

PafAnnotation

Parameters:

formula (str)
kwargs (Unpack[CommonAnnotationParams])

static make_immonium(amino_acid, modification=None, **kwargs)[source]

Create a PafAnnotation for an immonium ion

Return type:

PafAnnotation

Parameters:

amino_acid (str | AminoAcids)
modification (str | None)
kwargs (Unpack[CommonAnnotationParams])

static make_internal(start_position, end_position, ion_type='by', sequence=None, **kwargs)[source]

Create a PafAnnotation for an internal fragment

Return type:

PafAnnotation

Parameters:

start_position (int)
end_position (int)
ion_type (str | InternalSeries)
sequence (str | None)
kwargs (Unpack[CommonAnnotationParams])

static make_named_compound(name, **kwargs)[source]

Create a PafAnnotation for a named compound

Return type:

PafAnnotation

Parameters:

name (str)
kwargs (Unpack[CommonAnnotationParams])

static make_peptide(ion_type, position, sequence=None, **kwargs)[source]

Create a PafAnnotation for a peptide fragment ion

Return type:

PafAnnotation

Parameters:

ion_type (str | IonSeries)
position (int)
sequence (str | None)
kwargs (Unpack[CommonAnnotationParams])

static make_precursor(**kwargs)[source]

Create a PafAnnotation for the precursor ion

Return type:: PafAnnotation
Parameters:: kwargs (Unpack[CommonAnnotationParams])

static make_reference(name, **kwargs)[source]

Create a PafAnnotation for a reference ion

Return type:

PafAnnotation

Parameters:

name (str)
kwargs (Unpack[CommonAnnotationParams])

static make_smiles(smiles, **kwargs)[source]

Create a PafAnnotation for a SMILES compound

Return type:

PafAnnotation

Parameters:

smiles (str)
kwargs (Unpack[CommonAnnotationParams])

static make_unknown(label=None, **kwargs)[source]

Create a PafAnnotation for an unknown/unannotated ion

Return type:

PafAnnotation

Parameters:

label (int | None)
kwargs (Unpack[CommonAnnotationParams])

mass(monoisotopic=True, calculate_sequence=True)[source]

Calculate the mass of the annotated ion including modifications

Return type:

float

Parameters:

monoisotopic (bool)
calculate_sequence (bool)

mass_error: MassError | None

mz(monoisotopic=True, calculate_sequence=True)[source]

Calculate the m/z of the annotated ion

Return type:

float

Parameters:

monoisotopic (bool)
calculate_sequence (bool)

neutral_losses: tuple[NeutralLoss, ...]

static parse(annotation_str)[source]

Parse a single mzPAF annotation string into a FragmentAnnotation object

Return type:: PafAnnotation
Parameters:: annotation_str (str)

property peptacular_ion_type: IonType | None: Map to peptacular IonType if applicable, else None

proforma_formula(calculate_sequence=True)[source]

Get the ProForma-style chemical formula string of the annotated ion

Return type:: str
Parameters:: calculate_sequence (bool)

property sequence: str | None: Get the peptide sequence if applicable, else None

serialize(include_sequence=True)[source]

Serialize the annotation back to mzPAF string format

Return type:: str
Parameters:: include_sequence (bool)

Parser

class paftacular.parser.mzPAFParser[source]

Bases: object

parse(annotation_str)[source]

Parse a single annotation string

Return type:: PafAnnotation
Parameters:: annotation_str (str)

parse_multi(annotation_str)[source]

Parse potentially multiple comma-separated annotations

Follows the mzPAF spec’s Appendix A strategy: from the current position, greedily match one annotation; if the next unmatched character is a comma, skip it and continue; if the match reached the end of the string, parsing is complete; otherwise it’s a parse error. This (rather than a naive comma split) is required because commas may legitimately appear inside bracketed content, e.g. a reference or named-compound label.

Return type:: list[PafAnnotation]
Parameters:: annotation_str (str)

paftacular.parser.parse(annotation_str)[source]

parse single mzPAF annotation string into PafAnnotation

Return type:: PafAnnotation | list[PafAnnotation]
Parameters:: annotation_str (str)

paftacular.parser.parse_multi(annotation_str)[source]

parse mzPAF annotation string into list of PafAnnotation

Return type:: list[PafAnnotation]
Parameters:: annotation_str (str)

paftacular.parser.parse_single(annotation_str)[source]

backward compatibility alias for parse()

Return type:: PafAnnotation
Parameters:: annotation_str (str)

Annotation Types

class paftacular.comps.Adduct(count, base_formula)[source]

Bases: Serializable, ScalableComposition, MassProvider

Parameters:

count (int)
base_formula (str)

as_dict()[source]

Convert the adduct to a dictionary representation

Return type:: dict

base_formula: str

count: int

property formula: str

static parse(s)[source]

Parse a single adduct string like ‘+H’, ‘+2Na’, ‘-NH4’

Return type:: Adduct
Parameters:: s (str)

property proforma_formula: str

serialize()[source]

Return type:: str

class paftacular.comps.ChemicalFormula(formula)[source]

Bases: Serializable, CompositionProvider, MassProvider

Represents a chemical formula

Example

f{C13H9}/-0.55ppm f{C12H9N}/0.06ppm f{C13H9N}/-2.01ppm f{C13H10N}/-0.11ppm f{C13H11N}/-0.09ppm f{C13H12N}/0.26ppm f{C14H10N}/0.19ppm f{C14H11N}/0.45ppm f{C14H10NO}/0.03ppm

Parameters:: formula (str)

property composition: Counter[ElementInfo]: Get elemental composition

formula: str

static parse(s)[source]

Parse chemical formula string like ‘f{C13H9}’

Return type:: ChemicalFormula
Parameters:: s (str)

property proforma_formula: str

serialize()[source]

Return type:: str

class paftacular.comps.CompositionProvider[source]

Bases: ABC

Base class for objects that can provide composition

abstract property composition: Counter[ElementInfo]: Get elemental composition

property dict_composition: dict[str, int]: Get composition as a dictionary with element symbols as keys

mass(monoisotopic=True)[source]

Calculate mass from composition

Return type:: float
Parameters:: monoisotopic (bool)

class paftacular.comps.ImmoniumIon(amino_acid, modification=None)[source]

Bases: Serializable, CompositionProvider, MassProvider

Represents an immonium ion

Parameters:

amino_acid (AminoAcids)
modification (str | None)

amino_acid: AminoAcids

property composition: Counter[ElementInfo]: Get elemental composition

property formula: str

mass(monoisotopic=True)[source]

Calculate mass from composition

Return type:: float
Parameters:: monoisotopic (bool)

modification: str | None

static parse(s)[source]

Parse immonium ion string like ‘IK’, ‘IM[Oxidation]’

Return type:: ImmoniumIon
Parameters:: s (str)

serialize()[source]

Return type:: str

class paftacular.comps.InternalFragment(start_position, end_position, sequence=None, nterm_ion_type=None, cterm_ion_type=None)[source]

Bases: Serializable, CompositionProvider, MassProvider

Represents an internal fragment ion with optional backbone cleavage specification

Parameters:

start_position (int)
end_position (int)
sequence (str | None)
nterm_ion_type (IonSeries | None)
cterm_ion_type (IonSeries | None)

property composition: Counter[ElementInfo]: Get elemental composition

cterm_ion_type: IonSeries | None

end_position: int

property formula: str

mass(monoisotopic=True)[source]

Calculate mass from composition

Return type:: float
Parameters:: monoisotopic (bool)

nterm_ion_type: IonSeries | None

static parse(s)[source]

Parse internal fragment string like ‘m5:10’, ‘m5:10{PEPTIDE}’

Return type:: InternalFragment
Parameters:: s (str)

sequence: str | None

serialize(include_sequence=True)[source]

Return type:: str
Parameters:: include_sequence (bool)

start_position: int

class paftacular.comps.IsotopeSpecification(count=0, element=None, is_average=False)[source]

Bases: Serializable, CompositionProvider, MassProvider

Represents isotope information

Parameters:

count (int)
element (str | None)
is_average (bool)

as_dict()[source]

Convert isotope specification to dictionary representation

Return type:: dict

property composition: Counter[ElementInfo]: Get elemental composition

count: int

element: str | None

is_average: bool

mass(monoisotopic=True)[source]

Calculate mass contribution of isotope specification

Return type:: float
Parameters:: monoisotopic (bool)

static parse(s)[source]

Parse isotope string like ‘+i’, ‘-2i13C’, ‘+iA’

Return type:: IsotopeSpecification
Parameters:: s (str)

serialize()[source]

Return type:: str

class paftacular.comps.MassError(value, unit='da')[source]

Bases: Serializable

Represents mass error with value and unit

Parameters:

value (float)
unit (Literal['da', 'ppm'])

static parse(s)[source]

Parse mass error string like ‘0.55ppm’ or ‘0.06’

Return type:: MassError
Parameters:: s (str)

serialize()[source]

Return type:: str

unit: Literal['da', 'ppm']

value: float

class paftacular.comps.MassProvider[source]

Bases: ABC

Base class for objects that can provide mass

property average_mass: float

abstractmethod mass(monoisotopic=True)[source]

Calculate mass

Return type:: float
Parameters:: monoisotopic (bool)

property monoisotopic_mass: float

class paftacular.comps.NamedCompound(name)[source]

Bases: Serializable, CompositionProvider, MassProvider

Represents a named compound.

Example: 0@_{Urocanic Acid}

Parameters:: name (str)

property composition: Counter[ElementInfo]: Get elemental composition

mass(monoisotopic=True)[source]

Calculate mass from composition

Return type:: float
Parameters:: monoisotopic (bool)

name: str

static parse(s)[source]

Parse named compound string like ‘_{Urocanic Acid}’

Return type:: NamedCompound
Parameters:: s (str)

serialize()[source]

Return type:: str

class paftacular.comps.NeutralLoss(count, base_formula=None, base_mass=None, base_reference=None)[source]

Bases: Serializable, ScalableComposition, MassProvider

Represents a neutral loss or gain

Parameters:

count (int)
base_formula (str | None)
base_mass (float | None)
base_reference (str | None)

as_dict()[source]

Convert the neutral loss to a dictionary representation

Return type:: dict

base_formula: str | None

base_mass: float | None

base_reference: str | None

count: int

property formula: str

property loss_type: Literal['mass', 'formula', 'reference']

mass(monoisotopic=True)[source]

Calculate mass from composition

Return type:: float
Parameters:: monoisotopic (bool)

static parse(loss_str)[source]

Parse a neutral loss string into a NeutralLoss object

Return type:: NeutralLoss
Parameters:: loss_str (str)

property proforma_formula: str

property reference: RefMolInfo | str | None

serialize(loss_type=None, monoisotopic=True)[source]

Return type:

str

Parameters:

loss_type (Literal['mass', 'formula', 'reference'] | None)
monoisotopic (bool)

class paftacular.comps.PeptideIon(series, position, sequence=None)[source]

Bases: Serializable, CompositionProvider, MassProvider

Represents a primary peptide fragment ion

Parameters:

series (IonSeries)
position (int)
sequence (str | None)

property composition: Counter[ElementInfo]: Get elemental composition

property formula: str

mass(monoisotopic=True)[source]

Calculate mass from composition

Return type:: float
Parameters:: monoisotopic (bool)

static parse(s)[source]

Parse peptide ion string like ‘b5’, ‘y10{PEPTIDE}’

Return type:: PeptideIon
Parameters:: s (str)

position: int

sequence: str | None

serialize(include_sequence=True)[source]

Return type:: str
Parameters:: include_sequence (bool)

series: IonSeries

class paftacular.comps.PrecursorIon[source]

Bases: Serializable, CompositionProvider, MassProvider

Represents a precursor ion

property composition: Counter[ElementInfo]: Get elemental composition

property formula: str | None

mass(monoisotopic=True)[source]

Calculate mass from composition

Return type:: float
Parameters:: monoisotopic (bool)

static parse(s)[source]

Parse precursor ion string ‘p’

Return type:: PrecursorIon
Parameters:: s (str)

serialize()[source]

Return type:: str

class paftacular.comps.ReferenceIon(name)[source]

Bases: Serializable, CompositionProvider, MassProvider

Represents a reference ion

Parameters:: name (str)

property composition: Counter[ElementInfo]: Get elemental composition

property formula: str | None

mass(monoisotopic=True)[source]

Calculate mass from composition

Return type:: float
Parameters:: monoisotopic (bool)

name: str

static parse(s)[source]

Parse reference ion string like ‘r[Phospho]’

Return type:: ReferenceIon
Parameters:: s (str)

property reference: RefMolInfo

serialize()[source]

Return type:: str

class paftacular.comps.SMILESCompound(smiles)[source]

Bases: Serializable, CompositionProvider, MassProvider

Represents a SMILES string

Example

s{CN=C=O}[M+H]/-0.55ppm s{COc(c1)cccc1C#N}[M+H+Na]^2/1.29ppm

Parameters:: smiles (str)

property composition: Counter[ElementInfo][source]: Get elemental composition

property formula: str

static parse(s)[source]

Parse SMILES compound string like ‘s{CN=C=O}’

Return type:: SMILESCompound
Parameters:: s (str)

property proforma_formula: str

serialize()[source]

Return type:: str

smiles: str

class paftacular.comps.ScalableComposition[source]

Bases: CompositionProvider

Mixin for compositions that scale by count and sign

property composition: Counter[ElementInfo]: Get scaled composition

count: int

class paftacular.comps.Serializable[source]

Bases: ABC

Base class for serializable objects

abstractmethod serialize()[source]

Return type:: str

class paftacular.comps.UnknownIon(label=None)[source]

Bases: Serializable, CompositionProvider, MassProvider

Represents an unknown/unannotated ion

Parameters:: label (int | None)

property composition: Counter[ElementInfo]: Get elemental composition

label: int | None

mass(monoisotopic=True)[source]

Calculate mass from composition

Return type:: float
Parameters:: monoisotopic (bool)

static parse(s)[source]

Parse unknown ion string like ‘?’ or ‘?5’

Return type:: UnknownIon
Parameters:: s (str)

serialize()[source]

Return type:: str

paftacular.comps.composition_to_formula_string(comp)[source]

Convert composition to standard chemical formula string

Return type:: str
Parameters:: comp (Counter[ElementInfo])

paftacular.comps.composition_to_proforma_formula_string(comp, hill_order=True)[source]

Convert composition to ProForma-style formula string

Return type:

str

Parameters:

comp (Counter[ElementInfo])
hill_order (bool)

paftacular.comps.formula_to_composition(formula)[source]

Convert chemical formula string to elemental composition

Return type:: Counter[ElementInfo]
Parameters:: formula (str)

Constants

class paftacular.constants.AminoAcids(*values)[source]

Bases: StrEnum

Standard amino acids

A = 'A'

C = 'C'

D = 'D'

E = 'E'

F = 'F'

G = 'G'

H = 'H'

I = 'I'

K = 'K'

L = 'L'

M = 'M'

N = 'N'

P = 'P'

Q = 'Q'

R = 'R'

S = 'S'

T = 'T'

V = 'V'

W = 'W'

Y = 'Y'

class paftacular.constants.AnnotationName(*values)[source]

Bases: StrEnum

FORMULA = 'formula'

IMMONIUM = 'immonium'

INTERNAL = 'internal'

NAMED_COMPOUND = 'named_compound'

PRECURSOR = 'precursor'

REFERENCE = 'reference'

SERIES = 'series'

SMILES = 'smiles'

UNANNOTATED = 'unannotated'

class paftacular.constants.BackboneCleavageType(*values)[source]

Bases: StrEnum

Types of backbone cleavages for internal fragments

A = 'a'

B = 'b'

C = 'c'

X = 'x'

Y = 'y'

Z = 'z'

class paftacular.constants.InternalSeries(*values)[source]

Bases: StrEnum

Enumeration of internal ion series types

AX = 'ax'

AY = 'ay'

AZ = 'az'

BX = 'bx'

BY = 'by'

BZ = 'bz'

CX = 'cx'

CY = 'cy'

CZ = 'cz'

class paftacular.constants.IonSeries(*values)[source]

Bases: StrEnum

Enumeration of ion series types

A = 'a'

B = 'b'

C = 'c'

D = 'd'

DA = 'da'

DB = 'db'

V = 'v'

W = 'w'

WA = 'wa'

WB = 'wb'

X = 'x'

Y = 'y'

Z = 'z'

Utilities

paftacular.util.parse_formula(formula)[source]

Parse a chemical formula into element counts, supporting isotopes.

Parameters:: formula (str) – Chemical formula string (e.g., “H2O”, “CO2”, “[13C2]H6”)
Return type:: Counter[str]
Returns:: Counter mapping element symbols to their counts - Regular elements: “H”, “O”, “Ca” - Isotopes: “13C”, “2H” (without brackets)