apb-fasta 0.1.0__tar.gz

apb_fasta-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.

apb_fasta-0.1.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: apb-fasta
+Version: 0.1.0
+Summary: FASTA validation and protein annotation for APB2 results.
+Keywords: proteomics,fasta,anndata,protein annotation,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.13
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Typing :: Typed
+Requires-Dist: apb2>=0.1,<0.2
+Requires-Dist: cyclopts>=4,<5
+Requires-Dist: loguru>=0.7,<1
+Requires-Dist: polars>=1.43,<2
+Requires-Dist: protein-fasta>=0.3,<0.4
+Requires-Dist: prozor>=0.1,<0.2
+Requires-Python: >=3.13
+Project-URL: Documentation, https://anndata-omics-bridge.github.io/apb-fasta/
+Project-URL: Repository, https://github.com/anndata-omics-bridge/apb-fasta
+Project-URL: Issues, https://github.com/anndata-omics-bridge/apb-fasta/issues
+Description-Content-Type: text/markdown
+
+# apb-fasta
+
+FASTA verification and protein annotation for APB2 results.
+
+**[Online documentation](https://anndata-omics-bridge.github.io/apb-fasta/)** or its [source index](https://github.com/anndata-omics-bridge/apb-fasta/blob/main/docs/index.md).
+
+The first release exposes two independent operations:
+
+- verify that APB2's modification-stripped peptide sequences occur in the supplied FASTA database;
+- merge FASTA annotations for every reported protein-group member without collapsing the group to its leading accession.
+
+Protein inference with Prozor is the planned third operation. It will remain explicit and opt-in.
+
+## Installation
+
+APB FASTA requires Python 3.13 or later.
+
+```bash
+pip install apb-fasta
+```
+
+## Python API
+
+Read the FASTA files once and load the APB2 result:
+
+```python
+from pathlib import Path
+
+from apb2.api import read_parsed_levels, write_parsed_levels
+from apb_fasta.api import FastaAnnotator
+
+annotator = FastaAnnotator.read((Path("human.fasta"), Path("contaminants.fasta")))
+parsed = read_parsed_levels(Path("input.h5mu"))
+```
+
+Verify peptides only:
+
+```python
+verified = annotator.verify_peptides(parsed)
+print(verified.reports.peptide_levels)
+write_parsed_levels(verified.parsed, Path("verified.h5mu"))
+```
+
+Merge protein annotations only:
+
+```python
+annotated = annotator.merge_annotations(parsed)
+print(annotated.reports.protein_groups)
+write_parsed_levels(annotated.parsed, Path("annotated.h5mu"))
+```
+
+Apply both operations in memory:
+
+```python
+complete = annotator.annotate(parsed)
+write_parsed_levels(complete.parsed, Path("complete.h5mu"))
+```
+
+The operations can also be chained explicitly without an intermediate file:
+
+```python
+verified = annotator.verify_peptides(parsed)
+complete = annotator.merge_annotations(verified.parsed)
+```
+
+The annotator validates and binds the reusable protein frame once. Every method accepts one canonical `ParsedLevels` value and returns an immutable `FastaAnnotationResult` containing its replacement plus typed operation reports. `apb_fasta` neither opens result files nor receives raw AnnData or MuData objects.
+
+## CLI
+
+Verify peptides only:
+
+```bash
+apb-fasta verify-peptides input.h5mu human.fasta contaminants.fasta --output verified.h5mu
+```
+
+Merge protein annotations only:
+
+```bash
+apb-fasta merge-annotations input.h5mu human.fasta contaminants.fasta --output annotated.h5mu
+```
+
+Apply both operations together:
+
+```bash
+apb-fasta run input.h5mu human.fasta contaminants.fasta --output complete.h5mu
+```
+
+Peptide verification adds feature-aligned `varm["fasta_validation"]` tables. Protein annotation adds protein-aligned `varm["fasta"]`, the lossless `fasta_protein_group_members` annotation table, and its directed relation to the protein axis.

apb_fasta-0.1.0/README.md

@@ -0,0 +1,88 @@
+# apb-fasta
+
+FASTA verification and protein annotation for APB2 results.
+
+**[Online documentation](https://anndata-omics-bridge.github.io/apb-fasta/)** or its [source index](https://github.com/anndata-omics-bridge/apb-fasta/blob/main/docs/index.md).
+
+The first release exposes two independent operations:
+
+- verify that APB2's modification-stripped peptide sequences occur in the supplied FASTA database;
+- merge FASTA annotations for every reported protein-group member without collapsing the group to its leading accession.
+
+Protein inference with Prozor is the planned third operation. It will remain explicit and opt-in.
+
+## Installation
+
+APB FASTA requires Python 3.13 or later.
+
+```bash
+pip install apb-fasta
+```
+
+## Python API
+
+Read the FASTA files once and load the APB2 result:
+
+```python
+from pathlib import Path
+
+from apb2.api import read_parsed_levels, write_parsed_levels
+from apb_fasta.api import FastaAnnotator
+
+annotator = FastaAnnotator.read((Path("human.fasta"), Path("contaminants.fasta")))
+parsed = read_parsed_levels(Path("input.h5mu"))
+```
+
+Verify peptides only:
+
+```python
+verified = annotator.verify_peptides(parsed)
+print(verified.reports.peptide_levels)
+write_parsed_levels(verified.parsed, Path("verified.h5mu"))
+```
+
+Merge protein annotations only:
+
+```python
+annotated = annotator.merge_annotations(parsed)
+print(annotated.reports.protein_groups)
+write_parsed_levels(annotated.parsed, Path("annotated.h5mu"))
+```
+
+Apply both operations in memory:
+
+```python
+complete = annotator.annotate(parsed)
+write_parsed_levels(complete.parsed, Path("complete.h5mu"))
+```
+
+The operations can also be chained explicitly without an intermediate file:
+
+```python
+verified = annotator.verify_peptides(parsed)
+complete = annotator.merge_annotations(verified.parsed)
+```
+
+The annotator validates and binds the reusable protein frame once. Every method accepts one canonical `ParsedLevels` value and returns an immutable `FastaAnnotationResult` containing its replacement plus typed operation reports. `apb_fasta` neither opens result files nor receives raw AnnData or MuData objects.
+
+## CLI
+
+Verify peptides only:
+
+```bash
+apb-fasta verify-peptides input.h5mu human.fasta contaminants.fasta --output verified.h5mu
+```
+
+Merge protein annotations only:
+
+```bash
+apb-fasta merge-annotations input.h5mu human.fasta contaminants.fasta --output annotated.h5mu
+```
+
+Apply both operations together:
+
+```bash
+apb-fasta run input.h5mu human.fasta contaminants.fasta --output complete.h5mu
+```
+
+Peptide verification adds feature-aligned `varm["fasta_validation"]` tables. Protein annotation adds protein-aligned `varm["fasta"]`, the lossless `fasta_protein_group_members` annotation table, and its directed relation to the protein axis.

apb_fasta-0.1.0/pyproject.toml

@@ -0,0 +1,146 @@
+[build-system]
+requires = ["uv_build>=0.9.26,<0.10.0"]
+build-backend = "uv_build"
+
+[project]
+name = "apb-fasta"
+version = "0.1.0"
+description = "FASTA validation and protein annotation for APB2 results."
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "proteomics",
+    "fasta",
+    "anndata",
+    "protein annotation",
+    "mass spectrometry",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+    "Typing :: Typed",
+]
+dependencies = [
+    "apb2>=0.1,<0.2",
+    "cyclopts>=4,<5",
+    "loguru>=0.7,<1",
+    "polars>=1.43,<2",
+    "protein-fasta>=0.3,<0.4",
+    "prozor>=0.1,<0.2",
+]
+
+[[project.authors]]
+name = "Witold Wolski"
+email = "wew@fgcz.ethz.ch"
+
+[project.scripts]
+apb-fasta = "apb_fasta.cli:main"
+
+[project.urls]
+Documentation = "https://anndata-omics-bridge.github.io/apb-fasta/"
+Repository = "https://github.com/anndata-omics-bridge/apb-fasta"
+Issues = "https://github.com/anndata-omics-bridge/apb-fasta/issues"
+
+[dependency-groups]
+dev = [
+    "build>=1.3,<2",
+    "deptry>=0.24,<1",
+    "import-linter>=2.9,<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.sources.apb2]
+path = "../apb2"
+editable = true
+
+[tool.uv.sources.protein-fasta]
+path = "../protein_fasta"
+editable = true
+
+[tool.uv.sources.prozor]
+path = "../prozor"
+editable = true
+
+[tool.ruff]
+line-length = 100
+target-version = "py313"
+src = [
+    "src",
+    "tests",
+]
+
+[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",
+]
+venvPath = "."
+venv = ".venv"
+pythonVersion = "3.13"
+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 = ["apb_fasta"]
+
+[tool.coverage.report]
+fail_under = 80
+show_missing = true
+skip_covered = true
+
+[tool.deptry]
+known_first_party = ["apb_fasta"]

apb_fasta-0.1.0/pyproject.toml.orig

@@ -0,0 +1,107 @@
+[build-system]
+requires = ["uv_build>=0.9.26,<0.10.0"]
+build-backend = "uv_build"
+
+[project]
+name = "apb-fasta"
+version = "0.1.0"
+description = "FASTA validation and protein annotation for APB2 results."
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Witold Wolski", email = "wew@fgcz.ethz.ch" },
+]
+keywords = ["proteomics", "fasta", "anndata", "protein annotation", "mass spectrometry"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+    "Typing :: Typed",
+]
+dependencies = [
+    "apb2>=0.1,<0.2",
+    "cyclopts>=4,<5",
+    "loguru>=0.7,<1",
+    "polars>=1.43,<2",
+    "protein-fasta>=0.3,<0.4",
+    "prozor>=0.1,<0.2",
+]
+
+[project.scripts]
+apb-fasta = "apb_fasta.cli:main"
+
+[project.urls]
+Documentation = "https://anndata-omics-bridge.github.io/apb-fasta/"
+Repository = "https://github.com/anndata-omics-bridge/apb-fasta"
+Issues = "https://github.com/anndata-omics-bridge/apb-fasta/issues"
+
+[dependency-groups]
+dev = [
+    "build>=1.3,<2",
+    "deptry>=0.24,<1",
+    "import-linter>=2.9,<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.sources]
+apb2 = { path = "../apb2", editable = true }
+protein-fasta = { path = "../protein_fasta", editable = true }
+prozor = { path = "../prozor", editable = true }
+
+[tool.ruff]
+line-length = 100
+target-version = "py313"
+src = ["src", "tests"]
+
+[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"]
+venvPath = "."
+venv = ".venv"
+pythonVersion = "3.13"
+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 = ["apb_fasta"]
+
+[tool.coverage.report]
+fail_under = 80
+show_missing = true
+skip_covered = true
+
+[tool.deptry]
+known_first_party = ["apb_fasta"]

apb_fasta-0.1.0/src/apb_fasta/api.py

@@ -0,0 +1,164 @@
+"""Public in-memory FASTA annotation API."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from importlib.metadata import version
+from pathlib import Path
+
+import polars as pl
+from apb2.api import ParsedLevels
+from protein_fasta.api import ProteinDatabase, ProteinFormat
+from prozor.api import resolve_backend
+
+from apb_fasta.calculation.matching import match_peptide_levels
+from apb_fasta.calculation.peptide_properties import peptide_level_properties
+from apb_fasta.calculation.protein_groups import match_protein_groups
+from apb_fasta.calculation.results import FastaAnnotationReports
+from apb_fasta.configuration import (
+    DEFAULT_FASTA_ANNOTATION_PARAMETERS,
+    FastaAnnotationParameters,
+)
+from apb_fasta.errors import FastaAnnotationError
+from apb_fasta.integration import (
+    apply_peptide_matches,
+    apply_peptide_properties,
+    apply_protein_group_match,
+    peptide_inputs,
+    protein_frame_metadata,
+    protein_group_input,
+    validate_protein_frame,
+)
+
+_NO_PEPTIDE_LEVEL = (
+    "result contains no peptide-derived level with canonical ProForma_peptide values"
+)
+
+
+@dataclass(frozen=True, slots=True)
+class FastaAnnotationResult:
+    """A replacement APB2 result and its FASTA reports."""
+
+    parsed: ParsedLevels
+    reports: FastaAnnotationReports
+
+
+class FastaAnnotator:
+    """Bind one protein database and its FASTA annotation behavior."""
+
+    __slots__ = ("_parameters", "_proteins")
+
+    def __init__(
+        self,
+        proteins: pl.DataFrame,
+        parameters: FastaAnnotationParameters = DEFAULT_FASTA_ANNOTATION_PARAMETERS,
+    ) -> None:
+        """Validate and bind a reusable protein database and configuration."""
+        validate_protein_frame(proteins)
+        self._proteins = proteins
+        self._parameters = parameters
+
+    @classmethod
+    def read(
+        cls,
+        fasta: Sequence[Path],
+        formats: Sequence[str] = ("uniprotkb", "refseq"),
+        parameters: FastaAnnotationParameters = DEFAULT_FASTA_ANNOTATION_PARAMETERS,
+    ) -> FastaAnnotator:
+        """Read FASTA files, or the protein-fasta database Parquet written from them."""
+        if not fasta:
+            raise ValueError("at least one FASTA path is required")
+        database = ProteinDatabase(*(ProteinFormat(name) for name in formats))
+        return cls(database.parse(tuple(fasta)), parameters)
+
+    @property
+    def proteins(self) -> pl.DataFrame:
+        """The bound protein table, one row per FASTA entry in file order."""
+        return self._proteins
+
+    def verify_peptides(self, parsed: ParsedLevels) -> FastaAnnotationResult:
+        """Verify every canonical stripped peptide against the protein sequences."""
+        inputs = peptide_inputs(parsed)
+        if not inputs:
+            raise FastaAnnotationError(_NO_PEPTIDE_LEVEL)
+        peptide_levels = match_peptide_levels(
+            inputs,
+            self._proteins,
+            backend=self._parameters.matcher_backend,
+            il_equivalent=self._parameters.il_equivalent,
+            protein_group_separator=self._parameters.protein_group_separator,
+        )
+        replacement, reports = apply_peptide_matches(
+            parsed,
+            peptide_levels,
+            requested_backend=self._parameters.matcher_backend,
+            resolved_backend=resolve_backend(self._parameters.matcher_backend),
+            il_equivalent=self._parameters.il_equivalent,
+            protein_metadata=protein_frame_metadata(self._proteins),
+        )
+        return FastaAnnotationResult(parsed=replacement, reports=reports)
+
+    def merge_annotations(self, parsed: ParsedLevels) -> FastaAnnotationResult:
+        """Merge FASTA annotations for every reported protein-group member."""
+        protein_input = protein_group_input(parsed)
+        if protein_input is None:
+            raise FastaAnnotationError("result contains no protein level to annotate")
+        protein_groups = match_protein_groups(
+            protein_input,
+            self._proteins,
+            separator=self._parameters.protein_group_separator,
+        )
+        replacement, reports = apply_protein_group_match(
+            parsed,
+            protein_groups,
+            protein_group_separator=self._parameters.protein_group_separator,
+            protein_metadata=protein_frame_metadata(self._proteins),
+        )
+        return FastaAnnotationResult(parsed=replacement, reports=reports)
+
+    def annotate(self, parsed: ParsedLevels) -> FastaAnnotationResult:
+        """Verify peptides and then merge protein annotations in memory."""
+        verified = self.verify_peptides(parsed)
+        annotated = self.merge_annotations(verified.parsed)
+        return FastaAnnotationResult(
+            parsed=annotated.parsed,
+            reports=FastaAnnotationReports(
+                peptide_levels=verified.reports.peptide_levels,
+                protein_groups=annotated.reports.protein_groups,
+            ),
+        )
+
+
+def add_peptide_properties(parsed: ParsedLevels) -> ParsedLevels:
+    """Attach sequence-derived properties to every peptide-derived level.
+
+    Writes a feature-aligned ``varm["peptide_properties"]`` computed by
+    ``protein_fasta.peptide_frame.peptide_property_frame`` from each level's ``ProForma_peptide``.
+    No protein database is needed. A feature without a sequence, or with a residue outside the 20
+    standard amino acids, has null properties.
+
+    Raises:
+        FastaAnnotationError: If the result has no peptide-derived level, already contains the
+            output, or already records the operation.
+        ValueError: If a sequence is not stripped upper-case letters.
+    """
+    inputs = peptide_inputs(parsed)
+    if not inputs:
+        raise FastaAnnotationError(_NO_PEPTIDE_LEVEL)
+    properties = {
+        name: peptide_level_properties(level.frame, level.sequence_column)
+        for name, level in inputs.items()
+    }
+    return apply_peptide_properties(
+        parsed, properties, protein_fasta_version=version("protein-fasta")
+    )
+
+
+__all__ = [
+    "FastaAnnotationParameters",
+    "FastaAnnotationReports",
+    "FastaAnnotationResult",
+    "FastaAnnotator",
+    "add_peptide_properties",
+]