TaxTree2

Related Tools

For working with taxonomic data, see also TaxTree and BBSketch.

Basic Usage

taxtree2.sh in=<input> out=<output>

TaxTree2 automatically detects the input format and converts to the opposite format based on the output filename extension. Files ending in .tsv or .tsv.gz are written as portable text format; all other extensions produce legacy serialized format. By default, the tool uses the bundled taxonomic database if no input is specified.

Workflow

1. Load: Read input TaxTree from file (supports both formats)
2. Convert: Write output in the requested format
3. Verify: Reload the output file to confirm successful conversion
4. Validate: Compare original and reconstructed trees field-by-field

Text Format Specification (A48 Encoding)

The portable text format uses A48 numerical encoding for compact representation and includes comprehensive validation headers.

Header Lines

All header lines begin with ## and must appear before data lines:

##TaxTree2 <version>

Format version number (currently 1)

##Encoding <encoding>

Numeric encoding type (currently A48)

##Tree <nodesLength> <nodeCount>

Array size and actual node count for validation

##Config <minValidTaxa> <simplify> <reassign> <skipNorank> <inferRankLimit>

Tree configuration flags and limits

##MergedMap <present> <count>

Presence flag and size of merged TaxID mapping

##LevelExtended <columns...>

Column headers for node data

Data Format

Node Lines: Tab-delimited with 8 columns per node:

• Extended level (taxonomy rank)
• TaxID (taxonomy identifier)
• Parent TaxID
• Number of children
• Minimum parent extended level
• Maximum child extended level
• Flag (bit-packed metadata)
• Taxonomic name

Merged TaxID Lines: After the #MergedMap section marker, two-column tab-delimited entries mapping old TaxIDs to new TaxIDs.

Validation

Validation performs the following checks on reconstruction:

• Exact match of node array length and actual node count
• All configuration flags (simplify, reassign, skipNorank) preserved
• Inference rank limit matches original
• Merged TaxID map identical (if present)
• Every node field matches: ID, name, parent, child count, levels, and flags
• Tree level distributions identical
• All runtime counts remain zero (not stored in text format)

Parameters

Usage Examples

Example 1: Convert Legacy to Portable Text Format

Convert a serialized legacy TaxTree to the portable TSV format:

taxtree2.sh in=taxonomy.taxtree out=taxonomy.taxtree.tsv.gz

The output will be gzip-compressed TSV text that can be inspected, version-controlled, or transferred between systems. The tool validates that all nodes and configurations were preserved exactly.

Example 2: Convert Text Format Back to Legacy

Restore a TSV file to legacy serialized format for maximum compatibility:

taxtree2.sh in=taxonomy.taxtree.tsv.gz out=taxonomy.taxtree

The .taxtree extension (not .tsv) causes output in serialized format. Full validation ensures the reconstructed tree is identical to the original.

Example 3: Using Bundled Default Tree

Convert the built-in default taxonomy without specifying an input:

taxtree2.sh out=default_tree.taxtree.tsv.gz

If no input is provided, TaxTree2 automatically uses the bundled taxonomy database included with BBTools, then converts it to the specified output format.

Example 4: Custom Memory Settings

For very large taxonomies or memory-constrained systems:

taxtree2.sh in=huge_tree.taxtree out=huge_tree.tsv.gz -Xmx64g

The -Xmx parameter overrides automatic memory detection. Allocate more memory for faster processing; large TaxTrees may require 16+ GB depending on node count.

Performance Characteristics

Threading

TaxTree2 uses multithreaded parsing for efficient processing, with up to 8 parser threads and additional merge threads for combining results. Thread count is automatically determined from available CPU cores but can be influenced by Java startup parameters.

Memory Usage

Memory requirements scale with the number of nodes in the TaxTree. A typical complete taxonomy with ~2.5 million nodes requires 4-8 GB of heap memory. Automatic memory detection allocates approximately 84% of available system RAM.

Benchmarks

On a 128-core system (2026-08-21), loading and processing a raw 138 MB tree with validation:

• 1 thread: ~0.56 seconds
• 2 threads: ~0.31 seconds
• 4 threads: ~0.20 seconds
• 8 threads: ~0.18 seconds

Technical Details

Validation Output

During execution, TaxTree2 reports timing information for each phase:

• Input load: Time to read and reconstruct the input TaxTree
• Output write: Time to serialize to the output format
• Output load: Time to reload and reconstruct the output file
• Validation: Time to perform complete field-by-field validation
• Total time: Sum of all phases

A48 Encoding

The A48 format uses a space-efficient encoding for small non-negative integers commonly encountered in taxonomic data (node IDs, counts, levels). This reduces file size while maintaining portability across platforms.

Merged TaxIDs

Modern TaxTrees include a mapping of deprecated/merged TaxID numbers to their current replacements. TaxTree2 preserves this mapping exactly during format conversion and validates it during reconstruction.

Limitations

The text format stores the static tree structure only. Runtime properties that are populated during TaxTree usage (such as abundance counts or name lookups) are not persisted. A non-empty runtime map will cause an error during writing, preventing accidental loss of data.

Support

For questions and support:

• Email: bbushnell@lbl.gov
• Documentation: bbmap.org
• GitHub: BBTools Repository