prozor 0.1.0__tar.gz

prozor-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Witold Wolski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

prozor-0.1.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: prozor
+Version: 0.1.0
+Summary: Typed peptide-to-protein matching and parsimonious protein inference
+Keywords: proteomics,protein inference,peptide matching,mass spectrometry
+Author: Witold Wolski
+Author-email: Witold Wolski <wew@fgcz.ethz.ch>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+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: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Typing :: Typed
+Requires-Dist: ahocorapy>=1.6,<2
+Requires-Dist: ahocorasick-rs>=1.0,<2
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/anndata-omics-bridge/prozor
+Project-URL: Documentation, https://anndata-omics-bridge.github.io/prozor/
+Project-URL: Repository, https://github.com/anndata-omics-bridge/prozor.git
+Project-URL: Issues, https://github.com/anndata-omics-bridge/prozor/issues
+Description-Content-Type: text/markdown
+
+# Prozor
+
+[![Quality](https://github.com/anndata-omics-bridge/prozor/actions/workflows/quality.yml/badge.svg)](https://github.com/anndata-omics-bridge/prozor/actions/workflows/quality.yml)
+[![Documentation](https://github.com/anndata-omics-bridge/prozor/actions/workflows/docs.yml/badge.svg)](https://anndata-omics-bridge.github.io/prozor/)
+[![Python](https://img.shields.io/badge/Python-%E2%89%A53.12-3776AB.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://spdx.org/licenses/MIT.html)
+
+Typed peptide-to-protein matching and deterministic greedy-parsimony protein
+inference.
+
+This repository is a Python port of the R [`prozor`](https://github.com/protViz/prozor) package.
+
+Prozor offers backend-neutral Aho--Corasick matching over mappings or streaming
+protein records, occurrence-level annotations, unique peptide--protein edges,
+and deterministic protein inference. The core deliberately does not
+parse FASTA files or depend on pandas, AnnData, MuData, MuLink, workflow engines,
+or consumer CLIs.
+
+**[Documentation](https://anndata-omics-bridge.github.io/prozor/)** ·
+**[Getting started](https://anndata-omics-bridge.github.io/prozor/getting-started/)** ·
+**[API reference](https://anndata-omics-bridge.github.io/prozor/api/)**
+
+Documentation: <https://anndata-omics-bridge.github.io/prozor/>
+
+## Installation
+
+```bash
+python -m pip install prozor
+```
+
+Both matching implementations are installed. The public matching operations
+default to `backend="auto"`, which selects `ahocorasick_rs`. The portable
+`ahocorapy` implementation remains directly selectable and is the automatic
+runtime fallback if Rust cannot be imported. Results record both the requested
+and concrete backend.
+
+## Quick start
+
+```python
+from dataclasses import dataclass
+
+from prozor.api import annotate_peptides_streaming, greedy_parsimony
+
+
+@dataclass(frozen=True, slots=True)
+class Protein:
+    id: str
+    sequence: str
+
+
+matches = annotate_peptides_streaming(
+    ["PEPTIDE", "SEQUENCE"],
+    [
+        Protein("P1", "MYPEPTIDESEQUENCE"),
+        Protein("P2", "XXSEQUENCEXX"),
+    ],
+)
+
+for match in matches:
+    print(match.peptide, match.protein_id, match.start, match.end)
+
+edges = {(match.peptide, match.protein_id) for match in matches}
+protein_groups = greedy_parsimony(edges)
+print(protein_groups.to_dict())
+```
+
+Matches include nested, overlapping, and repeated sites using half-open
+coordinates. Prozor matches the exact strings supplied by the consumer; FASTA
+header interpretation, normalization, decoy classification, and persistence
+remain application policy.
+
+## Development
+
+```bash
+uv sync --group dev --group docs
+.venv/bin/pre-commit install --hook-type pre-commit --hook-type pre-push
+make check
+```
+
+`make check` runs Ruff, strict Pyright, dependency validation, branch-coverage
+tests, a strict documentation build, and wheel/sdist validation. All Python
+commands run from the synchronized project `.venv`.
+
+## Provenance and license
+
+This implementation ports the algorithmic behavior of the R [`prozor`](https://github.com/protViz/prozor) package and consolidates the matching and inference core for Python consumers such as APB and `diann_runner`.
+
+The Python distribution is an independent implementation of that algorithm
+rather than a translation of the R source, and it is licensed under MIT. The R
+reference package remains GPL-3, and its license does not extend here: the
+copyright holder of both packages is the same author, and algorithms are not
+themselves subject to copyright.
+
+MIT keeps the whole anndata-omics-bridge spine under one permissive license, so
+that consumers such as APB can be redistributed without inheriting copyleft
+obligations from this package.

prozor-0.1.0/README.md

@@ -0,0 +1,96 @@
+# Prozor
+
+[![Quality](https://github.com/anndata-omics-bridge/prozor/actions/workflows/quality.yml/badge.svg)](https://github.com/anndata-omics-bridge/prozor/actions/workflows/quality.yml)
+[![Documentation](https://github.com/anndata-omics-bridge/prozor/actions/workflows/docs.yml/badge.svg)](https://anndata-omics-bridge.github.io/prozor/)
+[![Python](https://img.shields.io/badge/Python-%E2%89%A53.12-3776AB.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://spdx.org/licenses/MIT.html)
+
+Typed peptide-to-protein matching and deterministic greedy-parsimony protein
+inference.
+
+This repository is a Python port of the R [`prozor`](https://github.com/protViz/prozor) package.
+
+Prozor offers backend-neutral Aho--Corasick matching over mappings or streaming
+protein records, occurrence-level annotations, unique peptide--protein edges,
+and deterministic protein inference. The core deliberately does not
+parse FASTA files or depend on pandas, AnnData, MuData, MuLink, workflow engines,
+or consumer CLIs.
+
+**[Documentation](https://anndata-omics-bridge.github.io/prozor/)** ·
+**[Getting started](https://anndata-omics-bridge.github.io/prozor/getting-started/)** ·
+**[API reference](https://anndata-omics-bridge.github.io/prozor/api/)**
+
+Documentation: <https://anndata-omics-bridge.github.io/prozor/>
+
+## Installation
+
+```bash
+python -m pip install prozor
+```
+
+Both matching implementations are installed. The public matching operations
+default to `backend="auto"`, which selects `ahocorasick_rs`. The portable
+`ahocorapy` implementation remains directly selectable and is the automatic
+runtime fallback if Rust cannot be imported. Results record both the requested
+and concrete backend.
+
+## Quick start
+
+```python
+from dataclasses import dataclass
+
+from prozor.api import annotate_peptides_streaming, greedy_parsimony
+
+
+@dataclass(frozen=True, slots=True)
+class Protein:
+    id: str
+    sequence: str
+
+
+matches = annotate_peptides_streaming(
+    ["PEPTIDE", "SEQUENCE"],
+    [
+        Protein("P1", "MYPEPTIDESEQUENCE"),
+        Protein("P2", "XXSEQUENCEXX"),
+    ],
+)
+
+for match in matches:
+    print(match.peptide, match.protein_id, match.start, match.end)
+
+edges = {(match.peptide, match.protein_id) for match in matches}
+protein_groups = greedy_parsimony(edges)
+print(protein_groups.to_dict())
+```
+
+Matches include nested, overlapping, and repeated sites using half-open
+coordinates. Prozor matches the exact strings supplied by the consumer; FASTA
+header interpretation, normalization, decoy classification, and persistence
+remain application policy.
+
+## Development
+
+```bash
+uv sync --group dev --group docs
+.venv/bin/pre-commit install --hook-type pre-commit --hook-type pre-push
+make check
+```
+
+`make check` runs Ruff, strict Pyright, dependency validation, branch-coverage
+tests, a strict documentation build, and wheel/sdist validation. All Python
+commands run from the synchronized project `.venv`.
+
+## Provenance and license
+
+This implementation ports the algorithmic behavior of the R [`prozor`](https://github.com/protViz/prozor) package and consolidates the matching and inference core for Python consumers such as APB and `diann_runner`.
+
+The Python distribution is an independent implementation of that algorithm
+rather than a translation of the R source, and it is licensed under MIT. The R
+reference package remains GPL-3, and its license does not extend here: the
+copyright holder of both packages is the same author, and algorithms are not
+themselves subject to copyright.
+
+MIT keeps the whole anndata-omics-bridge spine under one permissive license, so
+that consumers such as APB can be redistributed without inheriting copyleft
+obligations from this package.

prozor-0.1.0/pyproject.toml

@@ -0,0 +1,142 @@
+[build-system]
+requires = ["uv_build>=0.9.26,<0.10.0"]
+build-backend = "uv_build"
+
+[project]
+name = "prozor"
+version = "0.1.0"
+description = "Typed peptide-to-protein matching and parsimonious protein inference"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "proteomics",
+    "protein inference",
+    "peptide matching",
+    "mass spectrometry",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+    "Typing :: Typed",
+]
+dependencies = [
+    "ahocorapy>=1.6,<2",
+    "ahocorasick-rs>=1.0,<2",
+]
+
+[[project.authors]]
+name = "Witold Wolski"
+email = "wew@fgcz.ethz.ch"
+
+[project.urls]
+Homepage = "https://github.com/anndata-omics-bridge/prozor"
+Documentation = "https://anndata-omics-bridge.github.io/prozor/"
+Repository = "https://github.com/anndata-omics-bridge/prozor.git"
+Issues = "https://github.com/anndata-omics-bridge/prozor/issues"
+
+[tool.uv]
+default-groups = [
+    "dev",
+    "docs",
+]
+
+[tool.uv.sources.carpet-scan]
+git = "https://github.com/anndata-omics-bridge/carpet_scan"
+rev = "a98f45d21884a95fa79b7660b153bbadb9268e03"
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+src = [
+    "src",
+    "tests",
+    "benchmarks",
+]
+
+[tool.ruff.lint]
+select = [
+    "ANN",
+    "B",
+    "C4",
+    "C90",
+    "E4",
+    "E7",
+    "E9",
+    "F",
+    "I",
+    "PGH",
+    "PIE",
+    "RUF",
+    "SIM",
+    "UP",
+]
+
+[tool.ruff.lint.mccabe]
+max-complexity = 10
+
+[tool.ruff.format]
+docstring-code-format = true
+
+[tool.pyright]
+include = [
+    "src",
+    "tests",
+    "benchmarks",
+]
+stubPath = "typings"
+venvPath = "."
+venv = ".venv"
+pythonVersion = "3.12"
+typeCheckingMode = "strict"
+reportImportCycles = "error"
+reportMissingTypeStubs = "error"
+reportUnnecessaryTypeIgnoreComment = "error"
+reportImplicitOverride = "error"
+enableTypeIgnoreComments = false
+
+[tool.pytest.ini_options]
+addopts = [
+    "--strict-config",
+    "--strict-markers",
+    "-ra",
+]
+testpaths = ["tests"]
+xfail_strict = true
+
+[tool.coverage.run]
+branch = true
+source = ["prozor"]
+
+[tool.coverage.report]
+fail_under = 80
+show_missing = true
+skip_covered = true
+
+[tool.deptry]
+known_first_party = ["prozor"]
+
+[dependency-groups]
+dev = [
+    "carpet-scan",
+    "build>=1.3,<2",
+    "deptry>=0.24,<1",
+    "import-linter>=2.8,<3",
+    "pre-commit>=4,<5",
+    "pyright>=1.1.400,<2",
+    "pytest>=9,<10",
+    "pytest-cov>=7,<8",
+    "ruff>=0.15,<1",
+    "twine>=6,<7",
+]
+docs = [
+    "mkdocstrings[python]>=1.0,<2",
+    "pymdown-extensions>=11,<12",
+    "zensical==0.0.43",
+]

prozor-0.1.0/pyproject.toml.orig

@@ -0,0 +1,122 @@
+[build-system]
+requires = ["uv_build>=0.9.26,<0.10.0"]
+build-backend = "uv_build"
+
+[project]
+name = "prozor"
+version = "0.1.0"
+description = "Typed peptide-to-protein matching and parsimonious protein inference"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Witold Wolski", email = "wew@fgcz.ethz.ch" },
+]
+keywords = ["proteomics", "protein inference", "peptide matching", "mass spectrometry"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+    "Typing :: Typed",
+]
+dependencies = [
+    "ahocorapy>=1.6,<2",
+    "ahocorasick-rs>=1.0,<2",
+]
+
+[project.urls]
+Homepage = "https://github.com/anndata-omics-bridge/prozor"
+Documentation = "https://anndata-omics-bridge.github.io/prozor/"
+Repository = "https://github.com/anndata-omics-bridge/prozor.git"
+Issues = "https://github.com/anndata-omics-bridge/prozor/issues"
+
+[tool.uv.sources]
+carpet-scan = { git = "https://github.com/anndata-omics-bridge/carpet_scan", rev = "a98f45d21884a95fa79b7660b153bbadb9268e03" }
+
+[dependency-groups]
+dev = [
+    # Carpet diagnostics. Must live in Prozor's own environment rather than an isolated `uvx` one,
+    # because grimp resolves the target package through the Python path.
+    "carpet-scan",
+    "build>=1.3,<2",
+    "deptry>=0.24,<1",
+    "import-linter>=2.8,<3",
+    "pre-commit>=4,<5",
+    "pyright>=1.1.400,<2",
+    "pytest>=9,<10",
+    "pytest-cov>=7,<8",
+    "ruff>=0.15,<1",
+    "twine>=6,<7",
+]
+docs = [
+    "mkdocstrings[python]>=1.0,<2",
+    "pymdown-extensions>=11,<12",
+    "zensical==0.0.43",
+]
+
+[tool.uv]
+default-groups = ["dev", "docs"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+src = ["src", "tests", "benchmarks"]
+
+[tool.ruff.lint]
+select = [
+    "ANN",
+    "B",
+    "C4",
+    "C90",
+    "E4",
+    "E7",
+    "E9",
+    "F",
+    "I",
+    "PGH",
+    "PIE",
+    "RUF",
+    "SIM",
+    "UP",
+]
+
+[tool.ruff.lint.mccabe]
+max-complexity = 10
+
+[tool.ruff.format]
+docstring-code-format = true
+
+[tool.pyright]
+include = ["src", "tests", "benchmarks"]
+stubPath = "typings"
+venvPath = "."
+venv = ".venv"
+pythonVersion = "3.12"
+typeCheckingMode = "strict"
+reportImportCycles = "error"
+reportMissingTypeStubs = "error"
+reportUnnecessaryTypeIgnoreComment = "error"
+reportImplicitOverride = "error"
+enableTypeIgnoreComments = false
+
+[tool.pytest.ini_options]
+addopts = ["--strict-config", "--strict-markers", "-ra"]
+testpaths = ["tests"]
+xfail_strict = true
+
+[tool.coverage.run]
+branch = true
+source = ["prozor"]
+
+[tool.coverage.report]
+fail_under = 80
+show_missing = true
+skip_covered = true
+
+[tool.deptry]
+known_first_party = ["prozor"]

prozor-0.1.0/src/prozor/__init__.py

@@ -0,0 +1 @@
+

prozor-0.1.0/src/prozor/api.py

@@ -0,0 +1,21 @@
+"""The one public prozor module for other anndata_bridge packages."""
+
+from __future__ import annotations
+
+from prozor.inference.greedy import greedy_parsimony
+from prozor.inference.ties import TieCandidate
+from prozor.matching.annotation import (
+    ProteinSequenceRecord,
+    annotate_peptides,
+    annotate_peptides_streaming,
+)
+from prozor.matching.automaton import resolve_backend
+
+__all__ = [
+    "ProteinSequenceRecord",
+    "TieCandidate",
+    "annotate_peptides",
+    "annotate_peptides_streaming",
+    "greedy_parsimony",
+    "resolve_backend",
+]

prozor-0.1.0/src/prozor/inference/greedy.py

@@ -0,0 +1,330 @@
+"""Deterministic greedy-parsimony protein inference over unique edges."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator, Sequence
+from dataclasses import dataclass
+
+from prozor.inference.ties import (
+    TieCandidate,
+    TieResolver,
+    resolve_current_tie,
+)
+
+type PeptideProteinEdge = tuple[str, str]
+
+
+@dataclass(slots=True)
+class ProteinGroup:
+    """Proteins selected together and the peptides assigned to them."""
+
+    proteins: list[str]
+    peptides: list[str]
+
+    @property
+    def protein_id(self) -> str:
+        """Return the semicolon-joined protein group identifier."""
+        return ";".join(self.proteins)
+
+    @property
+    def n_peptides(self) -> int:
+        """Return the number of assigned peptides."""
+        return len(self.peptides)
+
+    @property
+    def n_proteins(self) -> int:
+        """Return the number of grouped proteins."""
+        return len(self.proteins)
+
+
+@dataclass(slots=True)
+class GreedyResult:
+    """Protein groups selected by greedy parsimony."""
+
+    groups: list[ProteinGroup]
+
+    def __len__(self) -> int:
+        return len(self.groups)
+
+    def __iter__(self) -> Iterator[ProteinGroup]:
+        return iter(self.groups)
+
+    @property
+    def n_proteins(self) -> int:
+        """Return the total number of selected and subsumed proteins."""
+        return sum(group.n_proteins for group in self.groups)
+
+    @property
+    def n_groups(self) -> int:
+        """Return the number of inferred protein groups."""
+        return len(self.groups)
+
+    @property
+    def n_peptides(self) -> int:
+        """Return the number of distinct assigned peptides."""
+        return len({peptide for group in self.groups for peptide in group.peptides})
+
+    def to_dict(self) -> dict[str, str]:
+        """Return a peptide-to-protein-group mapping."""
+        return {peptide: group.protein_id for group in self.groups for peptide in group.peptides}
+
+
+@dataclass(frozen=True, slots=True)
+class _Selection:
+    winners: tuple[int, ...]
+    covered_peptides: frozenset[int]
+
+
+def greedy_parsimony(
+    edges: Iterable[PeptideProteinEdge],
+    resolve_tie: TieResolver = resolve_current_tie,
+    subsume: bool = True,
+) -> GreedyResult:
+    """Select a deterministic parsimonious set of protein groups.
+
+    Repeated ``(peptide, protein)`` edges collapse before inference. Proteins
+    with identical remaining peptide evidence are grouped. Disjoint equal
+    candidates are ordered deterministically, while overlapping non-identical
+    candidates are passed to ``resolve_tie``.
+
+    Args:
+        edges: Peptide and protein identifier pairs.
+        resolve_tie: Operation selecting one consequential tie candidate.
+        subsume: Whether proteins supported by a subset of selected evidence
+            remain in the selected group.
+
+    Returns:
+        Deterministically ordered inferred protein groups.
+    """
+    peptides, proteins, peptide_proteins, protein_peptides = _build_incidence(edges)
+    active_peptides = set(range(len(peptides)))
+    active_proteins = set(range(len(proteins)))
+    counts = [len(protein_evidence) for protein_evidence in protein_peptides]
+    groups: list[ProteinGroup] = []
+
+    while active_peptides and active_proteins:
+        selections = _select_winners(
+            active_peptides,
+            active_proteins,
+            protein_peptides,
+            counts,
+            peptides,
+            proteins,
+            resolve_tie,
+        )
+        if not selections:
+            break
+        for selection in selections:
+            subsumed = (
+                _find_subsumed(
+                    selection,
+                    active_peptides,
+                    active_proteins,
+                    peptide_proteins,
+                    protein_peptides,
+                )
+                if subsume
+                else ()
+            )
+            group_indices = tuple(sorted((*selection.winners, *subsumed)))
+            groups.append(
+                ProteinGroup(
+                    proteins=sorted(proteins[index] for index in group_indices),
+                    peptides=sorted(peptides[index] for index in selection.covered_peptides),
+                )
+            )
+            active_peptides.difference_update(selection.covered_peptides)
+            active_proteins.difference_update(group_indices)
+            _decrement_counts(
+                selection.covered_peptides,
+                active_proteins,
+                peptide_proteins,
+                counts,
+            )
+
+    groups.sort(
+        key=lambda group: (
+            -group.n_peptides,
+            -group.n_proteins,
+            tuple(group.proteins),
+        )
+    )
+    return GreedyResult(groups=groups)
+
+
+def _build_incidence(
+    edges: Iterable[PeptideProteinEdge],
+) -> tuple[list[str], list[str], list[frozenset[int]], list[frozenset[int]]]:
+    unique_edges = set(edges)
+    peptides = sorted({peptide for peptide, _protein in unique_edges})
+    proteins = sorted({protein for _peptide, protein in unique_edges})
+    peptide_indices = {peptide: index for index, peptide in enumerate(peptides)}
+    protein_indices = {protein: index for index, protein in enumerate(proteins)}
+    peptide_proteins: list[set[int]] = [set() for _peptide in peptides]
+    protein_peptides: list[set[int]] = [set() for _protein in proteins]
+    for peptide, protein in unique_edges:
+        peptide_index = peptide_indices[peptide]
+        protein_index = protein_indices[protein]
+        peptide_proteins[peptide_index].add(protein_index)
+        protein_peptides[protein_index].add(peptide_index)
+    return (
+        peptides,
+        proteins,
+        [frozenset(indices) for indices in peptide_proteins],
+        [frozenset(indices) for indices in protein_peptides],
+    )
+
+
+def _select_winners(
+    active_peptides: set[int],
+    active_proteins: set[int],
+    protein_peptides: Sequence[frozenset[int]],
+    counts: Sequence[int],
+    peptide_names: Sequence[str],
+    protein_names: Sequence[str],
+    resolve_tie: TieResolver,
+) -> tuple[_Selection, ...]:
+    ordered_active = sorted(active_proteins)
+    if not ordered_active:
+        return ()
+    max_count = max(counts[index] for index in ordered_active)
+    if max_count == 0:
+        return ()
+    max_proteins = [index for index in ordered_active if counts[index] == max_count]
+    signature_groups: dict[frozenset[int], list[int]] = {}
+    for index in max_proteins:
+        signature = frozenset(protein_peptides[index] & active_peptides)
+        signature_groups.setdefault(signature, []).append(index)
+
+    grouped = tuple(
+        tuple(indices)
+        for _signature, indices in sorted(
+            signature_groups.items(),
+            key=lambda item: tuple(protein_names[index] for index in item[1]),
+        )
+    )
+    signatures = tuple(
+        frozenset(protein_peptides[indices[0]] & active_peptides) for indices in grouped
+    )
+    components = _overlap_components(signatures)
+    selections = [
+        _selection_for_component(
+            component,
+            grouped,
+            signatures,
+            peptide_names,
+            protein_names,
+            resolve_tie,
+        )
+        for component in components
+    ]
+    return tuple(sorted(selections, key=lambda selection: _selection_key(selection, protein_names)))
+
+
+def _selection_key(
+    selection: _Selection,
+    protein_names: Sequence[str],
+) -> tuple[int, tuple[str, ...]]:
+    return (
+        -len(selection.winners),
+        tuple(protein_names[index] for index in selection.winners),
+    )
+
+
+def _overlap_components(signatures: Sequence[frozenset[int]]) -> tuple[tuple[int, ...], ...]:
+    peptide_groups: dict[int, list[int]] = {}
+    for group_index, signature in enumerate(signatures):
+        for peptide in signature:
+            peptide_groups.setdefault(peptide, []).append(group_index)
+    unseen = set(range(len(signatures)))
+    components: list[tuple[int, ...]] = []
+    while unseen:
+        pending = [min(unseen)]
+        component: set[int] = set()
+        while pending:
+            group_index = pending.pop()
+            if group_index not in unseen:
+                continue
+            unseen.remove(group_index)
+            component.add(group_index)
+            for peptide in signatures[group_index]:
+                pending.extend(peptide_groups[peptide])
+        components.append(tuple(sorted(component)))
+    return tuple(components)
+
+
+def _selection_for_component(
+    component: tuple[int, ...],
+    groups: Sequence[tuple[int, ...]],
+    signatures: Sequence[frozenset[int]],
+    peptide_names: Sequence[str],
+    protein_names: Sequence[str],
+    resolve_tie: TieResolver,
+) -> _Selection:
+    component_groups = tuple(groups[index] for index in component)
+    component_signatures = tuple(signatures[index] for index in component)
+    winners = (
+        component_groups[0]
+        if len(component_groups) == 1
+        else _resolve_overlapping_tie(
+            component_groups,
+            component_signatures,
+            peptide_names,
+            protein_names,
+            resolve_tie,
+        )
+    )
+    winner_index = component_groups.index(winners)
+    return _Selection(winners=winners, covered_peptides=component_signatures[winner_index])
+
+
+def _resolve_overlapping_tie(
+    groups: Sequence[tuple[int, ...]],
+    signatures: Sequence[frozenset[int]],
+    peptide_names: Sequence[str],
+    protein_names: Sequence[str],
+    resolve_tie: TieResolver,
+) -> tuple[int, ...]:
+    candidates = tuple(
+        TieCandidate(
+            proteins=tuple(protein_names[index] for index in group),
+            unexplained_peptides=frozenset(peptide_names[index] for index in signature),
+        )
+        for group, signature in zip(groups, signatures, strict=True)
+    )
+    selected = resolve_tie(candidates)
+    try:
+        selected_index = candidates.index(selected)
+    except ValueError as error:
+        raise ValueError("tie resolver must return one of the candidates it received") from error
+    return groups[selected_index]
+
+
+def _find_subsumed(
+    selection: _Selection,
+    active_peptides: set[int],
+    active_proteins: set[int],
+    peptide_proteins: Sequence[frozenset[int]],
+    protein_peptides: Sequence[frozenset[int]],
+) -> tuple[int, ...]:
+    candidates = {
+        protein for peptide in selection.covered_peptides for protein in peptide_proteins[peptide]
+    }
+    candidates.difference_update(selection.winners)
+    candidates.intersection_update(active_proteins)
+    return tuple(
+        protein
+        for protein in sorted(candidates)
+        if protein_peptides[protein] & active_peptides <= selection.covered_peptides
+    )
+
+
+def _decrement_counts(
+    removed_peptides: frozenset[int],
+    active_proteins: set[int],
+    peptide_proteins: Sequence[frozenset[int]],
+    counts: list[int],
+) -> None:
+    for peptide in removed_peptides:
+        for protein in peptide_proteins[peptide] & active_proteins:
+            counts[protein] -= 1

prozor-0.1.0/src/prozor/inference/ties.py

@@ -0,0 +1,24 @@
+"""Tie candidates and resolution for greedy protein inference."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class TieCandidate:
+    """One indistinguishable protein group competing in a consequential tie."""
+
+    proteins: tuple[str, ...]
+    unexplained_peptides: frozenset[str]
+
+
+type TieResolver = Callable[[Sequence[TieCandidate]], TieCandidate]
+
+
+def resolve_current_tie(candidates: Sequence[TieCandidate]) -> TieCandidate:
+    """Preserve Prozor's deterministic group-size and accession tie rule."""
+    if not candidates:
+        raise ValueError("at least one tie candidate is required")
+    return min(candidates, key=lambda candidate: (-len(candidate.proteins), candidate.proteins))

prozor-0.1.0/src/prozor/matching/annotation.py

@@ -0,0 +1,168 @@
+"""Peptide-to-protein annotation over mappings or streaming protein records."""
+
+from __future__ import annotations
+
+from bisect import bisect_right
+from collections.abc import Iterable, Iterator, Mapping, Sequence
+from dataclasses import dataclass
+from itertools import accumulate, islice
+from typing import Protocol
+
+from prozor.matching.automaton import (
+    BackendName,
+    BackendRequest,
+    create_automaton,
+    resolve_backend,
+)
+
+_SEPARATOR = "\n"
+_BATCH_SIZE = 10_000
+
+
+class ProteinSequenceRecord(Protocol):
+    """Smallest protein-record capability required by peptide matching."""
+
+    @property
+    def id(self) -> str:
+        """Return the protein identifier attached to matching results."""
+        ...
+
+    @property
+    def sequence(self) -> str:
+        """Return the protein sequence to search."""
+        ...
+
+
+@dataclass(frozen=True, slots=True)
+class PeptideAnnotation:
+    """One peptide occurrence in a protein sequence."""
+
+    peptide: str
+    protein_id: str
+    start: int
+    end: int
+
+    @property
+    def length(self) -> int:
+        """Return the matched peptide length."""
+        return len(self.peptide)
+
+
+@dataclass(slots=True)
+class AnnotationResult:
+    """Collection of peptide matches and matching-backend provenance."""
+
+    annotations: list[PeptideAnnotation]
+    requested_backend: BackendRequest = "ahocorapy"
+    resolved_backend: BackendName = "ahocorapy"
+
+    def __len__(self) -> int:
+        return len(self.annotations)
+
+    def __iter__(self) -> Iterator[PeptideAnnotation]:
+        return iter(self.annotations)
+
+    @property
+    def peptides(self) -> set[str]:
+        """Return the distinct matched peptide sequences."""
+        return {annotation.peptide for annotation in self.annotations}
+
+    @property
+    def proteins(self) -> set[str]:
+        """Return the distinct matched protein identifiers."""
+        return {annotation.protein_id for annotation in self.annotations}
+
+    def filter_tryptic(
+        self,
+        proteins: Mapping[str, str],
+        prefix_residues: str = "RK",
+        allow_n_term: bool = True,
+        allow_after_init_met: bool = True,
+    ) -> AnnotationResult:
+        """Return matches with a supported tryptic N-terminal context."""
+        filtered: list[PeptideAnnotation] = []
+        for annotation in self.annotations:
+            sequence = proteins.get(annotation.protein_id, "")
+            if not sequence:
+                continue
+            valid_prefix = (
+                (annotation.start == 0 and allow_n_term)
+                or (annotation.start == 1 and allow_after_init_met and sequence.startswith("M"))
+                or (annotation.start > 0 and sequence[annotation.start - 1] in prefix_residues)
+            )
+            if valid_prefix:
+                filtered.append(annotation)
+        return AnnotationResult(
+            annotations=filtered,
+            requested_backend=self.requested_backend,
+            resolved_backend=self.resolved_backend,
+        )
+
+
+def annotate_peptides(
+    peptides: Iterable[str],
+    proteins: Mapping[str, str],
+    backend: str = "auto",
+    filter_tryptic: bool = False,
+) -> AnnotationResult:
+    """Annotate peptides against an in-memory protein mapping."""
+    result = _annotate(peptides, [(tuple(proteins), tuple(proteins.values()))], backend)
+    return result.filter_tryptic(proteins) if filter_tryptic else result
+
+
+def annotate_peptides_streaming(
+    peptides: Iterable[str],
+    protein_records: Iterable[ProteinSequenceRecord],
+    backend: str = "auto",
+) -> AnnotationResult:
+    """Annotate peptides against one-pass records exposing ``id`` and ``sequence``."""
+    records = iter(protein_records)
+    batches = (
+        (tuple(record.id for record in batch), tuple(record.sequence for record in batch))
+        for batch in iter(lambda: tuple(islice(records, _BATCH_SIZE)), ())
+    )
+    return _annotate(peptides, batches, backend)
+
+
+def _annotate(
+    peptides: Iterable[str],
+    batches: Iterable[tuple[Sequence[str], Sequence[str]]],
+    backend: str,
+) -> AnnotationResult:
+    peptide_list = list(dict.fromkeys(peptides))
+    if not peptide_list:
+        return AnnotationResult(
+            annotations=[],
+            requested_backend=_requested_backend(backend),
+            resolved_backend=resolve_backend(backend),
+        )
+    if any(_SEPARATOR in peptide for peptide in peptide_list):
+        raise ValueError("peptides must not contain line breaks")
+
+    automaton = create_automaton(peptide_list, backend=backend)
+    annotations: list[PeptideAnnotation] = []
+    for ids, sequences in batches:
+        # One backend call per batch; the separator stops matches across sequences.
+        starts = list(accumulate((len(sequence) + 1 for sequence in sequences), initial=0))
+        for match in automaton.find_all(_SEPARATOR.join(sequences)):
+            index = bisect_right(starts, match.start) - 1
+            offset = starts[index]
+            annotations.append(
+                PeptideAnnotation(
+                    match.keyword, ids[index], match.start - offset, match.end - offset
+                )
+            )
+    return AnnotationResult(
+        annotations=annotations,
+        requested_backend=automaton.requested_backend,
+        resolved_backend=automaton.resolved_backend,
+    )
+
+
+def _requested_backend(backend: str) -> BackendRequest:
+    resolve_backend(backend)
+    if backend == "ahocorapy":
+        return "ahocorapy"
+    if backend == "ahocorasick_rs":
+        return "ahocorasick_rs"
+    return "auto"

prozor-0.1.0/src/prozor/matching/automaton.py

@@ -0,0 +1,164 @@
+"""Backend-neutral Aho--Corasick peptide matching."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Iterable, Iterator
+from dataclasses import dataclass
+from importlib.util import find_spec
+from typing import Literal, cast, override
+
+type BackendName = Literal["ahocorapy", "ahocorasick_rs"]
+type BackendRequest = Literal["auto", "ahocorapy", "ahocorasick_rs"]
+
+_VALID_BACKENDS = frozenset({"auto", "ahocorapy", "ahocorasick_rs"})
+
+
+@dataclass(frozen=True, slots=True)
+class Match:
+    """One half-open keyword match in a searched sequence."""
+
+    keyword: str
+    start: int
+    end: int
+
+
+class AhoCorasickBase(ABC):
+    """Common interface implemented by every matching backend."""
+
+    requested_backend: BackendRequest
+    resolved_backend: BackendName
+
+    @abstractmethod
+    def find_all(self, text: str) -> Iterator[Match]:
+        """Yield every match, including nested and overlapping matches."""
+
+
+class AhoCorasickPure(AhoCorasickBase):
+    """Portable matcher implemented with :mod:`ahocorapy`."""
+
+    def __init__(
+        self,
+        keywords: Iterable[str],
+        *,
+        case_sensitive: bool = True,
+        requested_backend: BackendRequest = "ahocorapy",
+    ) -> None:
+        from ahocorapy.keywordtree import KeywordTree
+
+        self.requested_backend = requested_backend
+        self.resolved_backend: BackendName = "ahocorapy"
+        self._tree = KeywordTree(case_insensitive=not case_sensitive)
+        for keyword in _unique_keywords(keywords):
+            self._tree.add(keyword)
+        self._tree.finalize()
+
+    @override
+    def find_all(self, text: str) -> Iterator[Match]:
+        """Yield all pure-Python matches in ``text``."""
+        for keyword, start in self._tree.search_all(text):
+            yield Match(keyword=keyword, start=start, end=start + len(keyword))
+
+
+class AhoCorasickRust(AhoCorasickBase):
+    """Accelerated matcher implemented with :mod:`ahocorasick_rs`."""
+
+    def __init__(
+        self,
+        keywords: Iterable[str],
+        *,
+        case_sensitive: bool = True,
+        requested_backend: BackendRequest = "ahocorasick_rs",
+    ) -> None:
+        import ahocorasick_rs
+
+        self.requested_backend = requested_backend
+        self.resolved_backend: BackendName = "ahocorasick_rs"
+        self._keywords = _unique_keywords(keywords)
+        self._case_sensitive = case_sensitive
+        indexed_keywords = (
+            self._keywords
+            if case_sensitive
+            else tuple(keyword.lower() for keyword in self._keywords)
+        )
+        self._automaton = ahocorasick_rs.AhoCorasick(indexed_keywords)
+
+    @override
+    def find_all(self, text: str) -> Iterator[Match]:
+        """Yield all Rust matches in ``text``."""
+        search_text = text if self._case_sensitive else text.lower()
+        for index, start, end in self._automaton.find_matches_as_indexes(
+            search_text,
+            overlapping=True,
+        ):
+            yield Match(keyword=self._keywords[index], start=start, end=end)
+
+
+def create_automaton(
+    keywords: Iterable[str],
+    backend: str = "auto",
+    case_sensitive: bool = True,
+) -> AhoCorasickBase:
+    """Create a matcher and expose both requested and resolved backend names.
+
+    Args:
+        keywords: Peptide patterns to search for.
+        backend: ``auto``, ``ahocorapy``, or ``ahocorasick_rs``.
+        case_sensitive: Whether matching distinguishes letter case.
+
+    Returns:
+        A backend-neutral matcher.
+
+    Raises:
+        ImportError: The Rust backend was requested but is not installed.
+        ValueError: ``backend`` is not supported.
+    """
+    requested_backend = _validate_backend(backend)
+    resolved_backend = resolve_backend(requested_backend)
+    if resolved_backend == "ahocorasick_rs":
+        return AhoCorasickRust(
+            keywords,
+            case_sensitive=case_sensitive,
+            requested_backend=requested_backend,
+        )
+    return AhoCorasickPure(
+        keywords,
+        case_sensitive=case_sensitive,
+        requested_backend=requested_backend,
+    )
+
+
+def resolve_backend(backend: str = "auto") -> BackendName:
+    """Resolve a requested backend to the concrete implementation name."""
+    requested_backend = _validate_backend(backend)
+    if requested_backend == "ahocorasick_rs":
+        if not _rust_available():
+            raise ImportError(
+                "backend 'ahocorasick_rs' requires a working ahocorasick-rs installation"
+            )
+        return "ahocorasick_rs"
+    if requested_backend == "ahocorapy":
+        return "ahocorapy"
+    return "ahocorasick_rs" if _rust_available() else "ahocorapy"
+
+
+def get_available_backends() -> list[BackendName]:
+    """Return the concrete matching backends available in this environment."""
+    backends: list[BackendName] = ["ahocorapy"]
+    if _rust_available():
+        backends.append("ahocorasick_rs")
+    return backends
+
+
+def _validate_backend(backend: str) -> BackendRequest:
+    if backend not in _VALID_BACKENDS:
+        raise ValueError(f"backend must be one of {sorted(_VALID_BACKENDS)}, got {backend!r}")
+    return cast(BackendRequest, backend)
+
+
+def _rust_available() -> bool:
+    return find_spec("ahocorasick_rs") is not None
+
+
+def _unique_keywords(keywords: Iterable[str]) -> tuple[str, ...]:
+    return tuple(dict.fromkeys(keywords))

prozor-0.1.0/src/prozor/py.typed

@@ -0,0 +1 @@
+