API Reference

Parser

class paftacular.parser.mzPAFParser

Bases: object

parse(annotation_str)

Parse a single annotation string

Return type:

PafAnnotation

Parameters:

annotation_str (str)

parse_multi(annotation_str)

Parse potentially multiple comma-separated annotations

Return type:

list[PafAnnotation]

Parameters:

annotation_str (str)

paftacular.parser.parse(annotation_str)

parse single mzPAF annotation string into PafAnnotation

Return type:

PafAnnotation | list[PafAnnotation]

Parameters:

annotation_str (str)

paftacular.parser.parse_multi(annotation_str)

parse mzPAF annotation string into list of PafAnnotation

Return type:

list[PafAnnotation]

Parameters:

annotation_str (str)

paftacular.parser.parse_single(annotation_str)

backward compatibility alias for parse()

Return type:

PafAnnotation

Parameters:

annotation_str (str)

Annotation Types

class paftacular.comps.Adduct(count, base_formula)

Bases: Serializable, ScalableComposition, MassProvider

Parameters:

• count (int)

• base_formula (str)

as_dict()

Convert the adduct to a dictionary representation

Return type:

dict

base_formula: str

count: int

property formula: str

static parse(s)

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

Return type:

Adduct

Parameters:

s (str)

property proforma_formula: str

serialize()

Return type:

str

class paftacular.comps.ChemicalFormula(formula)

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)

Parse chemical formula string like ‘f{C13H9}’

Return type:

ChemicalFormula

Parameters:

s (str)

property proforma_formula: str

serialize()

Return type:

str

class paftacular.comps.CompositionProvider

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)

Calculate mass from composition

Return type:

float

Parameters:

monoisotopic (bool)

class paftacular.comps.ImmoniumIon(amino_acid, modification=None)

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)

Calculate mass from composition

Return type:

float

Parameters:

monoisotopic (bool)

modification: str | None

static parse(s)

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

Return type:

ImmoniumIon

Parameters:

s (str)

serialize()

Return type:

str

class paftacular.comps.InternalFragment(start_position, end_position, sequence=None, nterm_ion_type=None, cterm_ion_type=None)

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)

Calculate mass from composition

Return type:

float

Parameters:

monoisotopic (bool)

nterm_ion_type: IonSeries | None

static parse(s)

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

Return type:

InternalFragment

Parameters:

s (str)

sequence: str | None

serialize(include_sequence=True)

Return type:

str

Parameters:

include_sequence (bool)

start_position: int

class paftacular.comps.IsotopeSpecification(count=0, element=None, is_average=False)

Bases: Serializable, CompositionProvider, MassProvider

Represents isotope information

Parameters:

• count (int)

• element (str | None)

• is_average (bool)

as_dict()

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)

Calculate mass contribution of isotope specification

Return type:

float

Parameters:

monoisotopic (bool)

static parse(s)

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

Return type:

IsotopeSpecification

Parameters:

s (str)

serialize()

Return type:

str

class paftacular.comps.MassError(value, unit='da')

Bases: Serializable

Represents mass error with value and unit

Parameters:

• value (float)

• unit (Literal['da', 'ppm'])

static parse(s)

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

Return type:

MassError

Parameters:

s (str)

serialize()

Return type:

str

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

value: float

class paftacular.comps.MassProvider

Bases: ABC

Base class for objects that can provide mass

property average_mass: float

abstractmethod mass(monoisotopic=True)

Calculate mass

Return type:

float

Parameters:

monoisotopic (bool)

property monoisotopic_mass: float

class paftacular.comps.NamedCompound(name)

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)

Calculate mass from composition

Return type:

float

Parameters:

monoisotopic (bool)

name: str

static parse(s)

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

Return type:

NamedCompound

Parameters:

s (str)

serialize()

Return type:

str

class paftacular.comps.NeutralLoss(count, base_formula=None, base_mass=None, base_reference=None)

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()

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)

Calculate mass from composition

Return type:

float

Parameters:

monoisotopic (bool)

static parse(loss_str)

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)

Return type:

str

Parameters:

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

• monoisotopic (bool)

class paftacular.comps.PeptideIon(series, position, sequence=None)

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)

Calculate mass from composition

Return type:

float

Parameters:

monoisotopic (bool)

static parse(s)

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

Return type:

PeptideIon

Parameters:

s (str)

position: int

sequence: str | None

serialize(include_sequence=True)

Return type:

str

Parameters:

include_sequence (bool)

series: IonSeries

class paftacular.comps.PrecursorIon

Bases: Serializable, CompositionProvider, MassProvider

Represents a precursor ion

property composition: Counter[ElementInfo]

Get elemental composition

property formula: str | None

mass(monoisotopic=True)

Calculate mass from composition

Return type:

float

Parameters:

monoisotopic (bool)

static parse(s)

Parse precursor ion string ‘p’

Return type:

PrecursorIon

Parameters:

s (str)

serialize()

Return type:

str

class paftacular.comps.ReferenceIon(name)

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)

Calculate mass from composition

Return type:

float

Parameters:

monoisotopic (bool)

name: str

static parse(s)

Parse reference ion string like ‘r[Phospho]’

Return type:

ReferenceIon

Parameters:

s (str)

property reference: RefMolInfo

serialize()

Return type:

str

class paftacular.comps.SMILESCompound(smiles)

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]

Get elemental composition

property formula: str

static parse(s)

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

Return type:

SMILESCompound

Parameters:

s (str)

property proforma_formula: str

serialize()

Return type:

str

smiles: str

class paftacular.comps.ScalableComposition

Bases: CompositionProvider

Mixin for compositions that scale by count and sign

property composition: Counter[ElementInfo]

Get scaled composition

count: int

class paftacular.comps.Serializable

Bases: ABC

Base class for serializable objects

abstractmethod serialize()

Return type:

str

class paftacular.comps.UnknownIon(label=None)

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)

Calculate mass from composition

Return type:

float

Parameters:

monoisotopic (bool)

static parse(s)

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

Return type:

UnknownIon

Parameters:

s (str)

serialize()

Return type:

str

paftacular.comps.composition_to_formula_string(comp)

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)

Convert composition to ProForma-style formula string

Return type:

str

Parameters:

• comp (Counter[ElementInfo])

• hill_order (bool)

paftacular.comps.formula_to_composition(formula)

Convert chemical formula string to elemental composition

Return type:

Counter[ElementInfo]

Parameters:

formula (str)

Constants

class paftacular.constants.AminoAcids(*values)

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)

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)

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)

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)

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)

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)