# Web of Life 3 (WoL3)

**Version 3.0.0-rc.4** (release `wol3_rc4`, 2026-09-14) -- see `version.txt`.

A reference database of **196,062 bacterial and archaeal genomes** with a unified taxonomy and a genome-scale phylogeny inferred from a common set of marker genes.

Web of Life (WoL) is a reference phylogeny and genome database built for metagenomics: reads are mapped against the genome collection (e.g. with
[Woltka](https://github.com/qiyunzhu/woltka)), and the resulting profiles can be
summarized along the taxonomy or along the tree, enabling phylogeny-aware
diversity metrics (UniFrac, Faith's PD) on metagenomics data. WoL3 is the third
iteration, expanding WoL2 (~16k genomes) by roughly an order of magnitude.

## Contents at a glance

| Genomes | Archaea | Bacteria | Phyla | Classes | Orders | Families | Genera | Species |
|--------:|--------:|---------:|------:|--------:|-------:|---------:|-------:|--------:|
| 196,062 | 3,918 | 192,144 | 120 | 399 | 1,324 | 3,535 | 14,698 | 56,502 |

- Source: 2,552,669 and 3,97,481 archaeal and bacterial genomes from NCBI (RefSeq and Genbank), plus 192 genomes carried over directly from WoL2.
- If a genome has a copy in both RefSeq and Genbank, the version in RefSeq is prioritized.
- 10,753 of the 15,953 WoL2 genomes (67.4%) are retained in this release.

## Directory layout

```
wol3/
|-- version.txt          # release version, date, and genome count (key: value)
|-- genomes/
|   |-- all.fna.xz       # host-masked nucleotide FASTA, all genomes concatenated, xz-compressed
|   `-- genome_list.txt  # the 196,062 genome IDs included, one per line
|-- proteins/
|   |-- all.faa.xz       # predicted protein sequences (ORFs), all genomes concatenated, xz-compressed
|   `-- coords.txt.xz    # ORF genomic coordinates, xz-compressed
|-- metadata/
|   |-- metadata.txt        # 196,062 rows x 49 columns, tab-delimited, has header, including QC stats
|   `-- genome_length.txt   # genome_id <TAB> total length (bp), no header
|-- taxonomy/
|   `-- taxonomy.txt        # genome_id <TAB> phylogeny-guided 7-rank lineage, no header
|-- phylogeny/
|   |-- tree.nwk                        # branch lengths only
|   |-- tree_branch_support.nwk         # internal nodes labeled with support values
|   |-- tree_decorated_branchonly.nwk   # internal nodes labeled with taxon names
|   `-- subtree_gene_trees/             # per-subtree gene trees from the uDance run
|-- function/            # functional annotations of the ORFs in proteins/all.faa.xz; see function/README.md
|   |-- cazy
|   |-- ec
|   |-- eggnog
|   |-- go
|   |-- kegg
|   |-- pfam
|   |-- uniref
|   `-- README.md
`-- databases/           # prebuilt alignment / search indexes; see 'Prebuilt databases'
    |-- bowtie2/wol3_rc4/               # 1,000 bucketed Bowtie2 indexes (bucket_000 ... bucket_999)
    |-- minimap2/wol3_rc4/              # Minimap2 .mmi indexes with HiFi preset (single/, sharded/ (distributed databases))
    |-- gsearch/wol3_rc4/               # GSearch HNSW index (parameters are available in `parameters.json`)
    |-- ryxdi/wol3_rc4-w20.ryxdi/       # RYpe index with k=64, w=20
    |-- krepp/wol3_rc4/                # krepp v0.10.0 index for phylogenetic placement (k=29, w=43, h=13)
    `-- sylph/                         # sylph v1.0.0 profiling databases, 95-ANI and 99-ANI
        |-- wol3_rc4/                  # 99% ANI database
        `-- wol3_rc4_95ani/            # 95% ANI database (recommended resolution)
```

## Genome identifiers

Every record is keyed by a 10-character WoL genome ID: `G` followed by 9 digits
(e.g. `G000005825`), derived from the NCBI assembly accession
(`GCF_000005825.2` -> `G000005825`). These IDs are the tip labels in the trees
and the first column of every table, so all files join on a single key. In the future we might include genomes not from NCBI but important for analyses. The genome IDs of those will start with H.

## Genome sequences

`genomes/all.fna.xz` contains the host-masked nucleotide FASTA sequences for
all 196,062 genomes, concatenated and xz-compressed. `genomes/genome_list.txt`
lists the genome IDs included, one per line, matching the FASTA headers.

## Protein sequences

`proteins/all.faa.xz` contains the predicted protein sequences (ORFs) for all
genomes, concatenated and xz-compressed. `proteins/coords.txt.xz` gives the
genomic coordinates of each ORF.

## Functional annotations

`function/` holds functional annotations of the ORFs in `proteins/all.faa.xz`,
one subdirectory per annotation system: `kegg/`, `go/`, `eggnog/`, `pfam/`,
`cazy/`, `uniref/`, `ec/`. See `function/README.md` for provenance, file formats,
and per-system details.

## Prebuilt databases

`databases/` holds search and alignment indexes built over the same 196,062
genomes, so reads can be mapped without rebuilding anything locally. All
indexes are built from the release `wol3_rc4`; each tool directory contains a
single `wol3_rc4` subdirectory. 

| Directory | Tool | Layout |
|-----------|------|--------|
| `databases/bowtie2/wol3_rc4/` | Bowtie2 | 1,000 buckets `bucket_000 ... bucket_999`, each a complete 6-file index named `index.*.bt2` |
| `databases/minimap2/wol3_rc4/single/` | Minimap2 | one whole-set index, `wol3_rc4-hifi-all.mmi` (HiFi preset) |
| `databases/minimap2/wol3_rc4/sharded/` | Minimap2 | 1,000 per-bucket indexes `bucket_NNN.mmi` (HiFi preset) |
| `databases/gsearch/wol3_rc4/` | GSearch | `index/` (HNSW graph + `seqdict.json` + `parameters.json`) |
| `databases/ryxdi/wol3_rc4-w20.ryxdi/` | RYpe index | `k=64, w=20` where k is k-mer and w is window size |
| `databases/krepp/wol3_rc4/` | krepp | 64-way sharded index, `w43_64of64.tar` (see 'krepp phylogenetic placement index' below) |
| `databases/sylph/wol3_rc4/` | sylph | `wol3_rc4_ani99.syldb` + `.syl2db` + `wol3_rc4_ani99_taxonomy.tsv` (99% ANI) |
| `databases/sylph/wol3_rc4_95ani/` | sylph | `wol3_rc4_ani95.syldb` + `.syl2db` + `wol3_rc4_ani95_taxonomy.tsv` (95% ANI, recommended) |

Supporting files and notes:

- `databases/manifests/wol3_rc4/assignments.tsv` -- 196,062 rows, header
  `genome_id <TAB> bucket <TAB> lineage`; the authoritative genome -> bucket map
  for every bucketed index above. 

- Bucketing is shared: bucket *N* contains the same genomes in the Bowtie2 index,
both Minimap2 shard sets, and the manifests, so per-bucket results can be merged
across tools.

- GSearch index parameters: HNSW `max_nb_conn = 128`, `ef = 1600`, capacity
1,500,000; sketching `kmer_size = 16`, `sketch_size = 15000`, `algo = OPTDENS`,
DNA.

### krepp phylogenetic placement index

We built a krepp (v0.10.0) index of all 196,062 references using 29-mer
minimizers of all 43-mers (`-k 29 -w 43 -h 13`). We make this index available
to enable phylogenetic placement for sequences of any length (e.g. short
reads, contigs).

Usage, with `/path/to/index` set to the extracted `w43_64of64/` directory
(`tar -xzvf w43_64of64.tar.gz`):

- Estimating distances from each query sequence to all sufficiently similar
  WoL3 genomes:
  ```
  krepp dist -i /path/to/index -q /path/to/query.fastx -o /path/to/output.tsv
  ```
- Placing each query sequence on the backbone WoL3 phylogeny:
  ```
  krepp place -i /path/to/index -q /path/to/query.fastx -o /path/to/output.jplace
  ```

### sylph profiling databases

The same samples were profiled against WoL3 using sylph v1.0.0. Two databases
are available, at 95% and 99% ANI; 95% is the resolution sylph's authors
recommend for profiling, and is the one we recommend here.

Each database is paired with a mapping file, `<db>_taxonomy.tsv`, two
columns with no header: the genome filename used as the sylph record ID, and
its full 7-rank GTDB-style lineage (`; `-separated), e.g.
```
G018819065.fna.gz	d__Archaea;p__Nanobdellota;c__Nanobdellia;o__Woesearchaeales;f__GCA-2686295;g__GCA-2686295;s__GCA-2686295 sp018819065
```
Use this to translate sylph's per-genome output into taxonomy. The 99-ANI
mapping covers all 196,062 genomes; the 95-ANI mapping covers the 95,255
cluster representatives that back the 95-ANI database.

## File details

### `metadata/metadata.txt`

Tab-delimited with a header row. Columns:

- **Identity**: `genome_id`, `assembly_accession`, `bioproject`, `biosample`,
  `wgs_master`, `taxid`, `species_taxid`, `organism_name`,
  `infraspecific_name`, `isolate`
- **Assembly**: `refseq_category`, `version_status`, `assembly_level`,
  `release_type`, `genome_rep`, `seq_rel_date`, `asm_name`, `asm_submitter`,
  `gbrs_paired_asm`, `paired_asm_comp`, `ftp_path`, `excluded_from_refseq`,
  `relation_to_type_material`, `asm_not_live_date`, `assembly_type`, `group`,
  `source` (`refseq` | `genbank`)
- **Composition**: `genome_size_ungapped`, `gc_percent`, `replicon_count`,
  `scaffold_count`, `contig_count`
- **Annotation**: `annotation_provider`, `annotation_name`, `annotation_date`,
  `total_gene_count`, `protein_coding_gene_count`, `non_coding_gene_count`,
  `pubmed_id`
- **Quality**: `checkm2-completeness`, `checkm2-contamination`,
  `checkm2-quality-score`, `ani_taxonomy_check_status`,
  `fcs_fraction_contaminated`
- **Marker / rRNA counts**: `marker_gene_cts`, `5S_counts`, `16S_counts`,
  `23S_counts`
- **Provenance**: `in_wol2` (1 if the genome was also in WoL2, else 0)

Missing values are `na` or empty. Note the 192 genomes ported directly from WoL2
have no CheckM2, rRNA, or NCBI annotation-count values -- those fields are blank
for them (a known gap).

### `taxonomy/taxonomy.txt`

Two columns, no header: genome ID and a GTDB-style lineage with all seven ranks
present, `; `-separated:

```
G018819065	d__Archaea; p__Nanobdellota; c__Nanobdellia; o__Woesearchaeales; f__GCA-2686295; g__GCA-2686295; s__GCA-2686295 sp018819065
```

### `phylogeny/*.nwk`

Three Newick files over the identical set of 196,062 tips, differing only in
what is written at the internal nodes:

| File | Internal node labels |
|------|----------------------|
| `tree.nwk` | none -- branch lengths only; use this for UniFrac / PD |
| `tree_branch_support.nwk` | support values (0-1) |
| `tree_decorated_branchonly.nwk` | taxon names |

### `phylogeny/subtree_gene_trees/`

Per-subtree gene trees from the uDance run that produced the backbone tree
above. (Coming soon -- not yet populated in this release.)