Method `baltic.tree.collapseSubtree`

tree.collapseSubtree() Method

Description

The collapseSubtree() method in the BALTIC tree class is used to collapse an entire subtree into a single clade object. This method is useful for simplifying complex tree structures, focusing on specific parts of the tree, or reducing the level of detail in certain analyses.

Syntax

def collapseSubtree(self, cl, givenName, verbose=False, widthFunction=lambda k: len(k.leaves))

Parameters

• cl (node): The node representing the root of the subtree to collapse.
• givenName (str): The name to assign to the new clade.
• verbose (bool): If True, prints verbose output during the process. Default is False.
• widthFunction (function): A function to determine the width of the clade when computing branch y coordinates in drawTree(). Default calculates width based on the number of leaves.

Return Value

• clade: The newly created clade object representing the collapsed subtree.

Functionality

1. Creates a new clade object with the given name.
2. Transfers relevant attributes from the subtree root to the new clade (index, leaves, length, height, parent, absoluteTime, traits).
3. Calculates the width of the new clade using the provided widthFunction.
4. Removes all nodes in the subtree from the tree's Objects list.
5. Replaces the subtree with the new clade in the parent's children list.
6. Updates the tree structure (traverses the tree and sorts branches).

Use Cases

1. Simplifying complex trees by collapsing less relevant subtrees.
2. Focusing analysis or visualization on specific parts of the tree.
3. Creating summary representations of large phylogenies.
4. Preparing trees for comparative analyses where some clades are treated as single units.

Example

# Assuming we have a tree and want to collapse a subtree
subtree_root = tree.getInternal()[5]  # Some internal node

# Collapse the subtree
collapsed_clade = tree.collapseSubtree(subtree_root, "Collapsed_Clade_1", verbose=True)

print(f"Collapsed clade name: {collapsed_clade.name}")
print(f"Number of leaves in collapsed clade: {len(collapsed_clade.leaves)}")

# Using a custom width function
def custom_width(node):
    return len(node.leaves) * 2  # Make the clade twice as wide

tree.collapseSubtree(another_subtree_root, "Collapsed_Clade_2", widthFunction=custom_width)

Notes

• This method modifies the tree in-place. If you need to preserve the original tree, make a deep copy before collapsing subtrees.
• The collapsed clade retains information about its constituent leaves, which can be accessed through the leaves attribute.
• The widthFunction parameter allows customization of how the collapsed clade is represented visually when the tree is drawn.
• Collapsing subtrees can significantly reduce the complexity of the tree, which may be beneficial for both computational efficiency and visual clarity.
• The method includes checks to ensure you're not attempting to collapse the entire tree.
• After collapsing, you may need to update any analyses or visualizations that relied on the detailed structure of the collapsed subtree.
• The verbose option can be useful for debugging or understanding the collapsing process, especially for large or complex subtrees.