Method `baltic.tree.addTextUnrooted`

tree.addTextUnrooted() Method

Description

The addTextUnrooted() method in the BALTIC tree class is used to add text annotations to an unrooted tree plot. This method is specifically designed to handle the circular layout of unrooted trees, adjusting text orientation and position accordingly.

Syntax

def addTextUnrooted(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 branch's 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.
   • Calculates the appropriate rotation angle based on the branch's position in the circular layout.
   • Adjusts text alignment for readability based on its position.
   • Generates the text content using the text function.
   • Adds the rotated and aligned text to the plot using matplotlib's ax.text method.
3. Returns the modified axes object.

Use Cases

1. Labeling tips in an unrooted tree visualization with species names or sample IDs.
2. Adding annotations to specific branches or clades in a radial tree layout.
3. Creating circular phylogenetic visualizations with readable labels.
4. Enhancing unrooted tree plots with additional information like support values or traits.

Example

import matplotlib.pyplot as plt

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

# Draw the unrooted tree
tree.drawUnrooted()
tree.plotTree(ax)

# Add tip labels
tree.addTextUnrooted(ax, 
                     target=lambda n: n.is_leaf(), 
                     x_attr=lambda n: n.x * 1.1,  # Slightly outside the tips
                     y_attr=lambda n: n.y * 1.1,
                     fontsize=8)

# Add support values to internal nodes
tree.addTextUnrooted(ax,
                     target=lambda n: n.is_node() and 'posterior' in n.traits,
                     x_attr=lambda n: n.x * 0.9,  # Slightly inside the nodes
                     y_attr=lambda n: n.y * 0.9,
                     text=lambda n: f"{n.traits['posterior']:.2f}",
                     fontsize=6,
                     color='red')

plt.axis('equal')  # Ensure the plot is circular
plt.axis('off')    # Hide axes
plt.tight_layout()
plt.show()

Notes

• This method is specifically designed for use with unrooted (circular) tree layouts. Make sure to use drawUnrooted() before calling this method.
• The method automatically handles text rotation and alignment to ensure readability in the circular layout.
• The target, x_attr, y_attr, and text parameters accept functions, allowing for great flexibility in determining what to annotate and how.
• For best results, adjust the x and y attributes to position text slightly inside or outside the tree circle as needed.
• 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 dense trees, consider using the target parameter to selectively annotate to avoid overcrowding.
• This method assumes that the tree has been drawn in an unrooted layout and that each node has a tau attribute representing its angular position.
• The method does not modify the tree structure; it only adds visual elements to the plot.