Method `baltic.tree.addText`

tree.addText() Method

Description

The addText() method in the BALTIC tree class is used to add text annotations to a tree plot. This method allows for flexible positioning and customization of text elements, making it useful for labeling tips, adding node information, or annotating specific parts of the tree.

Syntax

def addText(self, ax, target=None, x_attr=None, y_attr=None, text=None, zorder=None, **kwargs)

Parameters

• ax (matplotlib.axes.Axes): The matplotlib axes to add the text to.
• target (function or None): A function to select which branches to annotate. Default is None, which selects all leaf nodes.
• x_attr (function or None): A function to determine the x-coordinate for the text. Default is None, which uses the branch's x attribute.
• y_attr (function or None): A function to determine the y-coordinate for the text. Default is None, which uses the branch's y attribute.
• text (function or None): A function to determine the text content. Default is None, which uses the leaf name attribute.
• zorder (int or None): The z-order for the text. Default is None, which sets the z-order to 4.
• **kwargs: Additional keyword arguments to pass to the ax.text method.

Return Value

• matplotlib.axes.Axes: The axes with the text annotations added.

Functionality

1. Iterates through branches that satisfy the target condition.
2. For each selected branch:
   • Determines the x and y coordinates using x_attr and y_attr functions.
   • Generates the text content using the text function.
   • Adds the text to the plot using matplotlib's ax.text method.
3. Returns the modified axes object.

Use Cases

1. Labeling tips with species names or sample IDs.
2. Adding support values or other statistics to internal nodes.
3. Annotating specific branches or clades with additional information.
4. Creating custom legends or explanatory text on the tree plot.

Example

import matplotlib.pyplot as plt

# Create a figure and axes
fig, ax = plt.subplots(figsize=(10, 8))

# Plot the tree
tree.plotTree(ax)

# Add tip labels
tree.addText(ax, target=lambda n: n.is_leaf(), x_attr=lambda n: n.x + 0.1, ha='left')

# Add posterior probabilities to internal nodes
tree.addText(ax, 
             target=lambda n: n.is_node() and 'posterior' in n.traits,
             x_attr=lambda n: n.x - 0.1,
             y_attr=lambda n: n.y + 0.1,
             text=lambda n: f"{n.traits['posterior']:.2f}",
             ha='right',
             va='bottom',
             fontsize=8)

# Add a custom annotation to a specific node
special_node = tree.getInternal()[5]  # Example: 6th internal node
tree.addText(ax,
             target=lambda n: n == special_node,
             text=lambda n: "Important\nClade",
             bbox=dict(facecolor='white', edgecolor='red', boxstyle='round,pad=0.5'))

plt.show()

Notes

• The target, x_attr, y_attr, and text parameters accept functions, allowing for great flexibility in determining what to annotate and how.
• If not specified, the default behavior is to add the names of all leaf nodes at their respective positions.
• The zorder parameter can be used to control whether the text appears above or below other elements in the plot.
• Additional text formatting can be controlled through the **kwargs, which are passed directly to matplotlib's text() function.
• For large trees, adding text to every node might clutter the visualization. Consider using target to selectively annotate important features.
• The method assumes that the tree has been previously drawn (e.g., using plotTree()) to ensure that x and y coordinates are available.
• This method does not modify the tree structure; it only adds visual elements to the plot.