apb-proteobench 0.1.0__tar.gz

apb_proteobench-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_proteobench-0.1.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: apb-proteobench
+Version: 0.1.0
+Summary: ProteoBench annotation, diagnostics, and scoring for APB2 results
+Keywords: proteomics,proteobench,benchmarking,anndata,mass spectrometry
+Author: Witold Wolski
+Author-email: Witold Wolski <wew@fgcz.ethz.ch>
+License-Expression: MIT
+License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES.md
+License-File: src/apb_proteobench/data/APACHE-2.0.txt
+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: apb-catalog>=0.1,<0.2
+Requires-Dist: apb-fasta>=0.1,<0.2
+Requires-Dist: cyclopts>=4,<5
+Requires-Dist: loguru>=0.7,<1
+Requires-Dist: numpy>=2,<3
+Requires-Dist: pandas>=2.3,<4
+Requires-Dist: polars>=1.38,<2
+Requires-Dist: pydantic>=2.12,<3
+Requires-Dist: scipy>=1.16,<2
+Requires-Python: >=3.13
+Project-URL: Documentation, https://anndata-omics-bridge.github.io/apb-proteobench/
+Project-URL: Repository, https://github.com/anndata-omics-bridge/apb-proteobench
+Project-URL: Issues, https://github.com/anndata-omics-bridge/apb-proteobench/issues
+Description-Content-Type: text/markdown
+
+# APB ProteoBench
+
+ProteoBench annotation, mixed-species diagnostics, and scoring for storage-neutral APB2
+results. HYE and HY use the same configuration-driven calculation.
+
+## Installation
+
+APB ProteoBench requires Python 3.13 or later.
+
+```bash
+pip install apb-proteobench
+```
+
+## Usage
+
+Run the complete workflow directly from vendor files:
+
+```bash
+apb-proteobench run quant report.tsv proteins.fasta \
+    --params search-parameters.txt \
+    --module module_settings.toml \
+    --software spectronaut \
+    --level ion \
+    --output results/scored.h5ad
+```
+
+This one call converts the selected APB2 quantification level, verifies modification-stripped peptide sequences against the FASTA database, applies the ProteoBench sample design, calculates diagnostics and scores, and writes one final APB2 result. Omit `--level` to convert every compatible level. Single-level H5AD and multi-level H5MU targets are supported alongside Parquet and DuckDB. Intermediate values remain storage-neutral `ParsedLevels`, and APB2's `write_parsed_levels` selects persistence from the target suffix. It scores the level named in `module_settings.toml` as the vendor table reports it and performs no quantitative aggregation.
+
+The equivalent reusable workflow calls the existing tools directly:
+
+```bash
+apb2 convert report.tsv --params search-parameters.txt --software spectronaut --output results/all
+apb-fasta verify-peptides results/all.h5mu proteins.fasta --output results/fasta-checked.h5mu
+apb-aggregate ion protein sum results/fasta-checked.h5mu results/aggregated.h5mu
+apb-proteobench benchmark results/aggregated.h5mu module_settings.toml results/scored.h5mu
+```
+
+The `apb-aggregate` step is optional: include it only when the scored level must be derived from a lower one. Omit it and `benchmark` reads `results/fasta-checked.h5mu` directly.
+
+APB ProteoBench declares only `apb2` and `apb-fasta`, and reaches aggregation solely as a subprocess.
+
+The CLI intentionally exposes only `run` and `benchmark`; APB2 owns conversion and persistence, while the Python API exposes in-memory ProteoBench analysis over canonical `ParsedLevels`. `benchmark` combines annotation and scoring for an existing APB2 result. Scoring uses one abundance layer: `--layer NAME`, by default `X`, the APB primary layer projected to AnnData `X`. Per-layer diagnostics live in `varm["proteobench:<layer-name>"]`, while selection provenance and layer-keyed scores live in `metadata["proteobench"]`. See the [documentation](https://anndata-omics-bridge.github.io/apb-proteobench/).
+
+To feed the existing pMultiQC ProteoBench module and retain the matching ProteoBot result, add `--result-performance reports/result_performance.csv` to `run` or `benchmark`. The option publishes two staged files in the same directory: `result_performance.csv` plus `<intermediate_hash>.json` in the schema and naming convention used by `Proteobench/Results_quant_ion_DDA`. Each file is published atomically without overwrite, and a failed publication rolls back any file added by the same call. This export writes the scored layer, supports only an ion level, and refuses either existing target. Its SHA-256 submission hash is computed only during this export from the selected layer and scoring inputs. The new identity does not match historical SHA-1 uploads.
+
+For optional operation-level timing files, pass `--timings-dir DIR` to `run`. It writes separate JSON files for APB2 conversion, FASTA verification, and ProteoBench benchmarking without changing the scored result or Studio's process-level runtime measurement.
+
+The package owns all 11 ProteoBench module TOMLs: the nine quantitative HYE/HY and plasma modules
+and the newer de novo and entrapment documents. Entrapment is scored by `run entrapment`; de novo
+is packaged for planned support. Neither is accepted by the quantitative scorer. Every quantitative module's scores
+include ProteoBench's plasma metrics; see [results](https://anndata-omics-bridge.github.io/apb-proteobench/results/). Stable names,
+support status, and the Python loading API are documented under
+[module configuration](https://anndata-omics-bridge.github.io/apb-proteobench/configuration/).
+
+## Development
+
+```bash
+uv sync --group dev
+make check
+.venv/bin/pre-commit install --hook-type pre-commit --hook-type pre-push
+```
+
+All Python commands run from the synchronized project `.venv`.

apb_proteobench-0.1.0/README.md

@@ -0,0 +1,63 @@
+# APB ProteoBench
+
+ProteoBench annotation, mixed-species diagnostics, and scoring for storage-neutral APB2
+results. HYE and HY use the same configuration-driven calculation.
+
+## Installation
+
+APB ProteoBench requires Python 3.13 or later.
+
+```bash
+pip install apb-proteobench
+```
+
+## Usage
+
+Run the complete workflow directly from vendor files:
+
+```bash
+apb-proteobench run quant report.tsv proteins.fasta \
+    --params search-parameters.txt \
+    --module module_settings.toml \
+    --software spectronaut \
+    --level ion \
+    --output results/scored.h5ad
+```
+
+This one call converts the selected APB2 quantification level, verifies modification-stripped peptide sequences against the FASTA database, applies the ProteoBench sample design, calculates diagnostics and scores, and writes one final APB2 result. Omit `--level` to convert every compatible level. Single-level H5AD and multi-level H5MU targets are supported alongside Parquet and DuckDB. Intermediate values remain storage-neutral `ParsedLevels`, and APB2's `write_parsed_levels` selects persistence from the target suffix. It scores the level named in `module_settings.toml` as the vendor table reports it and performs no quantitative aggregation.
+
+The equivalent reusable workflow calls the existing tools directly:
+
+```bash
+apb2 convert report.tsv --params search-parameters.txt --software spectronaut --output results/all
+apb-fasta verify-peptides results/all.h5mu proteins.fasta --output results/fasta-checked.h5mu
+apb-aggregate ion protein sum results/fasta-checked.h5mu results/aggregated.h5mu
+apb-proteobench benchmark results/aggregated.h5mu module_settings.toml results/scored.h5mu
+```
+
+The `apb-aggregate` step is optional: include it only when the scored level must be derived from a lower one. Omit it and `benchmark` reads `results/fasta-checked.h5mu` directly.
+
+APB ProteoBench declares only `apb2` and `apb-fasta`, and reaches aggregation solely as a subprocess.
+
+The CLI intentionally exposes only `run` and `benchmark`; APB2 owns conversion and persistence, while the Python API exposes in-memory ProteoBench analysis over canonical `ParsedLevels`. `benchmark` combines annotation and scoring for an existing APB2 result. Scoring uses one abundance layer: `--layer NAME`, by default `X`, the APB primary layer projected to AnnData `X`. Per-layer diagnostics live in `varm["proteobench:<layer-name>"]`, while selection provenance and layer-keyed scores live in `metadata["proteobench"]`. See the [documentation](https://anndata-omics-bridge.github.io/apb-proteobench/).
+
+To feed the existing pMultiQC ProteoBench module and retain the matching ProteoBot result, add `--result-performance reports/result_performance.csv` to `run` or `benchmark`. The option publishes two staged files in the same directory: `result_performance.csv` plus `<intermediate_hash>.json` in the schema and naming convention used by `Proteobench/Results_quant_ion_DDA`. Each file is published atomically without overwrite, and a failed publication rolls back any file added by the same call. This export writes the scored layer, supports only an ion level, and refuses either existing target. Its SHA-256 submission hash is computed only during this export from the selected layer and scoring inputs. The new identity does not match historical SHA-1 uploads.
+
+For optional operation-level timing files, pass `--timings-dir DIR` to `run`. It writes separate JSON files for APB2 conversion, FASTA verification, and ProteoBench benchmarking without changing the scored result or Studio's process-level runtime measurement.
+
+The package owns all 11 ProteoBench module TOMLs: the nine quantitative HYE/HY and plasma modules
+and the newer de novo and entrapment documents. Entrapment is scored by `run entrapment`; de novo
+is packaged for planned support. Neither is accepted by the quantitative scorer. Every quantitative module's scores
+include ProteoBench's plasma metrics; see [results](https://anndata-omics-bridge.github.io/apb-proteobench/results/). Stable names,
+support status, and the Python loading API are documented under
+[module configuration](https://anndata-omics-bridge.github.io/apb-proteobench/configuration/).
+
+## Development
+
+```bash
+uv sync --group dev
+make check
+.venv/bin/pre-commit install --hook-type pre-commit --hook-type pre-push
+```
+
+All Python commands run from the synchronized project `.venv`.

apb_proteobench-0.1.0/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,7 @@
+# Third-party notices
+
+The modification renderer in `src/apb_proteobench/calculation/mapping.py` and the ProteoBench module TOMLs under
+`src/apb_proteobench/data/modules/` are derived from the ProteoBench project and are distributed
+under the Apache License 2.0. Their upstream attribution is retained in
+`src/apb_proteobench/data/RENDERER_NOTICE.md` and `src/apb_proteobench/data/MODULES_NOTICE.md`. The
+license text is retained beside them as `src/apb_proteobench/data/APACHE-2.0.txt`.

apb_proteobench-0.1.0/pyproject.toml

@@ -0,0 +1,161 @@
+[build-system]
+requires = ["uv_build>=0.9.26,<0.10.0"]
+build-backend = "uv_build"
+
+[project]
+name = "apb-proteobench"
+version = "0.1.0"
+description = "ProteoBench annotation, diagnostics, and scoring for APB2 results"
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+license-files = [
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md",
+    "src/apb_proteobench/data/APACHE-2.0.txt",
+]
+keywords = [
+    "proteomics",
+    "proteobench",
+    "benchmarking",
+    "anndata",
+    "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",
+    "apb-catalog>=0.1,<0.2",
+    "apb-fasta>=0.1,<0.2",
+    "cyclopts>=4,<5",
+    "loguru>=0.7,<1",
+    "numpy>=2,<3",
+    "pandas>=2.3,<4",
+    "polars>=1.38,<2",
+    "pydantic>=2.12,<3",
+    "scipy>=1.16,<2",
+]
+
+[[project.authors]]
+name = "Witold Wolski"
+email = "wew@fgcz.ethz.ch"
+
+[project.scripts]
+apb-proteobench = "apb_proteobench.cli.app:main"
+
+[project.urls]
+Documentation = "https://anndata-omics-bridge.github.io/apb-proteobench/"
+Repository = "https://github.com/anndata-omics-bridge/apb-proteobench"
+Issues = "https://github.com/anndata-omics-bridge/apb-proteobench/issues"
+
+[dependency-groups]
+dev = [
+    "build>=1.3,<2",
+    "deptry>=0.24,<1",
+    "import-linter>=2.9,<3",
+    "pandas-stubs>=2.3,<3",
+    "pre-commit>=4,<5",
+    "pyright>=1.1.400,<2",
+    "pytest>=9,<10",
+    "pytest-cov>=7,<8",
+    "ruff>=0.15,<1",
+    "sdrf-pipelines>=0.1.6,<0.2",
+    "twine>=6,<7",
+]
+docs = [
+    "mkdocstrings[python]>=1.0,<2",
+    "pymdown-extensions>=11,<12",
+    "zensical==0.0.43",
+]
+
+[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"
+reportUnnecessaryTypeIgnoreComment = "error"
+reportImplicitOverride = "error"
+enableTypeIgnoreComments = false
+reportMissingTypeStubs = "none"
+reportUnknownMemberType = "none"
+reportUnknownVariableType = "none"
+reportUnknownArgumentType = "none"
+reportUnknownParameterType = "none"
+reportUnknownLambdaType = "none"
+
+[tool.pytest.ini_options]
+addopts = [
+    "--strict-config",
+    "--strict-markers",
+    "-ra",
+]
+testpaths = ["tests"]
+xfail_strict = true
+
+[tool.coverage.run]
+branch = true
+source = ["apb_proteobench"]
+
+[tool.coverage.report]
+fail_under = 80
+show_missing = true
+skip_covered = true
+
+[tool.deptry]
+known_first_party = ["apb_proteobench"]
+
+[tool.uv.sources.apb2]
+path = "../apb2"
+editable = true
+
+[tool.uv.sources.apb-catalog]
+path = "../apb-catalog"
+editable = true
+
+[tool.uv.sources.apb-fasta]
+path = "../apb-fasta"
+editable = true

apb_proteobench-0.1.0/pyproject.toml.orig

@@ -0,0 +1,135 @@
+[build-system]
+requires = ["uv_build>=0.9.26,<0.10.0"]
+build-backend = "uv_build"
+
+[project]
+name = "apb-proteobench"
+version = "0.1.0"
+description = "ProteoBench annotation, diagnostics, and scoring for APB2 results"
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+license-files = ["LICENSE", "THIRD_PARTY_NOTICES.md", "src/apb_proteobench/data/APACHE-2.0.txt"]
+authors = [
+    { name = "Witold Wolski", email = "wew@fgcz.ethz.ch" },
+]
+keywords = ["proteomics", "proteobench", "benchmarking", "anndata", "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",
+    "apb-catalog>=0.1,<0.2",
+    "apb-fasta>=0.1,<0.2",
+    "cyclopts>=4,<5",
+    "loguru>=0.7,<1",
+    "numpy>=2,<3",
+    "pandas>=2.3,<4",
+    "polars>=1.38,<2",
+    "pydantic>=2.12,<3",
+    "scipy>=1.16,<2",
+]
+
+[project.scripts]
+apb-proteobench = "apb_proteobench.cli.app:main"
+
+[project.urls]
+Documentation = "https://anndata-omics-bridge.github.io/apb-proteobench/"
+Repository = "https://github.com/anndata-omics-bridge/apb-proteobench"
+Issues = "https://github.com/anndata-omics-bridge/apb-proteobench/issues"
+
+[dependency-groups]
+dev = [
+    "build>=1.3,<2",
+    "deptry>=0.24,<1",
+    "import-linter>=2.9,<3",
+    "pandas-stubs>=2.3,<3",
+    "pre-commit>=4,<5",
+    "pyright>=1.1.400,<2",
+    "pytest>=9,<10",
+    "pytest-cov>=7,<8",
+    "ruff>=0.15,<1",
+    "sdrf-pipelines>=0.1.6,<0.2",
+    "twine>=6,<7",
+]
+docs = [
+    "mkdocstrings[python]>=1.0,<2",
+    "pymdown-extensions>=11,<12",
+    "zensical==0.0.43",
+]
+
+[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"
+reportUnnecessaryTypeIgnoreComment = "error"
+reportImplicitOverride = "error"
+enableTypeIgnoreComments = false
+# SciPy and pandas still propagate Unknown through supported public operations.
+# Keep strict first-party checking while suppressing diagnostics with only that signal.
+reportMissingTypeStubs = "none"
+reportUnknownMemberType = "none"
+reportUnknownVariableType = "none"
+reportUnknownArgumentType = "none"
+reportUnknownParameterType = "none"
+reportUnknownLambdaType = "none"
+
+[tool.pytest.ini_options]
+addopts = ["--strict-config", "--strict-markers", "-ra"]
+testpaths = ["tests"]
+xfail_strict = true
+
+[tool.coverage.run]
+branch = true
+source = ["apb_proteobench"]
+
+[tool.coverage.report]
+fail_under = 80
+show_missing = true
+skip_covered = true
+
+[tool.deptry]
+known_first_party = ["apb_proteobench"]
+
+[tool.uv.sources]
+apb2 = { path = "../apb2", editable = true }
+apb-catalog = { path = "../apb-catalog", editable = true }
+apb-fasta = { path = "../apb-fasta", editable = true }

apb_proteobench-0.1.0/src/apb_proteobench/__init__.py

@@ -0,0 +1 @@
+

apb_proteobench-0.1.0/src/apb_proteobench/annotation.py

@@ -0,0 +1,93 @@
+"""Bind one ProteoBench module to the configured APB quantification level."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import dataclass, replace
+from pathlib import Path
+
+import polars as pl
+from apb2.api import AnnotationCompiler, AnnotationError, JsonValue, ParsedLevels
+
+from apb_proteobench.configuration.load import LoadedModule, load_module
+
+_STORAGE_KEY = "proteobench"
+
+
+@dataclass(frozen=True, slots=True)
+class ProteoBenchAnnotation:
+    """A dataset annotated with every module sample, awaiting its module provenance."""
+
+    annotated: ParsedLevels
+    module: LoadedModule
+
+    def annotate(self) -> ParsedLevels:
+        """Store the normalized module beside APB2's own annotation provenance."""
+        metadata = deepcopy(self.annotated.metadata)
+        section = metadata.setdefault(_STORAGE_KEY, {})
+        if not isinstance(section, dict):
+            raise AnnotationError("ProteoBench metadata must be an object")
+        provenance = section.setdefault("provenance", {})
+        if not isinstance(provenance, dict):
+            raise AnnotationError("ProteoBench provenance must be an object")
+        record: dict[str, JsonValue] = {**self.module.metadata(), "schema_version": "2"}
+        provenance["annotation"] = record
+        return replace(self.annotated, metadata=metadata)
+
+
+@dataclass(frozen=True, slots=True)
+class ProteoBenchAnnotationParser:
+    """A validated module source ready to bind to one APB result."""
+
+    module: LoadedModule
+
+    @classmethod
+    def from_path(cls, path: Path, /) -> ProteoBenchAnnotationParser:
+        """Decode and validate the complete module document once."""
+        return cls(load_module(path))
+
+    def parse(self, parsed: ParsedLevels, /) -> ProteoBenchAnnotation:
+        """Match every run to exactly one module sample and every sample to a run."""
+        level_name = self.module.settings.general.level
+        if level_name not in parsed.levels:
+            raise AnnotationError(
+                f"ProteoBench module selects unavailable level {level_name!r}; "
+                f"available={list(parsed.levels)}"
+            )
+        annotation = AnnotationCompiler("error").compile(_sample_frame(self.module)).parse(parsed)
+        coverage = annotation.matches.levels[level_name].coverage
+        if coverage.annotation_only_count:
+            raise AnnotationError(
+                "ProteoBench module contains samples absent from quantification; "
+                f"count={coverage.annotation_only_count}, "
+                f"examples={list(coverage.annotation_only_examples)}"
+            )
+        return ProteoBenchAnnotation(annotated=annotation.annotate().parsed, module=self.module)
+
+
+def _sample_frame(module: LoadedModule) -> pl.DataFrame:
+    """The module samples as a prolfquapp table keyed by raw file, with its aliases."""
+    samples = module.settings.samples
+    return pl.DataFrame(
+        {
+            "raw_file": [sample.raw_file for sample in samples],
+            "raw_file_aliases": [
+                list(
+                    dict.fromkeys(
+                        identifier
+                        for identifier in (*sample.raw_file_aliases, sample.sample_name)
+                        if identifier != sample.raw_file
+                    )
+                )
+                for sample in samples
+            ],
+            "sample_name": [sample.sample_name for sample in samples],
+            "condition": [sample.condition for sample in samples],
+        },
+        schema={
+            "raw_file": pl.String,
+            "raw_file_aliases": pl.List(pl.String),
+            "sample_name": pl.String,
+            "condition": pl.String,
+        },
+    )