Method `baltic.tree.plotCircularTree`

tree.plotCircularTree() Method

Description

The plotCircularTree() method in the BALTIC tree class is used to plot the tree in a circular layout on a given matplotlib axes. This method provides options for customizing the appearance of the circular tree, including control over the circular arrangement, branch colors, and widths.

Syntax

def plotCircularTree(self, ax, target=None, x_attr=None, y_attr=None, width=None, colour=None,
                     circStart=0.0, circFrac=1.0, inwardSpace=0.0, normaliseHeight=None, precision=15, **kwargs)

Parameters

• ax (matplotlib.axes.Axes): The matplotlib axes to plot the tree on.
• target (function or None): A function to select which branches to plot. Default selects all branches.
• x_attr (function or None): A function to determine the x-coordinate for the nodes. Default uses the branch's x attribute.
• y_attr (function or None): A function to determine the y-coordinate for the nodes. Default uses the branch's y attribute.
• width (int, function or None): The width of the lines. Default is 2.
• colour (str, function or None): The color of the lines. Default is 'k' (black).
• circStart (float): The starting angle (in fractions of 2*pi) for the circular layout. Default is 0.0.
• circFrac (float): The fraction of the full circle to use for the layout. Default is 1.0.
• inwardSpace (float): Amount of space to leave in the middle of the tree. Default is 0.0.
• normaliseHeight (function or None): A function to normalize the x-coordinates. Default is None.
• precision (int): The number of points used to plot curved segments. Default is 15.
• **kwargs: Additional keyword arguments to pass to the LineCollection.

Return Value

• matplotlib.axes.Axes: The axes with the circular tree plot added.

Functionality

1. Calculates the circular layout parameters based on circStart and circFrac.
2. Normalizes x-coordinates if a normaliseHeight function is provided.
3. Iterates through branches that satisfy the target condition.
4. For each selected branch:
   • Calculates the start and end positions in the circular layout.
   • Creates line segments for branches and curved segments for internal nodes.
   • Determines the width and color for each segment.
5. Adds all line segments to the plot using a matplotlib LineCollection.
6. Returns the modified axes object.

Use Cases

1. Creating aesthetically pleasing circular representations of phylogenetic trees.
2. Visualizing trees where the root-to-tip distance is important to show radially.
3. Generating compact representations of large trees.
4. Highlighting evolutionary relationships in a radial format.
5. Creating tree visualizations for publications or presentations where a circular layout is preferred.

Example

import matplotlib.pyplot as plt
import numpy as np

# Create a figure and axes
fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(16, 8))

# Plot full circular tree
tree.plotCircularTree(ax1)
ax1.set_title("Full Circular Tree")

# Plot a partial circular tree with custom styling
max_height = max(node.height for node in tree.Objects)
tree.plotCircularTree(ax2, 
                      circStart=0.25,  # Start at 90 degrees
                      circFrac=0.5,    # Use half of the circle
                      inwardSpace=0.2, # Leave space in the center
                      colour=lambda n: plt.cm.viridis(n.height / max_height),
                      width=lambda n: 1 if n.is_leaf() else 2,
                      normaliseHeight=lambda h: (h - tree.root.height) / (max_height - tree.root.height))
ax2.set_title("Partial Circular Tree with Custom Styling")

# Adjust layout and display
for ax in (ax1, ax2):
    ax.set_aspect('equal')
    ax.axis('off')
plt.tight_layout()
plt.show()

Notes

• This method assumes that the tree's x and y coordinates have been set (e.g., by calling drawTree() beforehand).
• The circStart and circFrac parameters allow for creating partial circular layouts or rotating the entire tree.
• Use inwardSpace to adjust the inner radius of the tree, which can be useful for creating space for additional visualizations in the center.
• The normaliseHeight function can be used to adjust the radial position of branches, allowing for non-linear scaling if desired.
• Curved segments for internal nodes are approximated using multiple straight line segments. The precision parameter controls the smoothness of these curves.
• For large trees, consider the performance implications of using high precision values or complex functions for width or colour.
• This method does not automatically set the axes limits or labels. You may need to adjust these manually for optimal visualization.
• Combining this method with addTextCircular() can be useful for adding readable labels to the circular tree.
• The circular layout can sometimes make it challenging to read details in dense parts of the tree. Consider using interactive plots or zooming capabilities for large trees.
• This method does not modify the tree structure; it only creates a visual representation.
• Remember to set the aspect ratio of the axes to 'equal' to ensure the tree appears circular and not elliptical.