APB2

APB2 (anndata proteomics bridge) is a rules-driven framework for converting outputs from proteomics software into AnnData or MuData. It supports ion, peptidoform, peptide, protein, and fragment quantification levels and can also store the parsed data in Parquet or DuckDB.

“Rules-driven” means that declarative rule documents describe each vendor table: which columns contain identifiers, measurements, and metadata, how those columns should be reshaped, and which constraints the result must satisfy. One shared parser applies those rules, so a new or revised input format can usually be supported by adding or updating a rule instead of writing a dedicated reader. The rules-driven conversion guide shows this with equivalent long- and wide-format examples.

APB2 was discussed and started during the Copenhagen ProteoBench Hackathon, 13–17 April 2026, as part of the work to improve the backend of the ProteoBench platform.

Existing vendor-specific readers for differential expression/abundance analysis provided a second motivation. They are maintained behind prolfquapp::preprocess_software() and in prolfquappPTMreaders. We plan to move their remaining input variants and PTM/site-level formats into APB2, so one rules-driven parser can serve both prolfquapp and ProteoBench.

Choose an interface

Both interfaces expose three separate workflows:

vendor table + parameter evidence
    -> convert
    -> h5ad/h5mu, Parquet, or DuckDB

APB2 result
    -> reformat
    -> another result format

APB2 result + sample annotation
    -> annotate
    -> annotated APB2 result

Command-line interface

Convert

Convert one quantification level to AnnData:

apb2 convert report.tsv ion --params search-parameters.txt --output results/ion

Omit the level to write every compatible level, and select the storage writer directly:

apb2 convert report.tsv --params search-parameters.txt --format parquet --output results/all-levels

The vendor-conversion guide covers rule selection, explicit rule documents, strictness, and output naming.

Reformat

Change the storage format without parsing the vendor table again:

apb2 reformat results/all-levels.h5mu results/all-levels.parquet

The result I/O guide documents the format contracts and fidelity guarantees.

Annotate

Attach a generic prolfquapp-style sample table to a converted result:

apb2 annotate results/all-levels.h5mu samples.tsv results/annotated.h5mu

The sample-annotation guide covers matching, strictness, filtering, and diagnostics. ProteoBench module annotation and scoring live in the separate apb-proteobench package.

The complete CLI reference lists every argument, option, and exit status.

Python API

The Python API exposes storage-neutral values between parsing, transformation, and persistence. File-to-file conversion remains a CLI workflow.

Parse vendor output in memory

from pathlib import Path

from apb2.api import ParseRuleCompiler

compiler = ParseRuleCompiler(
    Path("report.tsv"),
    Path("search-parameters.txt"),
    requested_levels=("ion",),
    software="spectronaut",
)
parsed_levels = compiler.compile().parse()

compiler.parameters retains the typed vendor parameters and compiler.detection retains the resolved software, version, documents, sources, and levels. Compilation and parsing perform no writes.

Compile and parse

Use the compiler/parser boundary to keep the parsed result in memory:

from pathlib import Path

from apb2.api import ParseRuleCompiler, write_parsed_levels

parser = ParseRuleCompiler(
    Path("report.tsv"),
    Path("search-parameters.txt"),
    requested_levels=("ion",),
    checks="standard",
).compile()

parsed = parser.parse()
write_parsed_levels(parsed, Path("results/ion.h5ad"))

Read and write results

The suffix selects the format:

from pathlib import Path

from apb2.api import read_parsed_levels, write_parsed_levels

parsed = read_parsed_levels(Path("results.parquet"))
write_parsed_levels(parsed, Path("results.duckdb"))

Annotate a parsed result

apb2 annotate RESULT SAMPLES TARGET performs the complete file-to-file operation. The compiler/parser API exposes the storage-neutral transformation:

from pathlib import Path

from apb2.api import AnnotationCompiler, read_parsed_levels, write_parsed_levels

parsed = read_parsed_levels(Path("results/all-levels.h5mu"))
parser = AnnotationCompiler().compile(Path("samples.tsv"))
annotation = parser.parse(parsed)
annotated = annotation.annotate().parsed
write_parsed_levels(annotated, Path("results/annotated.h5mu"))

The complete Python API reference documents result values, helper functions, and errors.

Supported result formats

Conversion does not perform sample annotation, FASTA annotation, protein inference, or ProteoBench scoring. Run those operations explicitly after conversion.

The repository README gives the compact project overview. The converter architecture and sample-annotation architecture record the design and dependency rules.