Introduction

The AnnData Proteomics Bridge (APB) converts the reports of quantification software such as DIA-NN, Spectronaut or MaxQuant into one result layout. The columns keep the vendors’ names, so a posterior error probability is PEP in MaxQuant and EG_PEP in Spectronaut. apb-catalog records what each column means; apbCatalogR implements its API in R, so an R application asks for a meaning and gets the column or its data.

The package works on a bundle apb-catalog releases: the reviewed sets and the levels apb2 converts for each software version. One bundle ships with the package, together with a test bundle of synthetic results and the answers apb-catalog gives on them.

apbCatalogR gives R one way into the quantification outputs of the 14 tools apb2 converts: AlphaDIA, AlphaPept, DIA-NN, FragPipe, i2MassChroQ, MaxQuant, MetaMorpheus, MSAngel, PEAKS, ProlineStudio, quantms, Sage, Spectronaut and WOMBAT-P, and of ProteoBench’s custom upload format. A meaning, such as a PEP or a normalized protein intensity, is asked for by the same key whichever tool reported it. Code that hands a result’s quantities to a Bioconductor package for differential expression analysis is therefore written once for all 14 tools; such packages include DEP, DEqMS, limma, limpa, msqrob2, MSstats, proDA and prolfqua.

apbCatalogR is on Bioconductor because anndataR and MuData are: they bring to R the AnnData and MuData formats apb2 writes its results in, and apbCatalogR hands each level back as an anndataR AnnData.

Who does what. The integrator converts the results of quantification software such as DIA-NN, Spectronaut, AlphaDIA and Sage with apb2 and its parsing rules into an APB result, and fills the catalog. Bioconductor applications such as prolfqua, exploreDE and QFeatures read the result by meaning through the apb-catalog API: apbCatalogR in R, apb-catalog in Python, apb-catalog-ts in TypeScript.

The main calls:

Catalog$new(software, software_version, set_name): a version’s fields
read_parsed_levels(path): an APB result, one anndataR AnnData per level
DataCatalog$new(result, ...): the data of a result, looked up by key
sets(), catalog_table(): the sets and their entries
rule_coverage(): how each software version covers a set
catalog_version(), update_catalog(): the bundle in use, and installing one

Installation

install.packages(c("BiocManager", "remotes"))
BiocManager::install("anndata-omics-bridge/apbCatalogR")

library(apbCatalogR)
catalog_version()
#> $version
#> [1] "0.1.4"
#> 
#> $origin
#> [1] "shipped"
#> 
#> $path
#> [1] "/tmp/Rtmpuk0F7y/Rinst13ea1d3ba0df/apbCatalogR/extdata/bundle"
#> 
#> $apb2_version
#> [1] "0.1.1"

Sets

Each set serves one kind of consumer, and each holds the fields one producer writes: apb_alpha what apb2 convert writes, fasta_peptides_alpha what apb-fasta verify-peptides adds, fasta_proteins_alpha what apb-fasta merge-annotations adds, and obs_annotation_alpha the sample annotation apb2 annotate attaches:

sets()[, c("set", "has_requirements", "entries")]
#>                            set has_requirements entries
#> 1              abundance_alpha             TRUE      45
#> 2             confidence_alpha            FALSE      26
#> 3 proteobench_entrapment_alpha            FALSE       7
#> 4                    apb_alpha             TRUE     181
#> 5         obs_annotation_alpha            FALSE       7
#> 6         fasta_peptides_alpha            FALSE      28
#> 7         fasta_proteins_alpha            FALSE       4
#> 8         chromatography_alpha            FALSE      58

catalog_table() lists the entries of a set, one row per field and software version pattern:

entries <- catalog_table("confidence_alpha")
columns <- c("software_version_pattern", "level", "name", "key")
entries[entries$source == "Spectronaut", columns]
#>    software_version_pattern           level               name             key
#> 29            ^(19|20)\\..* peptidoform_ion             EG_PEP             pep
#> 30                 ^15\\..* peptidoform_ion             EG_PEP             pep
#> 31                 ^21\\..* peptidoform_ion             EG_PEP             pep
#> 32            ^(19|20)\\..* peptidoform_ion          EG_Qvalue         q_value
#> 33                 ^15\\..* peptidoform_ion          EG_Qvalue         q_value
#> 34                 ^21\\..* peptidoform_ion          EG_Qvalue         q_value
#> 35            ^(19|20)\\..*         protein PG_QValue_Run_Wise         q_value
#> 36                 ^21\\..*         protein PG_QValue_Run_Wise         q_value
#> 37            ^(19|20)\\..*         protein          PG_Qvalue         q_value
#> 38                 ^21\\..*         protein          PG_Qvalue         q_value
#> 39                 ^21\\..*         protein   PG_LibraryQvalue library_q_value
#> 40                 ^21\\..* peptidoform_ion   EG_LibraryQvalue library_q_value

Which column a software version reports

Catalog answers from the catalog alone, without data. Its levels are the levels apb2 converts for that software version, each with the slots layers, var and obs, holding field names:

catalog <- Catalog$new("DIA-NN", "2.2.0", "abundance_alpha")
catalog
#> <Catalog abundance_alpha: peptidoform_ion, protein>
catalog$levels$peptidoform_ion$layers$keys()
#> [1] "intensity"                   "intensity_ms1"              
#> [3] "intensity_ms1_norm_settings" "intensity_norm_settings"
catalog$levels$peptidoform_ion$layers[["intensity"]]
#> [1] "Precursor_Quantity"
catalog$levels$protein$layers[["intensity_norm_settings"]]
#> [1] "PG_MaxLFQ"

[ on var or obs names every column the keys read. Spectronaut 21 reports two protein q-values:

spectronaut <- Catalog$new("Spectronaut", "21.0", "confidence_alpha")
spectronaut$levels$protein$var$keys()
#> [1] "library_q_value" "q_value"
spectronaut$levels$protein$var[c("q_value", "library_q_value")]
#> [1] "PG_Qvalue"        "PG_LibraryQvalue"

$fields() lists every cataloged field of the version as a table; each entry’s id names the software, version, level and slot where the field lives:

spectronaut$fields()[, c("key", "entry_id")]
#>               key                                              entry_id
#> 1             pep         Spectronaut/*/peptidoform_ion/layers/EG_PEP/-
#> 2         q_value      Spectronaut/*/peptidoform_ion/layers/EG_Qvalue/-
#> 3 library_q_value Spectronaut/21/peptidoform_ion/var/-/EG_LibraryQvalue
#> 4         q_value    Spectronaut/21/protein/layers/PG_QValue_Run_Wise/-
#> 5         q_value                Spectronaut/21/protein/var/-/PG_Qvalue
#> 6 library_q_value         Spectronaut/21/protein/var/-/PG_LibraryQvalue

The data of a result

read_parsed_levels() reads a result apb2 wrote, .parquet, .h5ad or .duckdb, into ParsedLevels, one anndataR AnnData per level. The test bundle carries synthetic Parquet results; this one has MaxQuant’s peptidoform-ion level.

results <- tempfile()
archive <- system.file(
    "extdata", "test-bundle", "results.tar.gz",
    package = "apbCatalogR"
)
utils::untar(archive, exdir = results)
result <- read_parsed_levels(
    file.path(results, "maxquant_wide-peptidoform_ion.parquet")
)
result
#> <ParsedLevels>
#>   peptidoform_ion: 2 x 3, layers: Intensity, MS_MS_count, Retention_time, Retention_length, Calibrated_retention_time, Calibrated_retention_time_start, Calibrated_retention_time_finish, Score, PEP
result$levels$peptidoform_ion
#> InMemoryAnnData object with n_obs × n_vars = 2 × 3
#>     obs: 'Raw_file', 'Experiment', 'Fraction'
#>     var: 'ProForma_ion', 'Sequence', 'Modified_sequence', 'Modifications', 'Charge', 'Mass', 'Proteins', 'Leading_proteins', 'Leading_razor_protein', 'protein_Protein_IDs', 'Protein_IDs', 'ProForma_peptidoform', 'ProForma_peptide', 'Reverse', 'Potential_contaminant', 'apb_Decoy', 'apb_Contaminant'
#>     uns: 'apb'
#>     layers: 'MS_MS_count', 'Retention_time', 'Retention_length', 'Calibrated_retention_time', 'Calibrated_retention_time_start', 'Calibrated_retention_time_finish', 'Score', 'PEP'

DataCatalog answers on the result and hands back the data. It composes the named sets alone: apb_alpha, APB’s own fields, answers only when named.

confidence <- DataCatalog$new(result, "confidence_alpha", "apb_alpha")
pep <- confidence$levels$peptidoform_ion$layers[["pep"]]
dim(pep)
#> [1] 2 3

$fields() lists the cataloged fields the result holds, from both sets:

confidence$fields()[, c("set", "slot", "name", "key", "present")]
#>                set   slot                 name                key present
#> 1 confidence_alpha layers                  PEP                pep    TRUE
#> 2        apb_alpha    var     ProForma_peptide            peptide    TRUE
#> 3        apb_alpha    var ProForma_peptidoform        peptidoform    TRUE
#> 4        apb_alpha    var         ProForma_ion    peptidoform_ion    TRUE
#> 5        apb_alpha    var            apb_Decoy              decoy    TRUE
#> 6        apb_alpha    var      apb_Contaminant        contaminant    TRUE
#> 7        apb_alpha    var          Protein_IDs protein_assignment    TRUE
#> 8        apb_alpha    var             Proteins   fasta_accessions    TRUE

Each level of the catalog has anndataR’s slots. A name is read as a key first, then as the level’s own layer or column, as the Python package cf_xarray finds an xarray variable by its CF-convention standard name first. ?Level and ?Slot list the methods:

ion <- confidence$levels$peptidoform_ion
dim(ion$layers[["pep"]])            # a matrix, runs x features
#> [1] 2 3
ion$layers$keys()                   # a character vector
#> [1] "pep"
head(ion$var[["peptidoform_ion"]])  # a vector, one value per feature
#> [1] "F0" "F1" "F2"

The slots read the anndataR AnnData of the level, so a key gives the same data as the vendor’s name in anndataR. A vendor’s own name still reads, and [ gives a data frame, as on anndataR’s obs and var:

# The anndataR AnnData of the level
adata <- result$levels$peptidoform_ion
identical(ion$layers[["pep"]], adata$layers[["PEP"]])
#> [1] TRUE
identical(ion$X, adata$X)
#> [1] TRUE
ion$obs_names
#> [1] "S0" "S1"
ion$var_names
#> [1] "F0" "F1" "F2"
# MaxQuant's own layer, as adata$layers[["Score"]]
ion$layers[["Score"]]
#>     F0  F1  F2
#> S0 0.8 0.9 1.0
#> S1 0.9 1.0 1.1
# A data frame, as adata$obs[c("Raw_file", "Experiment")]
ion$obs[c("Raw_file", "Experiment")]
#>   Raw_file Experiment
#> 1       S0         v0
#> 2       S1         v1
# Keys, each column named as the result names it
ion$var[c("peptidoform_ion", "decoy", "contaminant")]
#>   ProForma_ion apb_Decoy apb_Contaminant
#> 1           F0      TRUE            TRUE
#> 2           F1     FALSE           FALSE
#> 3           F2      TRUE            TRUE

A vendor may name a column as a key is named, as Sage names its quantification q-value q_value. A prefix makes the lookup exact: a set’s prefix asks that set alone and never the level’s own field, v: the level’s own field alone and never the catalog. sets() lists each set’s prefix:

ion$layers$name("c:pep")    # the confidence set alone
#> [1] "PEP"
ion$layers$name("v:Score")  # MaxQuant's own layer alone
#> [1] "Score"
sets()[, c("set", "prefix")]
#>                            set prefix
#> 1              abundance_alpha      a
#> 2             confidence_alpha      c
#> 3 proteobench_entrapment_alpha    pbe
#> 4                    apb_alpha    apb
#> 5         obs_annotation_alpha  annot
#> 6         fasta_peptides_alpha   fpep
#> 7         fasta_proteins_alpha  fprot
#> 8         chromatography_alpha     rt

MaxQuant reports no q-value on this level, so $get() gives NULL, where [[ signals an error; $name() names the field a key reads:

ion$layers$get("q_value")
#> NULL
ion$layers$name("pep")
#> [1] "PEP"

A lookup the catalog cannot answer with one field signals UnresolvedField rather than choosing silently. Spectronaut does not document how its protein quantity combines the precursors, so asking for a summed one is unknown there:

spectronaut <- Catalog$new("Spectronaut", "21.0", "abundance_alpha")
tryCatch(
    spectronaut$levels$protein$layers$get(
        "intensity_norm_settings",
        aggregation = "sum"
    ),
    UnresolvedField = function(condition) conditionMessage(condition)
)
#> [1] "intensity_norm_settings (kind=intensity, normalization=run_setting, aggregation=sum) on protein is unknown: PG_Quantity leaves aggregation unknown; candidates: PG_Quantity"

The same code for every software

The same lookup reads each software’s field; the test bundle holds results of many:

files <- c(
    MaxQuant = "maxquant_wide-peptidoform_ion.parquet",
    Spectronaut = "spectronaut_v21-peptidoform_ion.parquet",
    `DIA-NN` = "diann_v2-peptidoform_ion.parquet"
)
pep_field <- function(file) {
    vendor <- read_parsed_levels(file.path(results, file))
    catalog <- DataCatalog$new(vendor, "confidence_alpha")
    catalog$levels$peptidoform_ion$layers$name("pep")
}
vapply(files, pep_field, character(1))
#>    MaxQuant Spectronaut      DIA-NN 
#>       "PEP"    "EG_PEP"       "PEP"

A protein level reads the same way; DIA-NN’s MaxLFQ intensity, normalized as the run’s settings chose, is the key intensity_norm_settings:

diann <- read_parsed_levels(file.path(results, "diann_v2-protein.parquet"))
protein <- DataCatalog$new(diann, "abundance_alpha")$levels$protein
protein$layers$keys()
#> [1] "intensity_norm_settings"
protein$layers$name("intensity_norm_settings")
#> [1] "PG_MaxLFQ"
protein$layers[["intensity_norm_settings"]]
#>     F0  F1  F2
#> S0 0.0 0.1 0.2
#> S1 0.1 0.2 0.3

Several sets and qualifiers

DataCatalog$new() composes several sets on one result. A key may leave a qualifier open, such as the unit of a retention time; $get() and $name() narrow it, and a lookup no field answers gives NULL:

both <- DataCatalog$new(result, "confidence_alpha", "chromatography_alpha")
both
#> <DataCatalog confidence_alpha, chromatography_alpha: peptidoform_ion>
rt <- both$levels$peptidoform_ion
rt$layers$keys()
#> [1] "aligned_peak_end"       "aligned_peak_start"     "aligned_retention_time"
#> [4] "peak_width"             "pep"                    "retention_time"
rt$layers$name("retention_time", unit = "minute")
#> [1] "Retention_time"
rt$layers$get("retention_time", unit = "second")
#> NULL

Sets an app or an annotation answers

A set of an app’s fields answers once the app has run, and the sample annotation once apb2 annotate has attached it. Opening such a set on a result that lacks them is an error that says what to run:

tryCatch(
    DataCatalog$new(result, "fasta_peptides_alpha"),
    error = function(condition) conditionMessage(condition)
)
#> [1] "fasta_peptides_alpha: apb-fasta has not run on this result; run `apb-fasta verify-peptides`"

DataCatalog$answering_sets() lists the sets a result opens, without an error, so a consumer can leave out the fields of an app that has not run:

DataCatalog$answering_sets(result)
#> [1] "abundance_alpha"              "confidence_alpha"            
#> [3] "proteobench_entrapment_alpha" "apb_alpha"                   
#> [5] "chromatography_alpha"

Requirements

A set may require or recommend fields. enforce checks them once, when the catalog opens: "required" signals one MissingRequiredField listing every missing required field and warns about missing recommended ones; "recommended" signals for both. MaxQuant’s peptidoform level lacks a recommended field of apb_alpha:

peptidoform <- read_parsed_levels(
    file.path(results, "maxquant_wide-peptidoform.parquet")
)
tryCatch(
    DataCatalog$new(peptidoform, "apb_alpha", enforce = "recommended"),
    MissingRequiredField = function(condition) conditionMessage(condition)
)
#> [1] "recommended field peptidoform (kind=peptidoform) on peptidoform is missing: no reviewed MaxQuant ^(1\\.5|1\\.6|2\\.) entry on peptidoform matches"

Rule coverage

rule_coverage() checks every rule against one set; a set with requirements judges each level:

coverage <- rule_coverage("abundance_alpha")
unique(coverage[, c("software", "version", "level", "verdict")])[1:5, ]
#>    software version           level verdict
#> 1  AlphaDIA    1.10 peptidoform_ion    warn
#> 3  AlphaDIA    1.12 peptidoform_ion    warn
#> 5  AlphaDIA     2.x peptidoform_ion    warn
#> 7  AlphaDIA     2.x         protein    <NA>
#> 8 AlphaPept     0.5 peptidoform_ion    pass

A newer catalog

update_catalog() installs a bundle archive into the user cache; later sessions use the newest bundle, shipped or installed. apb-catalog’s make bundle writes the archive. Nothing is downloaded.

update_catalog("apb-catalog/build/apb-catalog-bundle.tar.gz")

Session information

sessionInfo()
#> R version 4.6.2 (2026-10-29)
#> Platform: x86_64-pc-linux-gnu
#> Running under: Ubuntu 26.04.1 LTS
#> 
#> Matrix products: default
#> BLAS:   /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3 
#> LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.32.so;  LAPACK version 3.12.0
#> 
#> locale:
#>  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
#>  [3] LC_TIME=en_US.UTF-8        LC_COLLATE=en_US.UTF-8    
#>  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8   
#>  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C                 
#>  [9] LC_ADDRESS=C               LC_TELEPHONE=C            
#> [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       
#> 
#> time zone: Etc/UTC
#> tzcode source: system (glibc)
#> 
#> attached base packages:
#> [1] stats     graphics  grDevices utils     datasets  methods   base     
#> 
#> other attached packages:
#> [1] apbCatalogR_0.99.4 BiocStyle_2.41.0  
#> 
#> loaded via a namespace (and not attached):
#>  [1] vctrs_0.7.3         cli_3.6.6           knitr_1.52         
#>  [4] rlang_1.3.0         xfun_0.62           otel_0.3.0         
#>  [7] png_0.1-9           purrr_1.2.2         assertthat_0.2.1   
#> [10] jsonlite_2.0.0      glue_1.8.1          bit_4.6.0          
#> [13] buildtools_1.0.0    htmltools_0.5.9     maketools_1.3.2    
#> [16] sys_3.4.3           sass_0.4.10         rmarkdown_2.32     
#> [19] grid_4.6.2          evaluate_1.0.5      jquerylib_0.1.4    
#> [22] fastmap_1.2.0       yaml_2.3.12         lifecycle_1.0.5    
#> [25] BiocManager_1.30.27 compiler_4.6.2      Rcpp_1.1.2         
#> [28] anndataR_1.3.5      lattice_0.23-1      digest_0.6.39      
#> [31] R6_2.6.1            tidyselect_1.2.1    reticulate_1.47.0  
#> [34] magrittr_2.0.5      bslib_0.12.0        Matrix_1.7-6       
#> [37] bit64_4.8.6         tools_4.6.2         arrow_26.0.1       
#> [40] cachem_1.1.0

Looking up APB fields by meaning