peff-digest 0.1.0__py3-none-any.whl

peff_digest/__init__.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from .api import digest
+from .config import DigestConfig, InternalMod, TerminalMod
+from .digest import Peptide, ann_to_map, digest_peff_sequence, get_cut_sites
+from .io import read_sequences
+
+__all__ = [
+    "DigestConfig",
+    "InternalMod",
+    "Peptide",
+    "TerminalMod",
+    "ann_to_map",
+    "digest",
+    "digest_peff_sequence",
+    "get_cut_sites",
+    "read_sequences",
+]

peff_digest/api.py

@@ -0,0 +1,114 @@
+"""High-level digest API — single orchestration entry point."""
+
+from __future__ import annotations
+
+import csv
+import itertools
+import logging
+import multiprocessing as mp
+import tempfile
+from functools import partial
+from pathlib import Path
+
+import polars as pl
+from tqdm import tqdm
+
+from peff_digest.config import DigestConfig
+from peff_digest.io import _digest_batch_worker, read_sequences
+
+logger = logging.getLogger(__name__)
+
+
+def _write_csv(
+    results: list[list[tuple[str, str, str | None, int, float | None]]],
+    output_file: str,
+) -> int:
+    """Write digest results to CSV atomically. Returns the number of peptides written."""
+    output_path = Path(output_file)
+    tmp_fd, tmp_path = tempfile.mkstemp(dir=output_path.parent, suffix=".tmp")
+    try:
+        with open(tmp_fd, "w", newline="") as f:
+            writer = csv.writer(f)
+            writer.writerow(["protein_id", "sequence", "variant", "length", "mass"])
+            for rows in results:
+                writer.writerows(rows)
+        Path(tmp_path).replace(output_path)
+    except Exception:
+        Path(tmp_path).unlink(missing_ok=True)
+        raise
+    return sum(len(r) for r in results)
+
+
+def _to_dataframe(
+    results: list[list[tuple[str, str, str | None, int, float | None]]],
+) -> pl.DataFrame:
+    """Convert digest results to a Polars DataFrame."""
+    protein_ids: list[str] = []
+    seqs: list[str] = []
+    variants: list[str | None] = []
+    lengths: list[int] = []
+    masses: list[float | None] = []
+
+    for rows in results:
+        for protein_id, seq, variant, length, mass in rows:
+            protein_ids.append(protein_id)
+            seqs.append(seq)
+            variants.append(variant)
+            lengths.append(length)
+            masses.append(mass)
+
+    return pl.DataFrame(
+        {
+            "protein_id": protein_ids,
+            "sequence": seqs,
+            "variant": variants,
+            "length": lengths,
+            "mass": masses,
+        },
+        schema={
+            "protein_id": pl.String,
+            "sequence": pl.String,
+            "variant": pl.String,
+            "length": pl.Int64,
+            "mass": pl.Float64,
+        },
+    )
+
+
+def digest(
+    config: DigestConfig,
+    show_progress: bool = False,
+    write_file: bool = False,
+) -> pl.DataFrame | None:
+    """
+    Run a full digest pipeline.
+
+    If write_file is False (default), returns a Polars DataFrame with columns:
+        protein_id (str), sequence (str), variant (str | null), length (i64), mass (f64 | null).
+    If write_file is True, writes results to config.output_file as CSV and returns None.
+    """
+    logger.info("Reading sequences from %s", config.input_file)
+    sequences, n_malformed = read_sequences(config.input_file)
+    skipped = f", {n_malformed} malformed entries skipped" if n_malformed else ""
+    logger.info("%d sequences loaded%s", len(sequences), skipped)
+
+    batches = list(itertools.batched(sequences, config.batch_size))
+    n_workers = config.workers or mp.cpu_count()
+    logger.info(
+        "Digesting with %d worker(s), batch size %d (%d batches total)",
+        n_workers,
+        config.batch_size,
+        len(batches),
+    )
+    worker = partial(_digest_batch_worker, config=config)
+    with mp.Pool(config.workers) as pool:
+        imap = pool.imap(worker, batches)
+        results = list(tqdm(imap, total=len(batches), disable=not show_progress, desc="Digesting", unit="batch"))
+
+    if write_file:
+        n_peptides = _write_csv(results, config.output_file)
+        logger.info("%d peptides written to %s", n_peptides, config.output_file)
+        return None
+
+    logger.info("%d peptides returned", sum(len(r) for r in results))
+    return _to_dataframe(results)

peff_digest/cli.py

@@ -0,0 +1,108 @@
+"""Command-line interface for peff-digest."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import multiprocessing as mp
+import sys
+
+import pydantic
+
+from peff_digest.api import digest
+from peff_digest.config import DigestConfig
+
+
+def main() -> None:
+    mp.freeze_support()
+    logging.basicConfig(level=logging.INFO, format="%(message)s", stream=sys.stderr)
+
+    parser = argparse.ArgumentParser(
+        prog="peff-digest",
+        description="Digest a PEFF or FASTA file and write peptides to CSV.",
+    )
+    parser.add_argument("--config", metavar="FILE", help="JSON or TOML config file")
+    parser.add_argument("--input-file", metavar="FILE", help="Input PEFF or FASTA file")
+    parser.add_argument(
+        "--output-file", metavar="FILE", default=argparse.SUPPRESS, help="Output CSV file (default: peptides.csv)"
+    )
+    parser.add_argument(
+        "--cleave-on", metavar="AAS", default=argparse.SUPPRESS, help="Amino acids to cleave on (default: KR)"
+    )
+    parser.add_argument("--missed-cleavages", type=int, metavar="N", default=argparse.SUPPRESS)
+    parser.add_argument("--semi-enzymatic", action="store_true", default=argparse.SUPPRESS)
+    parser.add_argument("--max-ptm-per-peptide", type=int, metavar="N", default=argparse.SUPPRESS)
+    parser.add_argument("--min-length", type=int, metavar="N", default=argparse.SUPPRESS)
+    parser.add_argument("--max-length", type=int, metavar="N", default=argparse.SUPPRESS)
+    parser.add_argument("--restrict-after", metavar="AAS", default=argparse.SUPPRESS)
+    parser.add_argument("--restrict-before", metavar="AAS", default=argparse.SUPPRESS)
+    parser.add_argument(
+        "--workers", type=int, metavar="N", default=argparse.SUPPRESS, help="Worker processes (default: all CPUs)"
+    )
+    parser.add_argument(
+        "--batch-size", type=int, metavar="N", default=argparse.SUPPRESS, help="Sequences per worker batch (default: 1)"
+    )
+    parser.add_argument("--min-mass", type=float, metavar="DA", default=argparse.SUPPRESS)
+    parser.add_argument("--max-mass", type=float, metavar="DA", default=argparse.SUPPRESS)
+    parser.add_argument(
+        "--drop-invalid-mass",
+        action="store_true",
+        default=argparse.SUPPRESS,
+        help="Exclude peptides whose mass cannot be computed",
+    )
+    parser.add_argument(
+        "--no-psi-mods",
+        dest="use_psi_mods",
+        action="store_false",
+        default=argparse.SUPPRESS,
+        help="Do not apply PSI-MOD (ModResPsi) annotations from the PEFF file",
+    )
+    parser.add_argument(
+        "--use-unimod-output",
+        action="store_true",
+        default=argparse.SUPPRESS,
+        help="Convert PSI-MOD mod tags to UniMod accessions in output; peptides with unmapped mods are dropped",
+    )
+    parser.add_argument(
+        "--no-simple-variants",
+        dest="include_simple_variants",
+        action="store_false",
+        default=argparse.SUPPRESS,
+        help="Skip VariantSimple (single AA substitution) entries",
+    )
+    parser.add_argument(
+        "--no-complex-variants",
+        dest="include_complex_variants",
+        action="store_false",
+        default=argparse.SUPPRESS,
+        help="Skip VariantComplex (multi-residue insertion/deletion/substitution) entries",
+    )
+    args = parser.parse_args()
+
+    # Build config: file first, then CLI overrides
+    cli_overrides = {
+        k: v for k, v in vars(args).items() if k != "config" and k in DigestConfig.model_fields and v is not None
+    }
+    cli_overrides = {k.replace("-", "_"): v for k, v in cli_overrides.items()}
+
+    if args.input_file:
+        cli_overrides["input_file"] = args.input_file
+
+    logger = logging.getLogger(__name__)
+    try:
+        if args.config:
+            config = DigestConfig.from_file(args.config, **cli_overrides)
+            logger.info("Config loaded from %s", args.config)
+        else:
+            config = DigestConfig(**cli_overrides)
+    except pydantic.ValidationError as exc:
+        for error in exc.errors():
+            loc = ".".join(str(x) for x in error["loc"])
+            logger.error("  %s: %s", loc, error["msg"])
+        sys.exit(1)
+
+    digest(config, show_progress=True, write_file=True)
+
+
+if __name__ == "__main__":
+    main()

peff_digest/config.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import json
+import tomllib
+from pathlib import Path
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class InternalMod(BaseModel, frozen=True):
+    modification: str
+    residue: str  # one or more AAs (e.g. "C" or "KR") — mod applies to each
+    mod_type: Literal["fixed", "variable"]
+
+
+class TerminalMod(BaseModel, frozen=True):
+    modification: str
+    position: Literal["nterm", "cterm"]
+    mod_type: Literal["fixed", "variable"]
+    residue: str | None = None  # AA that must be at the terminus; None = any
+    protein_terminus: bool = False  # True = only the protein N- or C-terminal peptide
+
+
+class DigestConfig(BaseModel):
+    input_file: str = ""
+    output_file: str = "peptides.csv"
+    cleave_on: str = "KR"
+    missed_cleavages: int = Field(default=2, ge=0)
+    semi_enzymatic: bool = False
+    max_ptm_per_peptide: int = Field(default=2, ge=0)
+    min_length: int = Field(default=7, ge=1)
+    max_length: int = Field(default=40, ge=1)
+    restrict_after: str = "P"
+    restrict_before: str = ""
+    cterminal: bool = True
+    internal_mods: list[InternalMod] = Field(default_factory=list)
+    terminal_mods: list[TerminalMod] = Field(default_factory=list)
+    min_mass: float | None = Field(default=None, gt=0)
+    max_mass: float | None = Field(default=None, gt=0)
+    drop_invalid_mass: bool = False
+    use_mod_names: bool = False
+    use_psi_mods: bool = True
+    use_unimod_output: bool = False
+    include_simple_variants: bool = True
+    include_complex_variants: bool = True
+    workers: int | None = Field(default=None, ge=1)
+    batch_size: int = Field(default=1, ge=1)
+
+    @field_validator("input_file")
+    @classmethod
+    def input_file_must_exist(cls, v: str) -> str:
+        if not v:
+            return v
+        if not Path(v).exists():
+            raise ValueError(f"input_file does not exist: {v}")
+        return v
+
+    @classmethod
+    def _parse_file(cls, path: Path) -> dict[str, Any]:
+        if path.suffix == ".toml":
+            with open(path, "rb") as f:
+                return tomllib.load(f)
+        with open(path) as f:
+            return json.load(f)
+
+    @classmethod
+    def from_file(cls, path: str | Path, **overrides: Any) -> DigestConfig:
+        data = cls._parse_file(Path(path))
+        return cls(**{**data, **overrides})
+
+    def to_file(self, path: str | Path) -> None:
+        p = Path(path)
+        data = self.model_dump()
+        if p.suffix == ".toml":
+            import tomli_w
+
+            data = {k: v for k, v in data.items() if v is not None}
+            with open(p, "wb") as f:
+                tomli_w.dump(data, f)
+        else:
+            with open(p, "w") as f:
+                json.dump(data, f, indent=2)

peff_digest/digest.py

@@ -0,0 +1,563 @@
+"""
+PEFF-aware protein digest.
+
+Produces all peptide ProFormaAnnotation variants from a PEFF SequenceEntry by:
+  1. Generating one sequence per variant (canonical + each VariantSimple/VariantComplex
+     applied independently — no combinations).
+  2. Digesting each variant sequence with the standard enzymatic rules.
+  3. For each peptide span, enumerating PEFF-annotated PTM combinations up to
+     max_ptm_per_peptide (0 = no PEFF PTMs applied, only unmodified peptides returned).
+
+Skipped: Processed entries (signal peptide / mature-chain trimming).
+"""
+
+from __future__ import annotations
+
+import copy
+import itertools
+from bisect import bisect_left, bisect_right
+from collections.abc import Generator
+from dataclasses import dataclass
+
+import pefftacular as pf
+import peptacular as pt
+import psimodpy
+from psimodpy import AminoAcid, PsiModDatabase, TermSpec
+
+from peff_digest.config import DigestConfig
+
+
+def get_cut_sites(
+    protein_sequence: str,
+    cleave_on: set[str],
+    restrict_after: set[str],
+    restrict_before: set[str],
+    cterminal: bool,
+) -> list[int]:
+    seq_len = len(protein_sequence)
+    cut_sites: list[int] = [0]
+    for i, aa in enumerate(protein_sequence):
+        if aa not in cleave_on:
+            continue
+        cut_pos = (i + 1) if cterminal else i
+        if cut_pos == 0 or cut_pos == seq_len:
+            continue
+        if restrict_after and protein_sequence[cut_pos] in restrict_after:
+            continue
+        if restrict_before and protein_sequence[cut_pos - 1] in restrict_before:
+            continue
+        cut_sites.append(cut_pos)
+    cut_sites.append(seq_len)
+    return cut_sites
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class _Variant:
+    """A concrete protein sequence derived from one PEFF annotation event."""
+
+    sequence: str
+    # Maps 1-based PEFF position → 0-based position in this variant's sequence.
+    # None means the position was deleted by a VariantComplex.
+    pos_map: dict[int, int | None]
+    source: pf.VariantSimple | pf.VariantComplex | None = None
+    source_orig: str = ""  # original AA(s) at the variant site
+
+
+def _canonical(sequence: str) -> _Variant:
+    return _Variant(sequence, {i + 1: i for i in range(len(sequence))})
+
+
+def _apply_simple(sequence: str, v: pf.VariantSimple) -> _Variant:
+    """Single AA substitution — sequence length is unchanged."""
+    pos0 = int(v.position) - 1  # 0-based
+    if pos0 < 0 or pos0 >= len(sequence):
+        return _canonical(sequence)  # out-of-range annotation → skip
+    new_seq = sequence[:pos0] + v.new_amino_acid + sequence[pos0 + 1 :]
+    pos_map: dict[int, int | None] = {i + 1: i for i in range(len(sequence))}
+    return _Variant(new_seq, pos_map, source=v, source_orig=sequence[pos0])
+
+
+def _apply_complex(sequence: str, v: pf.VariantComplex) -> _Variant:
+    """Multi-residue variant — sequence length may change."""
+    start0 = int(v.start_pos) - 1  # 0-based inclusive
+    end0 = int(v.end_pos)  # 0-based exclusive  (PEFF end is 1-based inclusive)
+    if start0 < 0 or end0 > len(sequence) or start0 > end0:
+        return _canonical(sequence)  # out-of-range annotation → skip
+
+    orig_seq = sequence[start0:end0]
+    new_seq = sequence[:start0] + v.new_sequence + sequence[end0:]
+    delta = len(v.new_sequence) - (end0 - start0)
+
+    pos_map: dict[int, int | None] = {}
+    for peff_pos in range(1, len(sequence) + 1):
+        orig0 = peff_pos - 1
+        if orig0 < start0:
+            pos_map[peff_pos] = orig0
+        elif orig0 < end0:
+            pos_map[peff_pos] = None  # consumed by the variant
+        else:
+            pos_map[peff_pos] = orig0 + delta
+
+    return _Variant(new_seq, pos_map, source=v, source_orig=orig_seq)
+
+
+def _variant_in_span(variant: _Variant, pep_start: int, pep_end: int) -> bool:
+    """Return True if the variant's mutation site overlaps the peptide span [pep_start, pep_end)."""
+    if variant.source is None:
+        return False
+    if isinstance(variant.source, pf.VariantSimple):
+        mapped = variant.pos_map.get(int(variant.source.position))
+        if mapped is None:
+            return False
+        return pep_start <= mapped < pep_end
+    # VariantComplex: the new sequence occupies [start0, start0+len(new_sequence))
+    v = variant.source
+    start0 = int(v.start_pos) - 1
+    new_len = len(v.new_sequence)
+    # After complex variant, the inserted region sits at [start0, start0+new_len)
+    # in the variant sequence. Check overlap with peptide span.
+    var_end = start0 + new_len
+    return pep_start < var_end and start0 < pep_end
+
+
+def _mods_in_span(
+    variant: _Variant,
+    span_start: int,  # 0-based in variant.sequence
+    span_end: int,  # 0-based exclusive
+    mod_entries: list[pf.ModResPsi | pf.ModResUnimod],
+    use_mod_names: bool = False,
+    psi_db: PsiModDatabase | None = None,
+    protein_len: int = 0,
+) -> list[tuple[int, str]]:
+    """Return (0-based peptide-local position, ProForma tag) for each PEFF mod in the span.
+
+    When *psi_db* is provided each mod is looked up to:
+    - Validate the origin residue against the (possibly variant-mutated) sequence.
+      Mods whose origin does not match the current residue are silently dropped.
+    - Promote terminus-specific mods (TermSpec.N_TERM / C_TERM) to the appropriate
+      terminal sentinel position (_NTERM_POS / _CTERM_POS) when the mod sits at the
+      protein terminus and the peptide spans that terminus.
+    """
+    result: list[tuple[int, str]] = []
+    for mod in mod_entries:
+        for peff_pos in mod.positions:
+            try:
+                peff_pos_int = int(peff_pos)
+            except (ValueError, TypeError):
+                continue  # skip unknown positions (e.g. '?')
+            local0 = variant.pos_map.get(peff_pos_int)
+            if local0 is None:
+                continue
+            pep_local = local0 - span_start
+            if not (0 <= pep_local < (span_end - span_start)):
+                continue
+            tag = mod.name if use_mod_names else mod.accession
+
+            if psi_db is not None:
+                entry = psi_db.get_by_id(mod.accession)
+                if entry is not None:
+                    # Validate: origin residue must match the (possibly mutated) residue.
+                    origin = entry.origin
+                    if isinstance(origin, AminoAcid) and origin != AminoAcid.ANY:
+                        if variant.sequence[local0] != str(origin):
+                            continue  # residue changed by variant — drop this mod
+
+                    # Terminal promotion: convert positional mod to terminal sentinel.
+                    # If a mod is terminal-specific but the conditions aren't met, drop it —
+                    # it cannot be validly applied as an internal modification.
+                    if entry.term_spec == TermSpec.N_TERM:
+                        if local0 == 0 and span_start == 0:
+                            result.append((_NTERM_POS, tag))
+                        continue
+                    if entry.term_spec == TermSpec.C_TERM:
+                        if local0 == protein_len - 1 and span_end == protein_len:
+                            result.append((_CTERM_POS, tag))
+                        continue
+
+            result.append((pep_local, tag))
+    return result
+
+
+_NTERM_POS = -1  # sentinel for N-terminal mods in the applicable list
+_CTERM_POS = -2  # sentinel for C-terminal mods in the applicable list
+
+
+def _apply_mod(ann: pt.ProFormaAnnotation, pos: int, tag: str, seq_len: int) -> None:
+    if pos == _NTERM_POS:
+        ann.append_nterm_mod(tag)
+    elif pos == _CTERM_POS:
+        ann.append_cterm_mod(tag)
+    else:
+        ann.append_internal_mod_at_index(pos, tag)
+
+
+def _yield_mod_variants(
+    base_sequence: str,
+    applicable: list[tuple[int, str]],
+    max_ptm: int,
+) -> list[pt.ProFormaAnnotation]:
+    """
+    Yield ProFormaAnnotation objects for the base peptide plus every combination
+    of 1..max_ptm mods applied to it.
+
+    Sentinel positions: _NTERM_POS (-1) = N-terminal, _CTERM_POS (-2) = C-terminal.
+    """
+    base = pt.parse(base_sequence)
+    variants: list[pt.ProFormaAnnotation] = [base]
+
+    if not applicable or max_ptm <= 0:
+        return variants
+
+    seq_len = len(base_sequence)
+    for n in range(1, min(max_ptm, len(applicable)) + 1):
+        for combo in itertools.combinations(applicable, n):
+            positions = [pos for pos, _ in combo]
+            if len(positions) != len(set(positions)):
+                continue  # multiple mods at the same site — skip this combo
+            ann = pt.parse(base_sequence)
+            for pos, tag in combo:
+                _apply_mod(ann, pos, tag, seq_len)
+            variants.append(ann)
+
+    return variants
+
+
+def _count_mods(ann: pt.ProFormaAnnotation) -> int:
+    """Return the total number of modifications on an annotation."""
+    count = 0
+    if ann._nterm_mods:
+        count += sum(ann._nterm_mods.values())
+    if ann._cterm_mods:
+        count += sum(ann._cterm_mods.values())
+    if ann._internal_mods:
+        for mods_dict in ann._internal_mods.values():
+            count += sum(mods_dict.values())
+    return count
+
+
+def _get_occupied_positions(ann: pt.ProFormaAnnotation) -> set[int]:
+    """Return the set of positions (including terminal sentinels) already carrying a mod."""
+    positions: set[int] = set()
+    if ann._nterm_mods:
+        positions.add(_NTERM_POS)
+    if ann._cterm_mods:
+        positions.add(_CTERM_POS)
+    if ann._internal_mods:
+        positions.update(ann._internal_mods.keys())
+    return positions
+
+
+def _yield_user_mod_variants(
+    base_ann: pt.ProFormaAnnotation,
+    user_applicable: list[tuple[int, str]],
+    remaining: int,
+) -> list[pt.ProFormaAnnotation]:
+    """Return annotation variants produced by layering user mods on top of *base_ann*.
+
+    Works like :func:`_yield_mod_variants` but starts from an existing annotation
+    (which may already carry PEFF mods) rather than a bare sequence string.
+    Uses :func:`copy.deepcopy` to avoid mutating the shared base.
+    """
+    variants: list[pt.ProFormaAnnotation] = [copy.deepcopy(base_ann)]
+    if not user_applicable or remaining <= 0:
+        return variants
+
+    seq_len = len(base_ann.stripped_sequence)
+    for n in range(1, min(remaining, len(user_applicable)) + 1):
+        for combo in itertools.combinations(user_applicable, n):
+            positions = [pos for pos, _ in combo]
+            if len(positions) != len(set(positions)):
+                continue  # multiple mods at the same site — skip
+            ann = copy.deepcopy(base_ann)
+            for pos, tag in combo:
+                _apply_mod(ann, pos, tag, seq_len)
+            variants.append(ann)
+    return variants
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class Peptide:
+    proforma: pt.ProFormaAnnotation
+    missed_cleavages: int
+    semi_enzymatic: bool
+    is_protein_nterm: bool = False
+    is_protein_cterm: bool = False
+    variant: pf.VariantSimple | pf.VariantComplex | None = None
+
+    @property
+    def sequence(self) -> str:
+        return self.proforma.stripped_sequence
+
+    @property
+    def mass(self) -> float:
+        return self.proforma.neutral_mass()
+
+    @property
+    def mod_map(self) -> dict[int, str]:
+        _, mod_map = ann_to_map(self.proforma)
+        return mod_map
+
+
+def digest_peff_sequence(
+    peff_entry: pf.SequenceEntry,
+    config: DigestConfig,
+    psi_db: PsiModDatabase | None = None,
+) -> Generator[Peptide, None, None]:
+    """
+    Digest a PEFF SequenceEntry and return all peptide variants as Peptide objects.
+
+    Each PEFF VariantSimple / VariantComplex is applied independently (not combined).
+    PEFF PTMs (ModResPsi) are applied in combinations of up to
+    ``config.max_ptm_per_peptide`` per peptide.  Pass 0 to skip PEFF PTMs entirely.
+    """
+
+    if psi_db is None:
+        psi_db = psimodpy.load()
+
+    sequence = peff_entry.sequence
+    _min = config.min_length if config.min_length is not None else 0
+    _max = config.max_length if config.max_length is not None else len(sequence)
+
+    restrict_after: set[str] = set(config.restrict_after)
+    restrict_before: set[str] = set(config.restrict_before)
+    cleave_on: set[str] = set(config.cleave_on)
+
+    internal_mods = config.internal_mods or []
+    terminal_mods = config.terminal_mods or []
+
+    fixed_mods: dict[str, str] = {}
+    variable_mods: dict[str, list[str]] = {}
+    for m in internal_mods:
+        for aa in m.residue:
+            if m.mod_type == "fixed":
+                fixed_mods[aa] = m.modification
+            else:
+                variable_mods.setdefault(aa, []).append(m.modification)
+
+    # Collect all PEFF mod annotations (PSI-MOD)
+    all_mods: list[pf.ModResPsi | pf.ModResUnimod] = []
+    if config.use_psi_mods:
+        all_mods.extend(peff_entry.mod_res_psi)
+
+    # One variant per PEFF event (canonical + each simple/complex independently)
+    variants: list[_Variant] = [_canonical(sequence)]
+    if config.include_simple_variants:
+        for v in peff_entry.variant_simple:
+            variants.append(_apply_simple(sequence, v))
+    if config.include_complex_variants:
+        for v in peff_entry.variant_complex:
+            variants.append(_apply_complex(sequence, v))
+
+    max_ptm_per_peptide = config.max_ptm_per_peptide
+    use_mod_names = config.use_mod_names
+    semi_enzymatic = config.semi_enzymatic
+    missed_cleavages = config.missed_cleavages
+
+    seen: set[str] = set()
+
+    for variant in variants:
+        vseq = variant.sequence
+        seq_len = len(vseq)
+
+        cut_sites = get_cut_sites(vseq, cleave_on, restrict_after, restrict_before, config.cterminal)
+        n_cuts = len(cut_sites)
+
+        def _process_span(
+            start: int,
+            end: int,
+            mc: int,
+            is_semi: bool,
+            _vseq: str = vseq,
+            _variant: _Variant = variant,
+            _seq_len: int = seq_len,
+        ) -> list[Peptide]:
+            length = end - start
+            if length < _min or length > _max:
+                return []
+            pep_seq = _vseq[start:end]
+            is_protein_nterm = start == 0
+            is_protein_cterm = end == _seq_len
+
+            # ----------------------------------------------------------------
+            # Phase 1: PEFF mods only
+            # When psi_db is provided, _mods_in_span validates each mod against
+            # the (possibly variant-mutated) residue and promotes terminus-specific
+            # mods to terminal sentinels.
+            # ----------------------------------------------------------------
+            peff_applicable = _mods_in_span(_variant, start, end, all_mods, use_mod_names, psi_db, _seq_len)
+
+            # Drop PEFF mods at positions reserved for fixed user mods.
+            if fixed_mods:
+                fixed_positions = {i for i, res in enumerate(pep_seq) if res in fixed_mods}
+                peff_applicable = [(pos, tag) for pos, tag in peff_applicable if pos not in fixed_positions]
+
+            span_variant = _variant.source if _variant_in_span(_variant, start, end) else None
+            try:
+                peff_variants = _yield_mod_variants(pep_seq, peff_applicable, max_ptm_per_peptide)
+            except ValueError:
+                return []  # unparseable sequence (e.g. contains '*' or spaces) — skip span
+
+            # ----------------------------------------------------------------
+            # Build user variable mod candidates once for this span.
+            # These are filtered per-peff-variant below to exclude occupied positions.
+            # ----------------------------------------------------------------
+            user_variable: list[tuple[int, str]] = []
+            if variable_mods:
+                for aa, tags in variable_mods.items():
+                    for i, res in enumerate(pep_seq):
+                        if res == aa:
+                            for tag in tags:
+                                user_variable.append((i, tag))
+            if terminal_mods:
+                for tm in terminal_mods:
+                    if tm.mod_type != "variable":
+                        continue
+                    if tm.position == "nterm":
+                        is_term = is_protein_nterm if tm.protein_terminus else True
+                        term_aa = pep_seq[0]
+                        sentinel = _NTERM_POS
+                    else:
+                        is_term = is_protein_cterm if tm.protein_terminus else True
+                        term_aa = pep_seq[-1]
+                        sentinel = _CTERM_POS
+                    if not is_term:
+                        continue
+                    if tm.residue is not None and term_aa not in tm.residue:
+                        continue
+                    user_variable.append((sentinel, tm.modification))
+
+            # ----------------------------------------------------------------
+            # Phase 2: for each validated PEFF variant, apply user mods.
+            # ----------------------------------------------------------------
+            span_results: list[Peptide] = []
+            for peff_ann in peff_variants:
+                existing = _count_mods(peff_ann)
+                remaining = max_ptm_per_peptide - existing
+                occupied = _get_occupied_positions(peff_ann)
+
+                # Exclude positions already carrying a PEFF mod or reserved by fixed mods.
+                filtered_user = [
+                    (pos, tag)
+                    for pos, tag in user_variable
+                    if pos not in occupied and (not fixed_mods or pos not in fixed_positions)
+                ]
+
+                user_variants = _yield_user_mod_variants(peff_ann, filtered_user, remaining)
+
+                for ann in user_variants:
+                    # Apply fixed internal mods unconditionally (positions were excluded
+                    # from PEFF and user variable pools so no double-mod conflict).
+                    if fixed_mods:
+                        for aa, mod_str in fixed_mods.items():
+                            for i, res in enumerate(pep_seq):
+                                if res == aa:
+                                    ann.append_internal_mod_at_index(i, mod_str)
+                    # Apply fixed terminal mods.
+                    if terminal_mods:
+                        for tm in terminal_mods:
+                            if tm.mod_type != "fixed":
+                                continue
+                            if tm.position == "nterm":
+                                is_term = is_protein_nterm if tm.protein_terminus else True
+                                term_aa = pep_seq[0]
+                            else:
+                                is_term = is_protein_cterm if tm.protein_terminus else True
+                                term_aa = pep_seq[-1]
+                            if not is_term:
+                                continue
+                            if tm.residue is not None and term_aa not in tm.residue:
+                                continue
+                            if tm.position == "nterm":
+                                ann.append_nterm_mod(tm.modification)
+                            else:
+                                ann.append_cterm_mod(tm.modification)
+                    span_results.append(
+                        Peptide(
+                            proforma=ann,
+                            missed_cleavages=mc,
+                            semi_enzymatic=is_semi,
+                            is_protein_nterm=is_protein_nterm,
+                            is_protein_cterm=is_protein_cterm,
+                            variant=span_variant,
+                        )
+                    )
+            return span_results
+
+        def _yield_deduped(peptides: list[Peptide]) -> Generator[Peptide, None, None]:
+            for peptide in peptides:
+                key = str(peptide.proforma)
+                if key not in seen:
+                    seen.add(key)
+                    yield peptide
+
+        # Fully enzymatic peptides
+        for i in range(n_cuts - 1):
+            for j in range(i + 1, min(i + 2 + missed_cleavages, n_cuts)):
+                yield from _yield_deduped(_process_span(cut_sites[i], cut_sites[j], mc=j - i - 1, is_semi=False))
+
+        # Semi-enzymatic peptides (one free end)
+        if semi_enzymatic:
+            cut_set = set(cut_sites)
+            for enz_idx, enz_pos in enumerate(cut_sites):
+                # Right-open: enzymatic N-term, non-enzymatic C-term
+                for end in range(enz_pos + _min, seq_len + 1):
+                    if _max and (end - enz_pos) > _max:
+                        break
+                    if end in cut_set:
+                        continue
+                    mc = bisect_right(cut_sites, end - 1) - enz_idx - 1
+                    if mc <= missed_cleavages:
+                        yield from _yield_deduped(_process_span(enz_pos, end, mc=mc, is_semi=True))
+
+                # Left-open: non-enzymatic N-term, enzymatic C-term
+                for start in range(enz_pos - _min, -1, -1):
+                    if _max and (enz_pos - start) > _max:
+                        break
+                    if start in cut_set:
+                        continue
+                    mc = enz_idx - bisect_left(cut_sites, start + 1)
+                    if mc <= missed_cleavages:
+                        yield from _yield_deduped(_process_span(start, enz_pos, mc=mc, is_semi=True))
+
+
+def ann_to_map(ann: pt.ProFormaAnnotation) -> tuple[str, dict[int, str]]:
+
+    mod_map: dict[int, str] = {}
+
+    # Process C-terminal modifications
+    if ann._cterm_mods is not None:
+        for mod_name, count in ann._cterm_mods.items():
+            if count != 1:
+                raise ValueError("format does not support modification multipliers.")
+            mod_map[-2] = mod_name
+
+    # Process N-terminal modifications
+    if ann._nterm_mods is not None:
+        for mod_name, count in ann._nterm_mods.items():
+            if count != 1:
+                raise ValueError("format does not support modification multipliers.")
+            mod_map[-1] = mod_name
+
+    # Process internal modifications
+    if ann._internal_mods is not None:
+        for index, mods_dict in ann._internal_mods.items():
+            if len(mods_dict) > 1:
+                raise ValueError("format does not support multiple modifications at the same site.")
+            for mod_name, count in mods_dict.items():
+                if count != 1:
+                    raise ValueError("format does not support modification multipliers.")
+                mod_map[index] = mod_name
+
+    unmod_sequence = ann.stripped_sequence
+
+    return unmod_sequence, dict(sorted(mod_map.items()))

peff_digest/io.py

@@ -0,0 +1,195 @@
+"""File I/O, database caching, and multiprocessing worker functions."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+import pefftacular as pf
+import peptacular as pt
+from psimodpy import PsiModDatabase
+
+from peff_digest.config import DigestConfig
+from peff_digest.digest import _apply_mod, ann_to_map, digest_peff_sequence
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Lazy database loaders (cached per process for multiprocessing)
+# ---------------------------------------------------------------------------
+
+_PSI_DB: PsiModDatabase | None = None
+_UNI_DB = None
+
+
+def _get_psi_db() -> PsiModDatabase:
+    """Load the bundled PSI-MOD database once per process and cache it."""
+    global _PSI_DB
+    if _PSI_DB is None:
+        import psimodpy as _psimodpy
+
+        _PSI_DB = _psimodpy.load()
+    return _PSI_DB
+
+
+def _get_uni_db():
+    """Load the bundled UniMod database once per process and cache it."""
+    global _UNI_DB
+    if _UNI_DB is None:
+        import unimodpy as _unimodpy
+
+        _UNI_DB = _unimodpy.load()
+    return _UNI_DB
+
+
+# ---------------------------------------------------------------------------
+# PSI-MOD → UniMod conversion
+# ---------------------------------------------------------------------------
+
+
+def _try_convert_psimod_to_unimod(
+    ann: pt.ProFormaAnnotation,
+    psi_db: PsiModDatabase,
+    uni_db,
+) -> pt.ProFormaAnnotation | None:
+    """Replace MOD:NNNNN tags with UNIMOD:N accessions.
+
+    Returns None if any PSI-MOD mod has no UniMod xref — the caller should drop the peptide.
+    Non-PSI-MOD tags (user-added mods) are passed through unchanged.
+    """
+    sequence, mod_map = ann_to_map(ann)
+    new_mod_map: dict[int, str] = {}
+    for pos, tag in mod_map.items():
+        if tag.startswith("MOD:"):
+            psi_entry = psi_db.get_by_id(tag)
+            if psi_entry is None or not psi_entry.xref_unimod:
+                return None
+            try:
+                unimod_id = int(psi_entry.xref_unimod.replace("Unimod:", "").split("#")[0])
+            except ValueError:
+                return None
+            if uni_db.get_by_id(unimod_id) is None:
+                return None
+            new_mod_map[pos] = f"UNIMOD:{unimod_id}"
+        else:
+            new_mod_map[pos] = tag
+    new_ann = pt.parse(sequence)
+    seq_len = len(sequence)
+    for pos, tag in new_mod_map.items():
+        _apply_mod(new_ann, pos, tag, seq_len)
+    return new_ann
+
+
+# ---------------------------------------------------------------------------
+# File reading (PEFF and FASTA)
+# ---------------------------------------------------------------------------
+
+_FASTA_EXTENSIONS = {".fasta", ".fa", ".faa", ".fas"}
+
+
+def _iter_fasta(path: str):
+    """Yield (header, sequence) pairs from a FASTA file."""
+    header = None
+    chunks: list[str] = []
+    with open(path) as f:
+        for line in f:
+            line = line.rstrip()
+            if line.startswith(">"):
+                if header is not None:
+                    yield header, "".join(chunks)
+                header = line[1:]
+                chunks = []
+            elif header is not None:
+                chunks.append(line)
+    if header is not None:
+        yield header, "".join(chunks)
+
+
+def _fasta_to_entry(header: str, sequence: str) -> pf.SequenceEntry:
+    """Convert a FASTA record to a minimal SequenceEntry."""
+    first_token = header.split()[0]
+    parts = first_token.split("|")
+    if len(parts) >= 3:
+        prefix, db_unique_id = parts[0], parts[1]
+    else:
+        prefix, db_unique_id = "", first_token
+    return pf.SequenceEntry(prefix=prefix, db_unique_id=db_unique_id, sequence=sequence)
+
+
+def read_sequences(path: str) -> tuple[list[pf.SequenceEntry], int]:
+    """Read sequences from a PEFF or FASTA file. Returns (entries, n_malformed)."""
+    sequences: list[pf.SequenceEntry] = []
+    n_malformed = 0
+    if Path(path).suffix.lower() in _FASTA_EXTENSIONS:
+        for header, seq in _iter_fasta(path):
+            try:
+                sequences.append(_fasta_to_entry(header, seq))
+            except Exception:
+                n_malformed += 1
+                logger.warning("Skipping malformed FASTA entry: %s", header.split()[0] if header else "<unknown>")
+    else:
+        reader = iter(pf.PeffReader(path))
+        while True:
+            try:
+                sequences.append(next(reader))
+            except StopIteration:
+                break
+            except Exception:
+                n_malformed += 1
+                logger.warning("Skipping malformed PEFF entry at position %d", len(sequences) + n_malformed)
+    return sequences, n_malformed
+
+
+# ---------------------------------------------------------------------------
+# Multiprocessing worker functions
+# ---------------------------------------------------------------------------
+
+
+def _format_variant(variant: pf.VariantSimple | pf.VariantComplex | None) -> str | None:
+    """Format a variant object as a PEFF-notation string for output."""
+    if variant is None:
+        return None
+    if isinstance(variant, pf.VariantSimple):
+        return f"({variant.position}|{variant.new_amino_acid})"
+    return f"({variant.start_pos}|{variant.end_pos}|{variant.new_sequence})"
+
+
+def _digest_worker(
+    sequence: pf.SequenceEntry,
+    config: DigestConfig,
+) -> list[tuple[str, str, str | None, int, float | None]]:
+    psi_db = _get_psi_db() if config.use_psi_mods else None
+    protein_id = sequence.db_unique_id
+    peptides = digest_peff_sequence(sequence, config, psi_db=psi_db)
+    rows = []
+    for peptide in peptides:
+        ann = peptide.proforma
+        variant_str = _format_variant(peptide.variant)
+        if config.use_unimod_output:
+            ann = _try_convert_psimod_to_unimod(ann, _get_psi_db(), _get_uni_db())
+            if ann is None:
+                continue
+        try:
+            mass = ann.mass()
+        except Exception:
+            mass = None
+        if mass is None:
+            logger.debug("Could not compute mass for peptide %s (protein %s)", str(ann), protein_id)
+        if mass is None and config.drop_invalid_mass:
+            continue
+        if mass is not None and config.min_mass is not None and mass < config.min_mass:
+            continue
+        if mass is not None and config.max_mass is not None and mass > config.max_mass:
+            continue
+        rows.append((protein_id, str(ann), variant_str, len(ann), mass))
+    return rows
+
+
+def _digest_batch_worker(
+    batch: list[pf.SequenceEntry],
+    config: DigestConfig,
+) -> list[tuple[str, str, str | None, int, float | None]]:
+    rows = []
+    for sequence in batch:
+        rows.extend(_digest_worker(sequence, config))
+    return rows

peff_digest-0.1.0.dist-info/METADATA

@@ -0,0 +1,235 @@
+Metadata-Version: 2.4
+Name: peff_digest
+Version: 0.1.0
+Summary: PEFF-aware in-silico protein digestion with PTM enumeration, sequence variants, and ProForma output.
+Author-email: Patrick Garrett <pgarrett@scripps.edu>
+Maintainer-email: Patrick Garrett <pgarrett@scripps.edu>
+License: MIT
+Keywords: PEFF,PTM,ProForma,bioinformatics,digestion,peptide,proteomics
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: pefftacular>=0.1.0
+Requires-Dist: peptacular>=3.1.0
+Requires-Dist: polars>=1.0
+Requires-Dist: psimodpy
+Requires-Dist: pydantic>=2.0
+Requires-Dist: tomli-w>=1.0
+Requires-Dist: tqdm>=4.67.3
+Requires-Dist: unimodpy
+Requires-Dist: uniprotptmpy
+Description-Content-Type: text/markdown
+
+# peff_digest
+
+A PEFF-aware protein digest tool. Given a PEFF file and enzymatic digestion parameters, produces a CSV of peptides with their sequence (ProForma notation), variant annotation, length, and monoisotopic mass.
+
+Each PEFF `VariantSimple` and `VariantComplex` annotation is applied independently (not combined). PEFF PTMs (`ModResPsi` / `ModResUnimod`) are applied combinatorially up to a configurable limit per peptide. Fixed and variable user-defined modifications — including terminal modifications — are also supported.
+
+## Installation
+
+```bash
+uv sync
+# or
+just install
+```
+
+Requires Python 3.12+.
+
+## Usage
+
+### Via config file
+
+```bash
+peff-digest --config config.toml
+```
+
+### Via flags
+
+```bash
+peff-digest --peff-file human.peff --output-file peptides.csv
+```
+
+Flags override any values set in `--config`. Run `peff-digest --help` for the full flag reference.
+
+### Output
+
+The output CSV has five columns:
+
+| Column | Description |
+|---|---|
+| `protein_id` | `db_unique_id` from the PEFF header |
+| `sequence` | ProForma-annotated peptide sequence (includes mods) |
+| `variant` | PEFF variant notation, e.g. `(42\|R)`, or empty for canonical |
+| `length` | Peptide length in residues |
+| `mass` | Monoisotopic mass in Da, or empty if not computable |
+
+## Config reference
+
+All options can be set in a TOML or JSON config file. TOML example:
+
+```toml
+peff_file = "human.peff"
+output_file = "peptides.csv"
+
+cleave_on = "KR"
+missed_cleavages = 2
+semi_enzymatic = false
+max_ptm_per_peptide = 2
+min_length = 7
+max_length = 40
+restrict_after = "P"
+restrict_before = ""
+cterminal = true
+min_mass = 400.0
+max_mass = 10000.0
+drop_invalid_mass = false
+annotate_variants = true
+
+# Internal modifications — one [[internal_mods]] block per mod:
+# [[internal_mods]]
+# modification = "Carbamidomethyl"
+# residue = "C"
+# mod_type = "fixed"
+#
+# [[internal_mods]]
+# modification = "Oxidation"
+# residue = "M"
+# mod_type = "variable"
+
+# Terminal modifications — one [[terminal_mods]] block per mod:
+# [[terminal_mods]]
+# modification = "Acetyl"
+# position = "nterm"
+# mod_type = "variable"
+# protein_terminus = true   # only the first peptide of each protein
+#
+# [[terminal_mods]]
+# modification = "UNIMOD:737"
+# position = "nterm"
+# mod_type = "fixed"
+# residue = "M"             # only if the terminal residue is M
+#
+# [[terminal_mods]]
+# modification = "Amidated"
+# position = "cterm"
+# mod_type = "variable"
+```
+
+### `DigestConfig` fields
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `peff_file` | `str` | required | Path to the input PEFF file. Must exist. |
+| `output_file` | `str` | `"peptides.csv"` | Path for the output CSV. |
+| `cleave_on` | `str` | `"KR"` | Amino acids at which to cleave (e.g. `"KR"` for trypsin). |
+| `missed_cleavages` | `int` | `2` | Maximum number of missed cleavage sites per peptide. Min 0. |
+| `semi_enzymatic` | `bool` | `false` | Include semi-enzymatic peptides (one non-enzymatic terminus). |
+| `max_ptm_per_peptide` | `int` | `2` | Maximum number of variable mods (PEFF + user) applied simultaneously per peptide. `0` disables all variable mods. Min 0. |
+| `min_length` | `int` | `7` | Minimum peptide length in residues (inclusive). Min 1. |
+| `max_length` | `int` | `40` | Maximum peptide length in residues (inclusive). Min 1. |
+| `restrict_after` | `str` | `"P"` | Skip cleavage when the following residue is in this set (e.g. `"P"` for trypsin/Pro rule). |
+| `restrict_before` | `str` | `""` | Skip cleavage when the preceding residue is in this set. |
+| `cterminal` | `bool` | `true` | `true` = C-terminal cleavage (standard); `false` = N-terminal. |
+| `internal_mods` | `list[InternalMod]` | `[]` | Per-residue modifications. See `InternalMod` fields below. |
+| `terminal_mods` | `list[TerminalMod]` | `[]` | Terminal modifications. See `TerminalMod` fields below. |
+| `min_mass` | `float \| None` | `None` | Minimum peptide mass in Da. Ignored if `None`. |
+| `max_mass` | `float \| None` | `None` | Maximum peptide mass in Da. Ignored if `None`. |
+| `drop_invalid_mass` | `bool` | `false` | If `true`, exclude peptides whose mass cannot be computed. |
+| `annotate_variants` | `bool` | `true` | If `false`, do not set `peptide_name` on variant peptides. |
+| `workers` | `int \| None` | `None` | Number of worker processes. Defaults to all available CPUs. Min 1. |
+
+### `InternalMod` fields
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `modification` | `str` | required | Modification name (e.g. `"Carbamidomethyl"`, `"UNIMOD:21"`). |
+| `residue` | `str` | required | One or more amino acids the mod applies to (e.g. `"C"` or `"KR"`). |
+| `mod_type` | `"fixed" \| "variable"` | required | `"fixed"` = always applied; `"variable"` = enumerated combinatorially (counts against `max_ptm_per_peptide`). |
+
+### `TerminalMod` fields
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `modification` | `str` | required | Modification name (e.g. `"Acetyl"`, `"UNIMOD:737"`). |
+| `position` | `"nterm" \| "cterm"` | required | Which terminus to apply the mod to. |
+| `mod_type` | `"fixed" \| "variable"` | required | `"fixed"` = always applied; `"variable"` = enumerated combinatorially (counts against `max_ptm_per_peptide`). |
+| `residue` | `str \| None` | `None` | If set, the mod is only applied when the terminal residue is in this string (e.g. `"M"` or `"KR"`). |
+| `protein_terminus` | `bool` | `false` | If `true`, only apply to the protein-level terminus (first peptide for N-term, last for C-term). |
+
+## Python API
+
+### Full digest → Polars DataFrame
+
+```python
+from peff_digest import DigestConfig, InternalMod, TerminalMod, digest
+
+config = DigestConfig(
+    peff_file="human.peff",
+    missed_cleavages=2,
+    min_length=7,
+    max_length=40,
+    min_mass=400.0,
+    max_mass=10000.0,
+    drop_invalid_mass=True,
+    internal_mods=[
+        InternalMod(modification="Carbamidomethyl", residue="C", mod_type="fixed"),
+        InternalMod(modification="Oxidation", residue="M", mod_type="variable"),
+    ],
+    terminal_mods=[
+        TerminalMod(modification="Acetyl", position="nterm", mod_type="variable", protein_terminus=True),
+    ],
+)
+
+df = digest(config)
+print(df)
+```
+
+Returns a `polars.DataFrame` with columns `protein_id`, `sequence`, `variant`, `length`, `mass`. All filtering from the config (mass bounds, `drop_invalid_mass`) is applied before returning.
+
+### Single-entry digest
+
+```python
+import pefftacular as pf
+from peff_digest import InternalMod, TerminalMod, digest_peff_sequence
+
+entry = next(iter(pf.PeffReader("human.peff")))
+
+peptides = digest_peff_sequence(
+    entry,
+    cleave_on="KR",
+    missed_cleavages=2,
+    min_length=7,
+    max_length=40,
+    restrict_after="P",
+    internal_mods=[
+        InternalMod(modification="Carbamidomethyl", residue="C", mod_type="fixed"),
+        InternalMod(modification="Oxidation", residue="M", mod_type="variable"),
+    ],
+    max_ptm_per_peptide=2,
+    terminal_mods=[
+        TerminalMod(modification="Acetyl", position="nterm", mod_type="variable", protein_terminus=True),
+        TerminalMod(modification="Amidated", position="cterm", mod_type="variable"),
+    ],
+)
+
+for peptide in peptides:
+    print(str(peptide), len(peptide), peptide.mass())
+```
+
+Returns a `set[peptacular.ProFormaAnnotation]`. Each element supports `len()`, `.mass()`, `str()`, and `.peptide_name` (PEFF variant notation, or `None` for canonical).
+
+## Development
+
+```bash
+just lint      # ruff check
+just format    # ruff format + import sort
+just test      # pytest
+just check     # lint + type check (ty) + test
+```

peff_digest-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+peff_digest/__init__.py,sha256=EKvVEONc3vG7_0t7xTZ2cTYqOW6lww2R_R0R4cJgPzY,418
+peff_digest/api.py,sha256=U_hE8xn_qRWWgtndBTcXDUJ8_7DfS1Hyw4Q6t-6UYrA,3724
+peff_digest/cli.py,sha256=qLVXbLE0V4-Sb5nJPWd2jjHMGHDX73k_PPxUr3CFS8Q,4239
+peff_digest/config.py,sha256=2259cUKziryeci8D4HbNcL6nOW-ELLVUlTQbxwstd20,2768
+peff_digest/digest.py,sha256=x4vXqlSXemOoEscqNoXWD5AwPzY-cWQQGNgz3rH4Mus,22986
+peff_digest/io.py,sha256=pF_Fbh3INTaO9iKlzSO7JYAf7dtPXxQ5OVi4OPyUMG0,6759
+peff_digest-0.1.0.dist-info/METADATA,sha256=rNHTcKK2dxEEyPJ1gTN5DgRxPWGdF7x1hA5hK6hduyE,8639
+peff_digest-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+peff_digest-0.1.0.dist-info/entry_points.txt,sha256=PwjwCI63wRekkTDOKcNpcGInXIcjV0O1AOyTtM6KOtQ,53
+peff_digest-0.1.0.dist-info/RECORD,,

peff_digest-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

peff_digest-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+peff-digest = peff_digest.cli:main