NEWS

apbCatalogR 0.99.0

First version: apb-catalog's API in R on the apb-catalog bundle: the R6 classes Catalog and DataCatalog, catalogues(), rule_coverage(), catalogue_table() and the conditions UnresolvedField and MissingRequiredField.
Needs R 4.6.0 or later, the R of Bioconductor 3.24; CI checks on R 4.6.
Reading a .duckdb result no longer keeps a duckdb home under ~/.duckdb.
CITATION.cff and .zenodo.json describe the package to GitHub and Zenodo; citation("apbCatalogR") cites its Zenodo DOI, 10.5281/zenodo.23928865.
The README and the vignette open with a figure of who does what: quantification software, apb2, the APB result and catalog, the apb-catalog API and Bioconductor applications; tools/draw_actors.py draws it.
read_parsed_levels() reads an APB Parquet result into ParsedLevels, one anndataR AnnData per level. It also reads apb2's .h5ad and .duckdb results into the same ParsedLevels; Parquet needs the suggested arrow package and DuckDB the suggested duckdb and DBI packages; .h5ad needs only anndataR 1.2.2 or later, the first to read the text columns apb2 writes.
Lookups ask by key: each set lists its keys in the bundle's keys.csv, each a kind with the qualifier values it fixes, such as "normalized_intensity" (kind intensity, normalization run_setting); further qualifiers, such as unit, narrow a lookup, and one the key fixes is an error. The abundance set has its normalization qualifier again; asking "intensity" where the normalization is unknown is unknown. q_value in var is the q-value across the experiment (was global_q_value); Sage's is "quantification_q_value". catalogue_table() and fields() have key and kind columns, rule_coverage() a key column.
update_catalog() downloads the bundle of an apb-catalog release; catalog_version() reports the bundle in use.
The bundle holds only the catalogue tables; the synthetic results and expected answers ship as a separate test bundle in inst/extdata/test-bundle/.
Bundle format 2: the catalogue sets are six CSV tables (entries, entry_qualifiers, vocabulary, keys, requirements, producers) described by datapackage.json; a vendor catalogue reviews every rule level the bundle's rule_levels.csv lists, and every qualifier lists unknown as a value. Bundles of format 1 are passed over.
Entries name the software version patterns they were reviewed for, not apb2's rule files, and the bundle carries no rules: rule_levels.csv gives the levels apb2 converts for each software version. apb2's own columns (ProForma_*, apb_Decoy, the protein-assignment columns) are each software's entries in the apb set. catalogue_table() and fields() name software_version_pattern and have no rule column; rule_coverage() has software_version_pattern and neither rule nor inputs.
Bundle format 3: entries name software versions by their labels (1.8–1.9, 2.x) in a version column, and versions.csv (software, version, version pattern) replaces rule_levels.csv; a version's levels are the levels its entries name. Bundles of format 2 are passed over. Answers are unchanged; rule_coverage() lists a version's levels in the order its entries first name them.
Entry ids name where a field lives, built as CPE names are: <source>/<version>/<level>/<attribute>/<key>/<column>, such as DIA-NN/2.x/peptidoform_ion/layers/PEP/-; * as version is every version of the source, and a trailing * in the column matches obs columns by prefix. entries.csv keeps set, entry_id, kind, basis and evidence_url; one id with two kinds is two rows, and entry_qualifiers.csv joins on entry_id and kind. A prefix entry bound to a result's column takes that column's id. An app's or annotation convention's entry may name level *, every level: it answers on each, taking that level in its reference and id, and catalogue_table() gives it one row with level *. Answers are unchanged; catalogue_table() and fields() show the new entry_id values.
DataCatalog$new(result, ...) composes the named catalogue sets with apb, which is always in; a key routes to the sets that define it, and two sets naming different fields for one key on one level is an error. Its levels give anndataR's slots looked up as cf_xarray does: cat$levels$protein$layers[["maxlfq"]] reads a key, else the level's own layer of that name, else an error; X, var[[...]], obs[[...]], obs_names, var_names; $keys() lists keys only.
var[c(...)] and obs[c(...)] read every column the names name as a data frame, as cf_xarray's ds.cf[["name"]]: both contaminant flags where the vendor and apb-fasta each set one, every prolfquapp group column; [[ still signals UnresolvedField there. A varm column is named table/column.
keys() lists only the keys a field the level holds answers: an app's keys, such as apb-fasta's, appear once it has run, so every key listed reads; asking for one before still signals UnresolvedField naming what to run.
Catalog$new() has levels too, with the same slots holding names: catalog$levels$peptidoform_ion$layers[["intensity"]] is "Precursor_Quantity", and [ returns a character vector.
A level's slots have $get(key, ...), which returns NULL where [[ signals an error, and $name(key, ...), the name of the field $get() reads ("PEP", or table/column for a varm column); both take the qualifiers a key leaves open, such as unit = "minute". On a Catalog's levels $get() returns the name.
Lookups go through levels only: Catalog and DataCatalog have no lookup methods of their own, and a slot's $keys() takes no qualifiers.
The vignette shows a level's slots beside anndataR's, one lookup across MaxQuant, Spectronaut and DIA-NN, a protein level, and composed sets with a qualifier.
Snapshots are not ported: DataCatalog$snapshot(), $resolve(), attach_snapshot() and ResolutionSnapshot have no R counterpart.