Class `baltic.clade`

clade Class

Description

The clade class in BALTIC represents a collapsed clade in a phylogenetic tree. It is used to simplify tree structures by collapsing a group of closely related taxa into a single entity, which can be useful for visualization or analysis of large trees.

Class Definition

class clade:
    def __init__(self, givenName):
        # ... (attribute initialization)

    def is_leaflike(self):
        return True

    def is_leaf(self):
        return False

    def is_node(self):
        return False

Attributes

• branchType (str): The type of branch, default is 'leaf'.
• subtree (list): The subtree containing all the branches that were collapsed, assigned in collapseSubtree().
• leaves (set): Names of descendant tips in the collapsed clade, assigned in collapseSubtree().
• length (float): The length of the branch, assigned in collapseSubtree().
• height (float or None): The height of the branch, assigned in collapseSubtree().
• absoluteTime (float or None): The absolute time of the event, assigned in collapseSubtree().
• parent (node): The parent node, assigned in collapseSubtree().
• traits (dict): Dictionary of traits associated with the clade, assigned in collapseSubtree().
• index (int or None): The index of the node, assigned in collapseSubtree().
• name (str): The name assigned to the clade when it was collapsed.
• x (float or None): The x-coordinate for plotting, default is None.
• y (float or None): The y-coordinate for plotting, default is None.
• lastHeight (float): The height of the highest tip in the collapsed clade, assigned in collapseSubtree().
• lastAbsoluteTime (float or None): The absolute time of the highest tip in the collapsed clade, assigned in collapseSubtree().
• width (float): The width of the node for plotting, default is 1.

Methods

is_leaflike()

Returns True, indicating that collapsed clades are treated as leaf-like objects in the tree structure.

is_leaf()

Returns False, as a collapsed clade is not a true leaf (tip) in the phylogenetic tree.

is_node()

Returns False, as a collapsed clade is not an internal node in the traditional sense.

Usage

Clade objects are typically created by BALTIC's tree manipulation functions, particularly collapseSubtree(), rather than being instantiated directly by users. They are used to simplify complex tree structures by representing a group of related taxa as a single entity.

Example

import baltic as bt
import matplotlib.pyplot as plt

# Create a simple tree
tree_string = "((A:0.1,B:0.2):0.3,(C:0.4,(D:0.5,E:0.6):0.7):0.8);"
tree = bt.make_tree(tree_string)

# Visualize the original tree
fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(15, 7))
tree.plotTree(ax1)
ax1.set_title("Original Tree")

# Collapse a subtree into a clade
node_to_collapse = tree.getInternal()[2]  # Choose a node to collapse
collapsed_clade = tree.collapseSubtree(node_to_collapse, "Collapsed_DE")

# Print information about the collapsed clade
print(f"Collapsed clade name: {collapsed_clade.name}")
print(f"Number of leaves in collapsed clade: {len(collapsed_clade.leaves)}")
print(f"Height of collapsed clade: {collapsed_clade.height}")

# Visualize the tree with the collapsed clade
tree.plotTree(ax2)
ax2.set_title("Tree with Collapsed Clade")

plt.tight_layout()
plt.show()

# To uncollapse the tree
tree.uncollapseSubtree()

Notes

• Collapsed clades are useful for simplifying the visualization and analysis of large, complex phylogenetic trees.
• The subtree attribute contains all the original branches that were collapsed, allowing for later uncollapsing if needed.
• The leaves attribute provides quick access to all the tip names contained within the collapsed clade.
• lastHeight and lastAbsoluteTime represent the most recent (highest) tip in the collapsed clade, which can be useful for time-calibrated trees.
• When plotting, collapsed clades are represented as single entities, typically with a width greater than that of individual tips to visually indicate that they represent multiple taxa.
• The traits dictionary can be used to store aggregate information about the collapsed clade, such as average trait values of its constituent taxa.
• While collapsed clades behave like leaves in many tree operations, they retain information about their internal structure, allowing for more detailed analysis when needed.

Advanced Usage

Collapsed clades can be particularly useful in scenarios where you want to focus on specific parts of a large tree or when dealing with trees that have many closely related taxa. Here are some advanced usage examples:

1. Collapsing multiple clades based on a criterion:

# Collapse all clades with more than 10 descendants
for node in tree.getInternal():
    if len(node.leaves) > 10:
        tree.collapseSubtree(node, f"Clade_{node.index}")

# Plot the simplified tree
fig, ax = plt.subplots(figsize=(12, 8))
tree.plotTree(ax)
plt.show()

2. Analyzing traits of collapsed clades:

# Assuming tips have a 'value' trait
for obj in tree.Objects:
    if isinstance(obj, bt.clade):
        values = [tree.tipMap[leaf].traits['value'] for leaf in obj.leaves]
        obj.traits['mean_value'] = sum(values) / len(values)

# Color clades based on their mean value
fig, ax = plt.subplots(figsize=(12, 8))
tree.plotTree(ax, colour=lambda n: plt.cm.viridis(n.traits.get('mean_value', 0) / 100))
plt.show()

3. Temporarily collapsing clades for specific analyses:

# Perform an analysis on a simplified tree
original_objects = tree.Objects.copy()
tree.collapseSubtree(some_node, "temp_clade")
# ... perform analysis ...
tree.uncollapseSubtree()
tree.Objects = original_objects

These examples demonstrate how the clade class can be used to simplify, analyze, and manipulate complex phylogenetic trees in BALTIC.