Tree of Trees

A phylogenetic visualization toolkit for creating "tree of trees" representations, where each tip of a main phylogenetic tree is associated with its own subtree. This project combines tree visualization with consensus tree computation using Frequency Difference Consensus Tree (FDCT) methods.

Overview

This repository provides tools for:

• Creating hierarchical "tree of trees" visualizations using Python (toytree/toyplot)
• Computing Frequency Difference Consensus Trees (FDCT) using a Python wrapper for FACT2
• Working with phylogenetic trees in Newick format

Project Structure

tree_of_trees/
├── data/                           # Data files and tree datasets
├── scripts/
│   └── python/
│       ├── tree_of_trees_toytree.py  # Main visualization script
│       └── fdct/                     # FDCT consensus tree module
│           ├── fdct.py               # Python wrapper for FACT2
│           ├── example.py            # Usage examples
│           ├── setup.sh              # Setup script for FACT2
│           └── README.md             # FDCT module documentation
└── README.md

Features

Tree of Trees Visualization

The tree_of_trees_toytree.py script creates sophisticated visualizations where:

• A main phylogenetic tree serves as the backbone structure
• Each leaf node displays an associated subtree
• Uses toytree and toyplot libraries for rendering

FDCT Consensus Tree Computation

The FDCT module provides a Python wrapper for computing Frequency Difference Consensus Trees:

• Processes multiple phylogenetic trees to find consensus
• Supports taxa encoding/decoding for non-integer identifiers
• Returns consensus trees in Newick format

Installation

Prerequisites

• Python 3.x
• Required Python libraries:
  • toytree
  • toyplot
  • numpy

FDCT Setup

To use the FDCT functionality:

cd scripts/python/fdct
bash setup.sh

This script will:

1. Fetch FACT2 source code from https://github.com/Mesh89/FACT2
2. Download the required BOOST library
3. Compile FACT2
4. Generate the FACT++ executable

Note: The setup script has been tested on Linux systems and GitHub Codespaces.

Usage

Tree of Trees Visualization

import toytree
import toyplot

# Define your main tree
main_tree_newick = "(16:0.1115,(...))"

# Define subtrees for each tip
subtrees_newick = {
    "1": "(0:1.0,(1:1.0,4:1.0):1.0,(3:1.0,2:1.0):1.0);",
    "2": "(0:1.0,(1:1.0,3:1.0):1.0,(2:1.0,4:1.0):1.0);",
    # ... more subtrees
}

# Run tree_of_trees_toytree.py to generate visualization

FDCT Consensus Tree

from fdct import fdct

# List of trees in Newick format
trees = [
    "(0:1.0,(1:1.0,4:1.0):1.0,(3:1.0,2:1.0):1.0);",
    "(0:1.0,(1:1.0,3:1.0):1.0,(2:1.0,4:1.0):1.0);",
    # ... more trees
]

# Compute consensus tree
consensus = fdct(trees, exec="path/to/FACT++", encode=False)
print(consensus)

# If taxa are not integers, use encode=True
consensus = fdct(trees, exec="path/to/FACT++", encode=True)

FDCT Function Parameters

• input: List of trees as Newick strings
• exec: Path to the FACT++ executable
• encode: Set to True if taxa identifiers are not integers (default: False)

FDCT Return Value

Returns the consensus tree as a Newick string. Note that the consensus tree does not include branch lengths.

Examples

See scripts/python/fdct/example.py for a complete working example of FDCT usage with sample phylogenetic trees.

References

• FACT2 (Frequency-based Aggregate Consensus Tree): https://github.com/Mesh89/FACT2
• Toytree documentation: https://toytree.readthedocs.io/

License

MIT License

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Contact

For questions or issues, please open an issue on GitHub or contact the tahiri-lab team.