FAQ

Taxonomy FAQ

Why is there a discrepancy in the naming system between GTDB-Tk and NCBI or Silva taxonomic names?

GTDB-Tk uses the GTDB taxonomy (https://gtdb.ecogenomic.org/). This taxonomy is similar, but not identical to NCBI and Silva. In many cases the GTDB taxonomy more strictly follows the nomenclatural rules for rank suffixes which is why there is Nitrospirota instead of Nitrospirae.

Why do I see discrepancies in classification for closely related genomes?

Discrepancies in taxonomic assignments can occur when working with closely related genomes. GTDB-Tk uses both the Relative Evolutionary Divergence (RED) value and the placement of the genome in the reference tree to determine the best taxonomic classification. In most cases taxonomic assignments are robust, but it is possible for highly similar genomes to have sufficiently different protein sequences that their placements in the reference tree will vary slightly. This can lead to:

1. placement on different but closely related branches, or

2. placement on the same branch but at different depths.

This uncertainty in the placement of even closely related genomes can result in genomes being erroneously assigned to different taxa (e.g. closely related sister families).

What should I do?

If you run into this situation, here are a few strategies you can use:

1. Dereplicate your genomes.

   If you have a cluster of closely related genomes representing a single species, consider dereplicating them to pick a single representative based on genome quality metrics (for example, using a tool like dRep or Galah). The taxonomic assignment for this species representative genomes can then be propagated to the other genomes in the cluster.

2. Build a de novo tree

   Another option is to construct a de novo tree including your closely related genomes plus a suitable outgroup. For instance, if you have three genomes classified as:

   • c__Atribacteria;o__Atribacterales;f__Atribacteraceae

   • c__Atribacteria;o__Atribacterales;f__Thermatribacteraceae

   • c__Atribacteria;o__Atribacterales;f__

you could generate a tree for the class Atribacteria (with one outgroup class) and examine whether your genomes cluster together despite their different family-level assignments.

Can you combine the bacterial and archaeal trees into a single tree?

The bacterial and archaeal trees are inferred from different marker genes. Currently, the correct rootings of these trees remain an open area of research. GTDB-Tk does not provide a tool to merge the trees but It is possible to artificially combine them by manipulating the Newick files. One solution would be to use (DendroPy); a Python library used for phylogenetic computing.

GTDB-Tk FAQ

GTDB-Tk reaches the memory limit / pplacer crashes

The host may report that GTDB-Tk has exceeded the memory requirements due to how pplacer is implemented. Briefly, this is only the reported value and is not true for how much memory is actually in use.

When pplacer runs, it goes through several steps notable detailed below:

1. pplacer requests an uninitialised chunk of memory from the host (say, 150 GB).

   • VIRT = 150 GB [virtual memory memory, i.e. the amount of memory mapped]

   • RES ~= 0 GB [amount of memory physically in use]

2. pplacer starts caching information to that chunk of memory

   • VIRT = 150 GB

   • RES -> 150 GB (slowly increases to 150 GB as caching information is written)

   Note

   If pplacer crashes here, you likely don’t have enough free memory on the server.

3. pplacer starts placing genomes into the tree

   1. the main pplacer thread forks for each --pplacer_cpus or --cpus (if not specified).

      • Unix uses the copy-on-write method for each child.

      Note

      This means that a new thread will appear using the same amount of memory as the parent (150 GB). Due to how copy-on-write is implemented, this is the same memory space and is not using any additional physical memory.

      Therefore, the host will report pplacer using a total of PARENT_MEMORY * (N_CHILDREN + 1) GB.

   2. each worker will only read from the memory space and exit once the queue of query genomes is depleted.

For example, running GTDB-Tk on the bacterial tree (requires ~140 GB of memory) with 1 CPU will require ~140 GB of physical memory, but the host will report ~280 GB of memory in use.

Using the --scratch_dir parameter and --pplacer_cpus 1 may help.

How is GTDB-Tk validating species assignments using average nucleotide identity?

GTDB-Tk uses skani ( it was using fastANI until v2.3.2) to estimate the ANI between genomes. A query genome is only classified as belonging to the same species as a reference genome if the ANI between the genomes is within the species ANI circumscription radius (typically, 95%) and the alignment fraction (AF) is >= --min_af (default: 0.5). Since GTDB-Tk v2.7.0, query genomes are compared to all GTDB species representative genomes, not only to the representatives of the genus in which they are placed. In some circumstances, the phylogenetic placement of a query genome may not support the species assignment. GTDB r207+ strictly uses ANI to circumscribe species and GTDB-Tk follows this methodology. The species-specific ANI circumscription radii are available from the GTDB website.

What is --place_species?

By default, genomes assigned to a species by the ANI screen are not placed in the reference tree (classification method ani_screen). With --place_species, they are also placed: the species assignment still comes from ANI, but the placement columns of the summary file are filled in and the note column reports whether placement and ANI agree. This increases run time and pplacer memory use. --place_species does not disable the ANI screen.

Deprecated FAQ

What were the options --mash_db and --skip_ani_screen?

In GTDB-Tk v2.2 to v2.4, classify_wf and classify required one of two mutually exclusive options: --mash_db or --skip_ani_screen.

--mash_db gave the path of the Mash sketch of the reference genomes used by the ANI screen; if it did not exist, it was created so it could be reused in later runs.

--skip_ani_screen skipped the ANI screen: genomes were only compared by ANI to the reference genomes of the genus in which pplacer placed them.

FastANI was replaced by skani in v2.4.0, and Mash was removed in v2.5.0 (--mash_db is no longer used).

Since v2.7.0, the reference data includes a pre-sketched skani database of the GTDB species representatives, so the ANI screen always runs against all representatives and --skip_ani_screen (and --skani_sketch_dir, added in v2.6.0) have been removed. To also place ANI-assigned genomes in the reference tree, use --place_species (see above).

Why is FastANI using more threads than allocated?

If you are using FastANI version 1.33 then you may run into an issue where FastANI will use more threads than you allocate. This can be problematic if running GTDB-Tk on a HPC where you have a limited number of threads available.

This issue has been reported to the FastANI developers (#101).

Depending on how you installed GTDB-Tk there are different ways to downgrade FastANI to version 1.32.

Manual:

Simplify download and install the FastANI binary from here.

Conda:

From GTDB-Tk v2.0.0 the conda environment will automatically have FastANI v1.3 installed. Otherwise run:

conda install -c bioconda fastani==1.32

Docker:

From GTDB-Tk v2.2.2 the Docker container will automatically have FastANI v1.32 installed. Otherwise, manually build the container from the Dockerfile, making sure to specify FastANI v1.32.