Functional annotations of ORFs -- WoL3 (196,062 genomes)
======

This directory holds functional annotations of predicted protein sequences
(ORFs, in ../proteins/all.faa.xz) for the WoL3 genome set
(../genomes/genome_list.txt), in a WoL2-compatible layout
(see the format-contract note below for the one deliberate deviation from
WoL2's own file shape).

Primary annotation systems:

 - kegg/: KO annotation via eggNOG-mapper's KEGG_ko field (eggNOG 5.0.2).
   Reference hierarchy (pathway/module/reaction/compound/disease/EC links,
   name files) regenerated fresh from the KEGG REST API -- see kegg note
   * https://www.genome.jp/kegg/

 - go/: Gene Ontology annotation, via eggNOG-mapper's GOs field.
   * http://geneontology.org/

 - eggnog/: Orthologous group (OG) and COG category annotation, via
   eggNOG-mapper (eggNOG 5.0.2).
   * http://eggnog5.embl.de/

 - pfam/: Pfam domain annotation, via eggNOG-mapper's PFAMs field.
   * https://pfam.xfam.org/

 - cazy/: CAZy family annotation, via eggNOG-mapper's CAZy field.
   * http://www.cazy.org/

 - uniref/: UniRef annotation, via DIAMOND best-hit search
   (`wipe functional-db build --uniref`).
   * https://www.uniprot.org/help/uniref

 - ec/: Enzyme Commission annotation, via eggNOG-mapper's EC field.
   * https://enzyme.expasy.org/

Provenance common to kegg/, go/, eggnog/, pfam/, cazy/, ec/: eggNOG 5.0.2
database, emapper.py 2.1.12, run via `wipe functional-db build --eggnog`.

Typical filename patterns (same convention as WoL2):

 - orf-to-x.map: Mapping of ORFs to basic entries of the system.
 - x-to-y.map: Mapping of X entries to Y entries within the same system.
 - x_name.txt: Mapping of X entries to descriptive names, strictly 2 columns.

Format contract -- the one deliberate deviation from WoL2:

 - WoL2's *.map files are "wide": one line per source ID, with every target
   as an extra tab-separated field on that line (ragged column count).
 - Every *.map file here is instead strict 2-column "long" TSV: one row per
   (source, target) pair, with repeated source rows for one-to-many. This
   was verified against `woltka` 0.1.7 (envs/woltka): `woltka collapse`
   produces byte-identical output for long vs. wide (it reads maps via
   `read_map_many`, which explicitly documents the repeated-row form as a
   supported "many-to-many" layout), and long is far easier for any other
   tool (awk/pandas/DuckDB) to consume correctly than a ragged format.
 - Exception: kegg/module-to-reaction.map and kegg/pathway-to-module.map are
   WIDE, because `woltka coverage` reads maps via a bare `dict()` (silently
   overwriting repeated keys instead of accumulating) -- verified
   empirically: a 3-member module with 1 member present reports 100%
   coverage from a long map and the correct 33.3% from a wide one. These two
   files exist only to serve `coverage`, so they stay wide; every other file
   in this tree is long.

Large files are xz-compressed with a `.md5` sidecar holding the bare 32-char
md5 of the `.xz` file (matches WoL2's convention).

Additional Notes:
- eggnog/:
  - orf-to-og.map.xz: Values are `<OG>@<taxid>|<taxon name>`; all
   taxonomic nesting levels are present as separate rows for a given ORF,
   not just the narrowest.
  - orf-to-category.map.xz: emapper's `COG_category` field, one single-letter category per row.
- go/:
  - go_name.txt: descriptions of each GO term built from the 2026-01-23 release of go-basic.obo.
  - idmaps/{ec,metacyc,reactome,rhea,kegg}.map: external mappings built by from GO Consortium's own external2go files (current.geneontology.org).
- kegg/:
  - Reference hierarchies and supporting files were built from KEGG release 119.0 at rest.kegg.jp.
  - ko_name.txt backfill: 23 of our observed KOs are absent from current KEGG (retired/renumbered since eggNOG 5.0 was released) but were backfilled from WoL2's KEGG mappings.
  - ko-to-go.map: doesn't exist in KEGG REST, so it was built from eggnog.db's `prots` table (kegg_ko + gos columns, 285,616 reference proteins with both populated).