CompleteBinarySimulator.py

​

High-level description

The CompleteBinarySimulator class simulates a complete binary tree, where each node has exactly two children except for the leaves. It provides a way to generate a balanced tree topology with specified depth or number of cells, which can be used for in silico simulations of single-cell phylogenies.

​

Code Structure

The CompleteBinarySimulator class inherits from the TreeSimulator abstract class and implements the simulate_tree method. It uses the networkx library to generate a balanced binary tree and then converts it into a CassiopeiaTree object.

​

References

This code references the following symbols:

• TreeSimulator: The abstract base class for tree simulators.
• CassiopeiaTree: The data structure representing a tree in Cassiopeia.
• TreeSimulatorError: An exception class for tree simulator errors.
• nx.balanced_tree: A function from the networkx library to generate a balanced binary tree.

​

Symbols

​

CompleteBinarySimulator

​

Description

This class simulates a complete binary tree with a specified depth or number of cells. It uses the networkx library to generate a balanced binary tree and then converts it into a CassiopeiaTree object. The branch lengths are normalized by the height of the tree, resulting in a tree with a height of 1.

​

Inputs

​

Outputs

This class doesn’t directly return any output. It simulates a tree and stores it internally.

​

Internal Logic

1. Initialization:
   • Checks if exactly one of num_cells or depth is provided.
   • If num_cells is provided, calculates the depth and validates that num_cells is a power of 2.
   • If depth is provided, validates that it is greater than 0.
2. Tree Simulation (simulate_tree method):
   • Generates a balanced binary tree using nx.balanced_tree with a branching factor of 2.
   • Creates a mapping from the default integer node names to unique string names.
   • Adds a root node (“root”) and connects it to the root of the generated binary tree.
   • Relabels the nodes using the generated mapping.
   • Creates a CassiopeiaTree object from the generated tree.
   • Initializes branch lengths by dividing the time of each node by the total depth of the tree plus 1.

​

Side Effects

• Creates and stores a CassiopeiaTree object internally.

​

Dependencies

​

Error Handling

• Raises TreeSimulatorError if:
  • Neither or both num_cells and depth are provided.
  • num_cells is not a power of 2.
  • depth is not greater than 0.