Skip to content

proteins: wire verbs

The facts on this page are the same facts mzLibRust and mzLibR publish, because all three render them from one spec per wire verb. The parameter, result, error and caveat tables are generated; edit the spec, not this page. How the reference facts are generated explains the mechanism. For the Python signatures and result classes, see the API reference. For worked tasks, see the Protein databases guide.

Python spells the database inputs differently from the wire. Each function takes one database or a list as its first argument, and contaminant databases as contaminants=. pyMzLib chooses --path, --contaminant or --paths-stdin from those, so the tables' path, contaminant and paths_stdin rows describe the wire, not Python keywords. accessions_stdin is Python's accessions= list. genes resolve is a wire verb of the genes module, and Python projects it as pymzlib.proteins.resolve_genes.

annotate_go takes the table and the database positionally (groups, database), as the wire's --groups and --database; every other option is a keyword with the wire's name in snake case. Its rows are windowed by limit/offset, while out= always receives the whole table, so a large run is out= plus limit=0.

Multi-table output is JSON only. proteins read has no out option: its three tables would need three files. Performance: each call starts one bridge process, about 120 ms before mzLib does any work, and each database is read whole. Pass all your databases in one call rather than looping, and raise threads only if memory allows one whole database per thread.

read

Read protein databases (UniProt XML or FASTA) into one row per protein, with GO terms and Ensembl gene links as long tables on request.

Wire verb proteins read · Python pymzlib.proteins.read

Wraps

Parameters

Parameter Type Default Unit Range Meaning
path path absent — — One database: UniProt XML (.xml) or FASTA (.fasta, .fa, .faa, .fas), each optionally .gz. Exactly one of path and paths-stdin.
contaminant flag false — — Load the --path database as contaminants (mzLib isContaminant). Usage error with paths-stdin.
paths_stdin (wire --paths-stdin) flag false — — Databases on stdin, one per line, each optionally followed by a tab and 'contaminant' or 'target'. Blank lines ignored; a repeated path is a usage error (BULK.md §1).
accessions_stdin (wire --accessions-stdin) flag false — — Keep only proteins whose accession exactly equals one read from stdin (one per line). With paths-stdin, stdin holds the paths, then a line holding only '--', then the accessions. Applies to every table.
tables string[] proteins — subset of proteins, go_terms, ensembl_genes Comma list of the tables to return. A table not asked for is null.
sequences flag false — — Add a sequence column to the proteins table.
threads int 1 — >= 1, or -1 for every core Databases loaded at once. Output is byte-identical at any value (tested at 1 and 4). mzLib's own maxThreads is pinned to 1 per load, so the degree is owned here alone.
on_error (wire --on-error) string fail — fail \| skip fail raises the failure of the LOWEST failing input index; skip records it in files[i].error and reads the rest.

Returns

Top-level fields:

Field Type Unit Null? Meaning
file_count int files never Databases given.
read_count int files never Databases read.
failed_count int files never Databases that failed (on-error skip only).
record_count int proteins never Proteins that passed the accession filter (rows of the proteins table when requested).
tables string[] — never The tables returned, in the order proteins, go_terms, ensembl_genes.
accession_filter_count int accessions yes: no accession filter was given Distinct accessions in the filter.
accessions_not_found string[] — yes: no accession filter was given Filter accessions no database contained, in the order given. Matching is exact: P04406-1 does not find P04406.
caveats string[] — never Whole-result traps, e.g. proteins with no computable mass.
files object[] — never One per input in input order (BULK.md §3): source_index, path (absolute), file_type (UniProtXml | Fasta | null if it failed first), reader, contaminant, protein_count, decoy_count, record_count, search_database_sha256 (null here), caveats, absent_fields, error (null or {kind: usage|correctness, type, message}). Present with --path too, so one shape serves both.
column_names string[] — yes: the proteins table was not requested Column order of the proteins table.
columns table — yes: the proteins table was not requested Column name to per-protein values.
go_terms object — yes: go_terms was not requested {row_count, column_names, columns}: one row per (protein, GO id), with columns source_index, source_path, accession, go_id, aspect, term_name, evidence_codes, projects (typed under result.tables.go_terms in this spec).
ensembl_genes object — yes: ensembl_genes was not requested {row_count, column_names, columns}: one row per (protein, Ensembl transcript), with columns source_index, source_path, accession, transcript_id, protein_id, gene_id, versioned_gene_id, gene_version (typed under result.tables.ensembl_genes in this spec).

Per-row fields (one value per record, in columns or each list entry):

Field Type Unit Null? Meaning
source_index int — never Position of the input in files (paths first, in order).
source_path string — never Absolute path of that input.
accession string — never As the database wrote it. A FASTA with a repeated accession gets _2, _3 appended by mzLib; an XML entry with an applied genotype variant gets a variant suffix (see caveats).
name string — yes: the database records no entry name Entry name, e.g. G3P_HUMAN.
full_name string — yes: the database records no protein name Recommended protein name.
organism string — yes: the database records no organism Scientific name (the XML organism element, FASTA OS=).
ncbi_taxonomy_id string — yes: the entry records no taxonomy id (a FASTA header without OX=) NCBI taxon, e.g. "9606". A string because it is an identifier.
primary_gene_name string — yes: the entry names no primary gene Primary gene name (the XML gene name of type primary, FASTA GN=).
gene_names string[] — never Every gene name the entry gives, in file order (primary, synonyms, ORF, locus). May be empty; may repeat when the file repeats.
length int residues never Sequence length.
monoisotopic_mass float Da yes: the sequence holds a letter with no defined residue mass (X, B, Z, J) Monoisotopic mass of the unmodified sequence as written plus one water: the precursor, initiator Met and signal peptide included.
is_contaminant bool — never Loaded from a database marked contaminant.
is_decoy bool — never The file marks it a decoy (accession prefix DECOY). None are generated.
is_entrapment bool — never mzLib's entrapment flag (FASTA accession containing 'Random', case-insensitive).
ensembl_gene_ids string[] — never Distinct stable Ensembl gene ids (Protein.EnsemblGeneIds), ordinal order. Empty for a FASTA: see absent_fields.
sequence string — never The base sequence. Present only with sequences.

Fields of go_terms:

Field Type Unit Null? Meaning
source_index int — never Input position.
source_path string — never Input path.
accession string — never The protein.
go_id string — never GO accession, e.g. GO:0005737. Unique per protein.
aspect string — never mzLib GoAspect name: BiologicalProcess, CellularComponent, MolecularFunction, or Unknown when UniProt gave no C:/F:/P: prefix (never inferred).
term_name string — yes: the reference carried no term property Term name with the aspect prefix removed.
evidence_codes string[] — never ECO ids unioned over UniProt's repeats of this GO id, sorted ordinal. Empty is normal.
projects string[] — never Annotating projects (UniProtKB, MGI, HPA, ...), unioned, sorted.

Fields of ensembl_genes:

Field Type Unit Null? Meaning
source_index int — never Input position.
source_path string — never Input path.
accession string — never The protein.
transcript_id string — yes: the reference named no transcript Ensembl transcript as UniProt wrote it, versioned.
protein_id string — yes: UniProt gave no Ensembl protein id Ensembl protein id as written.
gene_id string — never Stable gene id, e.g. ENSG00000111640: the one to join on.
versioned_gene_id string — never As UniProt wrote it, e.g. ENSG00000111640.15; equal to gene_id when unversioned.
gene_version int — yes: the id carried no numeric version (absent is not 0) The gene version.

Errors

Kind pyMzLib raises When
usage UsageError neither or both of path and paths-stdin; contaminant with paths-stdin; no paths on stdin; a blank or repeated path; a role other than target/contaminant; accessions-stdin with no accessions; paths-stdin with accessions-stdin but no '--' line
usage UsageError tables names something else; threads 0 or < -1; on-error not fail/skip; an option given without a value
usage UsageError a database not named .xml or a FASTA extension; a missing database (under skip: recorded in files[i].error with kind usage)
correctness BridgeError mzLib cannot parse a database (malformed XML); under skip, recorded with kind correctness
service_unavailable ServiceUnavailableError never raised by this verb

Caveats

  • A FASTA carries no GO or Ensembl cross-references: its files[i].absent_fields is [go_terms, ensembl_genes, ensembl_gene_ids] and it contributes no rows to either table. Empty there means the format is silent, not that no annotation exists.
  • Decoys are not generated (DecoyType.None), but decoys already in the file are kept with is_decoy true.
  • Sequence variants are not expanded (maxHeterozygousVariants 0), except that mzLib still applies variants a VCF-annotated XML records a genotype for; such proteins carry a variant accession suffix, and the file's caveats count them.
  • GO terms are the terms as annotated, not propagated up the GO graph.
  • Parallel XML loads share ProteinDbLoader's static modification state; it affects only modification resolution, which this verb does not report, and output was byte-identical at threads 1 and 4.

Example

db = pymzlib.proteins.read([xml, fasta, mouse], contaminants=[bovine], tables=pymzlib.proteins.TABLES)

Recorded from the live bridge as proteins_read_human.json. The doctests in the API reference replay these recordings in CI.

Same verb in other bindings

Python (pyMzLib) Rust (mzLibRust) R (mzLibR)
pymzlib.proteins.read mzlib::proteins::read_with with ProteinReadOptions proteins_read

References

  • doi:10.1038/75556: The Gene Ontology and its three aspects (Ashburner et al. 2000, Nature Genetics)
  • doi:10.1093/nar/gkae1010: UniProt, the source of the XML's organism, taxonomy, GO and Ensembl cross-references (UniProt Consortium 2025, NAR)
  • doi:10.1093/nar/gkaf1239: Ensembl, whose transcript and gene ids the ensembl_genes table carries (Ensembl 2026, NAR)

Since

Wire protocol pyMzLib mzLibRust mzLibR
1 0.2.0 0.1.0 0.1.0

Not yet verified

  • files[] is always present, with --path too, instead of BULK.md §3's flattened single-file block: a new verb has no pre-existing single-file shape to preserve, and one shape is simpler for every binding. Confirm or amend BULK.md.
  • Two lists sharing stdin, separated by a line holding only '--', is new wire grammar (also used by proteins classify-peptides). It belongs in CONTRACT.md or BULK.md if adopted.
  • result.tables (go_terms, ensembl_genes) is not validated by tools/check_verbs.py, which checks only 'columns'; the pyMzLib tests pin them.
  • No --out TSV mode yet (BULK.md §2 mentions one): multi-table output is JSON only, since three tables would need three files.
  • proteins_read_filtered.json (an accession-filtered read) is a second recording used by the pyMzLib tests; it is not listed as an example because the doctest replay bridge cannot tell two recordings of one verb apart by stdin.

resolve_genes

Resolve every protein in the given databases to stable Ensembl gene ids, counted against a caller-supplied, release-pinned gene set, with one outcome per protein and the hash of every input.

Wire verb genes resolve · Python pymzlib.proteins.resolve_genes

Wraps

Parameters

Parameter Type Default Unit Range Meaning
path path absent — — One search database (UniProt XML for real answers; a FASTA carries no gene links). Exactly one of path and paths-stdin.
contaminant flag false — — Load the --path database as contaminants: every protein is contaminant_not_mapped.
paths_stdin (wire --paths-stdin) flag false — — Databases on stdin, one per line, optionally followed by a tab and 'contaminant' or 'target' (BULK.md §1).
gtf path absent — — An Ensembl GTF, plain or .gz; only gene rows are read. Use the primary-assembly GTF (Species.Assembly.Release.gtf.gz) and keep Ensembl's file name, which carries the release. Exactly one of gtf and gene-set; there is no default.
gene_set (wire --gene-set) path absent — — Instead of gtf: a compact gene table from mzLib's EnsemblGeneSetWriter. It carries the GTF's provenance, so rows are keyed as against the GTF (tested byte-identical).
xref path absent — — Optional Ensembl Species.Assembly.Release.uniprot.tsv(.gz): per-row agreement, and a row per gene only Ensembl links (source ensembl_xref).
threads int 1 — >= 1, or -1 for every core Databases loaded (and hashed) at once. Output identical at any value.
on_error (wire --on-error) string fail — fail \| skip As proteins read.

Returns

Top-level fields:

Field Type Unit Null? Meaning
file_count int files never Databases given.
read_count int files never Databases read.
failed_count int files never Databases that failed (on-error skip only).
protein_count int proteins never Proteins resolved.
record_count int rows never Rows in columns: at least one per protein; one per gene for multi_gene; plus ensembl_xref rows.
gene_set object — never {source_file_name, sha256 (of the file's bytes as read: compressed for .gz), release (null: not in the file name), genome_build (null: no #!genome-build header), genebuild_last_updated (null: no header), gene_count}.
xref object — yes: no --xref was given {source_file_name, sha256, release (nullable), accession_count}.
outcome_counts map<string,int> proteins never Outcome name -> proteins with it; all six keys always present.
caveats string[] — never FASTA proteins (all not_in_source), a GTF with no release or genome build, no xref (agreement unknown, not false).
files object[] — never As proteins read; search_database_sha256 is set: lower-case hex sha256 of the DECOMPRESSED database, so .xml and .xml.gz agree.
column_names string[] — never source_index, source_path, then mzLib's GeneResolutionTsv.Schema headers in its order (a bridge test holds them equal).
columns table — never Column name to per-row values.

Per-row fields (one value per record, in columns or each list entry):

Field Type Unit Null? Meaning
source_index int — never Input position.
source_path string — never Input path.
accession string — never Verbatim, as the search reported it (a variant suffix kept).
entry_accession string — never UniProt entry or unversioned RefSeq accession; verbatim when unrecognized.
isoform int — yes: no -N isoform suffix UniProt isoform number.
namespace string — never uniprot | refseq | unrecognized.
outcome string — never resolved | multi_gene | off_primary_only | not_in_source | unrecognized_accession | contaminant_not_mapped (GeneResolutionTsv.OutcomeName).
n_genes int genes never Genes the search database links on the gene set's assembly.
gene_id string — yes: the outcome has no gene on the assembly Stable Ensembl gene id.
versioned_gene_id string — yes: no gene on the row As the database wrote it (e.g. ENSG00000111640.15); for an ensembl_xref row, built from the GTF's version, or null when the GTF has none.
gene_symbol string — yes: no gene on the row, or the GTF gives it no gene_name The release's gene_name: a display label, never a key.
gene_biotype string — yes: no gene on the row The release's gene_biotype ('unknown' when the GTF omits it).
off_primary_genes int genes never Linked genes outside the gene set (ALT haplotypes, patches, scaffolds): dropped from n_genes, counted here.
uniprot_gene_name string — yes: the entry names no primary gene The database's primary gene name, as a label.
source string — never search_database_dbreference, or ensembl_xref for a gene only Ensembl links (it carries the search database's outcome and never changes it).
search_database_sha256 string — never sha256 of the decompressed database.
gene_set_release string — yes: the GTF's file name carries no release Ensembl release.
gene_set_sha256 string — never sha256 of the GTF as read.
ensembl_xref_agrees bool — yes: no gene on the row, or no --xref: unknown, not false Whether Ensembl's xref links this accession to this gene.
ensembl_xref_info_type string — yes: Ensembl's xref does not link the pair, or no --xref Ensembl's strongest evidence: DIRECT, SEQUENCE_MATCH, INFERRED_PAIR.
ensembl_xref_sha256 string — yes: no --xref was given sha256 of the xref file.

Errors

Kind pyMzLib raises When
usage UsageError neither or both of gtf and gene-set; a missing GTF, gene set or xref; any database-selection error proteins read raises
correctness BridgeError a GTF gene row without gene_id (InvalidDataException); an xref whose header is not Ensembl's nine columns; a compact gene table mzLib's reader refuses; a database mzLib cannot parse
service_unavailable ServiceUnavailableError never raised by this verb

Caveats

  • The caller supplies and pins the gene set. Use the primary-assembly GTF, not chr_patch_hapl_scaff: counting ALT haplotypes as genes made human release 116 look 6.99% multi-gene when it is 0.36% (mzLib EnsemblGeneSet remarks).
  • A FASTA carries no Ensembl links, so every FASTA protein is not_in_source regardless of biology; the result caveats count them.
  • Contaminants are never mapped (contaminant_not_mapped), even when they would resolve.
  • multi_gene is one row per gene, never a pick.

Example

genes = pymzlib.proteins.resolve_genes([xml, fasta], contaminants=[bovine], gtf=gtf, xref=xref)

Recorded from the live bridge as genes_resolve_human.json. The doctests in the API reference replay these recordings in CI.

Same verb in other bindings

Python (pyMzLib) Rust (mzLibRust) R (mzLibR)
pymzlib.proteins.resolve_genes mzlib::proteins::resolve_genes_with with GeneResolveOptions proteins_resolve_genes

References

Since

Wire protocol pyMzLib mzLibRust mzLibR
1 0.2.0 0.1.0 0.1.0

Not yet verified

  • The wire module is 'genes' but every binding projects it in its proteins module (BULK.md §6); confirm.
  • No verb writes the compact gene set (EnsemblGeneSetWriter); callers need mzLib or a future 'genes gene-set' verb to make one.
  • The example gene set is a hand-built three-gene GTF in Ensembl's layout; O43653 is off_primary_only only because PSCA is left out of it.

classify_peptides

Classify peptides as unique to one sequence, shared within a gene, shared across genes, or not in the databases, treating I and L as the same residue.

Wire verb proteins classify-peptides · Python pymzlib.proteins.classify_peptides

Wraps

Parameters

Parameter Type Default Unit Range Meaning
path path absent — — One database. Exactly one of path and paths-stdin. With path, all of stdin is peptides.
contaminant flag false — — Load the --path database as contaminants (they are still searched).
paths_stdin (wire --paths-stdin) flag false — — stdin holds database paths (each optionally tab 'contaminant'), then a line holding only '--', then the peptides.
threads int 1 — >= 1, or -1 for every core Databases loaded at once. mzLib's classifier has no thread knob of its own; it is one pass. Output identical at any value.
on_error (wire --on-error) string fail — fail Only 'fail' is accepted: every database is one search space, and skipping one would report the peptides it holds as unique.
peptides string[] required — non-empty, letters A-Z only Read from stdin (not an option). Unmodified base sequences, upper case, one per line; blank lines ignored. One result per peptide, in order, duplicates included.

Returns

Top-level fields:

Field Type Unit Null? Meaning
file_count int files never Databases searched.
peptide_count int peptides never Rows (input peptides).
target_protein_count int proteins never Non-decoy proteins searched, contaminants included.
decoy_proteins_ignored int proteins never Decoy entries present in the files and never searched.
i_and_l_equivalent bool — never Always true: I and L are one residue for matching. On the wire so the rule travels with the result.
sharing_counts map<string,int> peptides never Class -> peptides; all four keys always present.
files object[] — never As proteins read; record_count is the target proteins searched from that file.
column_names string[] — never Column order.
columns table — never Column name to per-peptide values.

Per-row fields (one value per record, in columns or each list entry):

Field Type Unit Null? Meaning
peptide string — never Exactly as given (not I/L-folded).
sharing string — never mzLib PeptideSharing name: NotInDatabase | Unique (every containing protein has one sequence) | SharedWithinGene (several sequences sharing a gene key) | SharedAcrossGenes.
accession_count int proteins never Target proteins containing the peptide.
accessions string[] — never Those proteins, distinct, ordinal order; empty for NotInDatabase.
shared_gene_keys string[] — never Gene keys common to all of them (ensembl:ENSG..., gene:ORGANISM:PRIMARY_NAME, entry:UNIPROT_ENTRY), ordinal order. Empty for NotInDatabase and SharedAcrossGenes.

Errors

Kind pyMzLib raises When
usage UsageError no peptides; a peptide that is not non-empty A-Z (mzLib's ArgumentException, reclassified; the message names the peptide) - lower case and bracketed modifications included
usage UsageError on-error other than fail; any database-selection error proteins read raises; paths-stdin without the '--' line
correctness BridgeError a database mzLib cannot parse
service_unavailable ServiceUnavailableError never raised by this verb

Caveats

  • Containment, not digestion: a protein contains a peptide if its sequence contains it anywhere, whatever the protease. Deliberately conservative.
  • Identical sequences under different accessions are one sequence: the peptide is Unique and lists both accessions.
  • Contaminants are searched; leaving the contaminant database out can turn a SharedAcrossGenes peptide (YLYEIAR, human and bovine albumin) into Unique.
  • A FASTA protein has no ensembl: key, so gene sharing for it rests on organism + primary gene name and the UniProt entry.

Example

calls = pymzlib.proteins.classify_peptides(["VGVNGFGR", "LVLNGNPLTLFQER", "ALSEQINIFFDYSGR", "YLYEIAR", "AEFVEVTK", "PEPTIDEK"], [xml, fasta], contaminants=[bovine])

Recorded from the live bridge as proteins_classify_peptides.json. The doctests in the API reference replay these recordings in CI.

Same verb in other bindings

Python (pyMzLib) Rust (mzLibRust) R (mzLibR)
pymzlib.proteins.classify_peptides mzlib::proteins::classify_peptides_with with ClassifyOptions proteins_classify_peptides

References

Since

Wire protocol pyMzLib mzLibRust mzLibR
1 0.2.0 0.1.0 0.1.0

Not yet verified

  • The gene-key function is mzLib's DefaultGeneKeys and is not selectable on the wire.
  • The peptides param travels on stdin, not as an option; the spec format has no stdin field yet, so its doc says so.

annotate_go

Annotate a stored MetaMorpheus protein-group table with Gene Ontology terms: one row per (group, term) that any member holds, directly or through an ancestor, with no member privileged.

Wire verb proteins annotate-go · Python pymzlib.proteins.annotate_go

Wraps

Parameters

Parameter Type Default Unit Range Meaning
groups path required — — A MetaMorpheus protein-group table: AllQuantifiedProteinGroups.tsv, AllProteinGroups.tsv (no quantification, mzLib #1365) or a file's _ProteinGroups.tsv. Read by ProteinGroupFromTsvFile.
database path required — — The UniProt XML (.xml or .xml.gz) whose GO terms annotate the members: the proteome the search used. Exactly one, because every row carries that database's sha256. A FASTA is a usage error: it carries no GO.
go_obo (wire --go-obo) path required — — A go.obo file, which must exist. Nothing is downloaded (see proteins update-go), so the release is always one the caller chose to keep.
skip_unknown_go_ids (wire --skip-unknown-go-ids) flag false — — Drop each GO id the database cites that the release lacks, listing it in unresolved_go_ids, instead of failing on the first run that meets one.
category_map (wire --category-map) path absent — — A consumer term-to-category map in mzLib's format (#!category_map_format 1, #!map_name, #!map_version; columns category, subcategory, anchor_go_id). Adds the categories table. mzLib ships no map.
out path absent — .tsv only, any case (PYB-1) Write the WHOLE table here with GoAnnotationTsv.Write, header included, whatever offset and limit are. Written atomically through .partial. Must not name an input; its folder must exist.
categories_out (wire --categories-out) path absent — .tsv only, any case (PYB-1) Write the category table here with GoCategoryTsv.Write. Needs category-map.
offset int 0 rows >= 0 Skip this many rows in the payload.
limit int absent rows >= 0 Return at most this many rows. Absent means every row. 0 returns only the summary, the usual pairing with out for a large run.

Returns

Top-level fields:

Field Type Unit Null? Meaning
groups_file string — never Absolute path of the protein-group table.
groups_file_sha256 string — never Lower-case hex sha256 of the table's bytes; also the header's source_file_sha256.
table_row_count int rows never Rows in the table, decoys included.
decoy_group_count int groups never Decoy rows (label contains D, so an entrapment decoy ED too), skipped: decoys carry no GO.
group_count int groups never Groups annotated: every non-decoy group, contaminants included, each once even when MetaMorpheus wrote it twice (mzLib #1366).
annotation_database object — never {path, file_type (UniProtXml), reader, protein_count, sha256 (of the DECOMPRESSED bytes), caveats}.
go object — never {source_file_name, sha256, release (the data-version; null when the file has none), term_count (obsolete terms included)}.
skip_unknown_go_ids bool — never Whether skip-unknown-go-ids was given.
unresolved_go_ids string[] — never GO ids the database cites that the release lacks, in ordinal order. Always empty without skip-unknown-go-ids (the call fails instead).
header map<string,string> — never The #!key value header GoAnnotationTsv.Write produced, read back: go_annotation_format, mzlib_version, mzlib_release, go_release, go_obo_sha256, annotation_db_sha256, source_file_sha256, unresolved_go_ids (only when some were dropped), counter_q_value_max, n_multi_member_groups and status_. The counters count GROUPS at q <= counter_q_value_max, not rows.
row_count int rows never Rows in the whole table.
returned_count int rows never Rows in columns.
offset int rows never The offset applied.
truncated bool — never True whenever rows were left out of columns by limit or offset.
caveats string[] — never Ids dropped from the database, a go.obo with no data-version, and the database's own load caveats.
written object — yes: out was not given {path, row_count}; row_count is the whole table.
categories object — yes: category-map was not given {map_name, map_version, source_file_name, sha256, anchor_count, row_count, column_names [go_id, category, subcategory], columns}: GoCategoryTsv's rows read back. subcategory is "category:subcategory", or null where the term reaches only the category's own anchor. A term under no anchor has no row.
categories_written object — yes: categories-out was not given {path}.
column_names string[] — never Exactly GoAnnotationTsv.Schema's headers, in its order (a bridge test holds them equal).
columns table — never Column name to per-row values, for the returned window.

Per-row fields (one value per record, in columns or each list entry):

Field Type Unit Null? Meaning
protein_group string — never The group as MetaMorpheus named it, members |-joined.
accession_used string[] — never Members carrying the term, directly or by propagation, ordinal order. Empty on a term-less row.
accession_direct string[] — never Of those, members annotated to this exact term.
accession_inherited string[] — never Of those, members whose terms were borrowed: a UniProt isoform or mzLib sequence variant takes its entry's terms when it has none of its own.
go_id string — yes: a term-less row: the group has no term (annotation_status says why) The term's primary id (an alternative id in the database resolves to it).
go_name string — yes: a term-less row The term's name in this release.
aspect string — yes: a term-less row biological_process | cellular_component | molecular_function | unknown, spelled by mzLib's own schema column.
evidence string[] — never Evidence codes (ECO) pooled over the carrying members, ordinal order.
evidence_by_member map<string,string[]> — never Member to its own evidence codes for this term; empty on a term-less row. The file spells it member=code,code;member=code.
inherited bool — yes: a term-less row True when every carrying member's terms were borrowed (accession_inherited covers accession_used).
propagated bool — yes: a term-less row True when no member is annotated to this exact term: it is implied by a more specific one, over is_a or part_of.
n_members int proteins never Members in the group.
n_with int proteins never Members carrying the term; 0 on a term-less row. n_with == n_members is the consensus view.
entrapment_members string[] — never The group's entrapment members (ProteinDbLoader.IsEntrapmentAccession, or marked so by the database), on every row of the group.
annotation_status string — never annotated | no_go_terms | no_entry | contaminant (GoAnnotationTsv.StatusName). A row with a term is always annotated.
q_value float fraction (0 to 1) never The group's q-value from the table. Never filtered on.
go_release string — yes: the go.obo has no data-version header The ontology release, e.g. releases/2026-07-26.
go_obo_sha256 string — never sha256 of the go.obo.
annotation_db_sha256 string — never sha256 of the decompressed annotation database.

Errors

Kind pyMzLib raises When
usage UsageError a missing groups table, database, go.obo or category map; a FASTA database; out or categories-out not .tsv, naming an input, naming each other, or in a folder that does not exist; categories-out without category-map; a negative offset or limit. Every one is raised before any file is read.
correctness BridgeError the database cites a GO id the release lacks, without skip-unknown-go-ids (InvalidDataException naming every id); a go.obo mzLib cannot parse, including a truncated one whose edges name absent terms (InvalidDataException with the line); a category map it refuses; a group written twice with different members (InvalidDataException); a table or database it cannot parse
service_unavailable ServiceUnavailableError never raised by this verb

Caveats

  • The table is the UNION over a group's members, never a pick: MetaMorpheus chooses no leading protein. Consensus (n_with == n_members), direct-only (propagated false) and no-borrowing (inherited false) are filters on the rows.
  • Every non-decoy group gets at least one row; a group with no term gets one term-less row whose annotation_status says why. Decoys get none.
  • The header counters count groups at q <= 0.01, not rows; the rows are unfiltered and every group is present.
  • Pin the ontology: terms and ancestors change between releases. This verb reads only an existing go.obo and never downloads one; record go.sha256 with the results.
  • mzlib_release in the header is 'none' and mzlib_version is 1.0.0+, because the bridge builds mzLib from source at the pinned commit; the commit names the release.
  • An isoform or variant member absent from the database (or present without GO of its own) borrows its entry's terms and is listed in accession_inherited; an isoform can differ from its entry in cellular component, which is why the row says so.

Example

go = pymzlib.proteins.annotate_go("PXD036557_AllQuantifiedProteinGroups.tsv", "pxd036557_proteins.xml", go_obo="go-pxd036557.obo", category_map="organelle_map.tsv")

Recorded from the live bridge as proteins_annotate_go_pxd036557.json. The doctests in the API reference replay these recordings in CI.

go = pymzlib.proteins.annotate_go(groups, database, go_obo=obo, out="go_annotations.tsv", limit=0)

Recorded from the live bridge as proteins_annotate_go_out.json. The doctests in the API reference replay these recordings in CI.

Same verb in other bindings

Python (pyMzLib) Rust (mzLibRust) R (mzLibR)
pymzlib.proteins.annotate_go mzlib::proteins::annotate_go_with with GoAnnotateOptions proteins_annotate_go

References

  • doi:10.1093/genetics/iyad031: The Gene Ontology knowledgebase in 2023 (GO Consortium, Genetics 224, iyad031), the ontology and annotations used
  • doi:10.1038/75556: Gene Ontology: tool for the unification of biology (Ashburner et al., Nat Genet 25, 25-29, 2000), the is_a / part_of graph propagated over
  • doi:10.1093/nar/gkae1010: UniProt, whose XML GO dbReferences are the direct annotations (UniProt Consortium 2025, NAR)

Since

Wire protocol pyMzLib mzLibRust mzLibR
1 0.3.0 not yet shipped not yet shipped

Not yet verified

  • Only one annotation database: a search over a target XML plus a separate contaminant database annotates contaminant members as no_entry unless their entries are in the XML. Whether GoGroupAnnotator should take several databases (and stamp several sha256s) is mzLib's call.
  • No bulk (--paths-stdin) form yet. One table per call; a cohort of many tables against one proteome reloads the proteome each time.
  • PYB-3 (a document too large to return is a usage error) is not built in the bridge yet; until it is, use out with limit 0 for a large table.

update_go

Download the current Gene Ontology release (go.obo) to a path, on purpose, keeping any different file already there as a timestamped backup.

Wire verb proteins update-go · Python pymzlib.proteins.update_go

Wraps

Parameters

Parameter Type Default Unit Range Meaning
go_obo (wire --go-obo) path required — — Where to write, e.g. go.obo. Its folder must exist.

Returns

Top-level fields:

Field Type Unit Null? Meaning
go_obo_file string — never Absolute path written.
url string — never Loaders.GeneOntologyUrl, https://purl.obolibrary.org/obo/go.obo: a moving PURL that always serves the current release.
existed_before bool — never Whether a file was already at the path.
previous_sha256 string — yes: no file was there sha256 of the file that was there.
changed bool — never Whether the file on disk now differs from what was there (true for a first download).
go object — never {source_file_name, sha256, release (null when the file has no data-version), term_count}, read back with GeneOntologyGraph.Load, so a truncated download fails here rather than in a later annotate-go.
caveats string[] — never The backup kept when a different file was replaced; a file with no data-version.

Errors

Kind pyMzLib raises When
usage UsageError the folder for go-obo does not exist
service_unavailable ServiceUnavailableError GO's PURL is unreachable, answers 408/429/5xx, or stalls for Loaders.GeneOntologyStallTimeout (2 min); any existing file is left untouched
correctness BridgeError a non-transient HTTP failure (e.g. 404); a downloaded file GeneOntologyGraph.Load refuses

Caveats

  • The whole file (~37 MB) is fetched every time; there is no conditional request. A file that is byte-identical is left in place.
  • When the download differs, the old file is kept beside the new one as ., so earlier runs stay reproducible.
  • This is the only verb that fetches go.obo; proteins annotate-go never downloads.

Example

update = pymzlib.proteins.update_go("go.obo")

Recorded from the live bridge as proteins_update_go.json. The doctests in the API reference replay these recordings in CI.

Same verb in other bindings

Python (pyMzLib) Rust (mzLibRust) R (mzLibR)
pymzlib.proteins.update_go mzlib::proteins::update_go proteins_update_go

References

Since

Wire protocol pyMzLib mzLibRust mzLibR
1 0.3.0 not yet shipped not yet shipped

Not yet verified

  • The backup's exact file name is not returned: mzLib's UpdateGeneOntology computes it internally and returns nothing.