Method `baltic.tree.plotCircularPoints`

tree.plotCircularPoints() Method

Description

The plotCircularPoints() method in the BALTIC tree class is used to add point markers to a circular tree plot. This method allows for flexible positioning and customization of points in a circular layout, making it useful for highlighting specific nodes, representing additional data, or creating visual cues on a circular tree plot.

Syntax

def plotCircularPoints(self, ax, x_attr=None, y_attr=None, target=None, size=None, colour=None,
                       circStart=0.0, circFrac=1.0, inwardSpace=0.0, normaliseHeight=None,
                       zorder=None, outline=None, outline_size=None, outline_colour=None, **kwargs)

Parameters

• ax (matplotlib.axes.Axes): The matplotlib axes to add the points to.
• x_attr (function or None): A function to determine the x-coordinate for the points. Default uses the branch's x attribute.
• y_attr (function or None): A function to determine the y-coordinate for the points. Default uses the branch's y attribute.
• target (function or None): A function to select which branches to annotate. Default selects all leaf nodes.
• size (int, function or None): The size of the points. Default is 40.
• colour (str, function or None): The color of the points. 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.
• zorder (int or None): The z-order for the points. Default is 3.
• outline (bool or None): If True, adds an outline to the points. Default is True.
• outline_size (int, function or None): The size of the outline. Default is twice the size of the points.
• outline_colour (str, function or None): The color of the outline. Default is 'k' (black).
• **kwargs: Additional keyword arguments to pass to the ax.scatter method.

Return Value

• matplotlib.axes.Axes: The axes with the points 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 position in the circular layout.
   • Determines the size and color of the point (and outline if applicable).
5. Adds the points to the plot using matplotlib's scatter method.
6. If outlines are enabled, adds a second layer of larger points behind the main points.
7. Returns the modified axes object.

Use Cases

1. Highlighting specific nodes or tips on a circular tree plot.
2. Representing additional data points associated with tree nodes in a circular layout.
3. Creating visual indicators for certain traits or characteristics in a radial tree representation.
4. Enhancing circular tree visualizations with custom markers or data representations.

Example

import matplotlib.pyplot as plt
import numpy as np

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

# Plot the circular tree
tree.plotCircularTree(ax)

# Add points to all leaf nodes
tree.plotCircularPoints(ax, 
                        target=lambda n: n.is_leaf(),
                        size=30,
                        colour='blue',
                        alpha=0.7)

# Add points to internal nodes with high support
tree.plotCircularPoints(ax,
                        target=lambda n: n.is_node() and n.traits.get('posterior', 0) > 0.95,
                        size=50,
                        colour='red',
                        outline_colour='darkred',
                        normaliseHeight=lambda h: h * 0.9)  # Move points slightly inward

# Add points with varying sizes based on a trait
trait_values = [n.traits.get('some_trait', 0) for n in tree.Objects if n.is_leaf()]
max_trait = max(trait_values)
tree.plotCircularPoints(ax,
                        target=lambda n: n.is_leaf(),
                        size=lambda n: 20 + (n.traits.get('some_trait', 0) / max_trait) * 100,
                        colour=lambda n: plt.cm.viridis(n.traits.get('some_trait', 0) / max_trait),
                        outline=False,
                        normaliseHeight=lambda h: h * 1.1)  # Move points slightly outward

ax.set_aspect('equal')
ax.axis('off')
plt.tight_layout()
plt.show()

Notes

• This method is designed to work in conjunction with plotCircularTree() and assumes that the tree has been drawn in a circular layout.
• The circStart, circFrac, and inwardSpace parameters should typically match those used in plotCircularTree() for consistent positioning.
• The normaliseHeight function can be used to adjust the radial position of points, allowing them to be placed inward or outward from their default positions.
• The target, size, and colour parameters accept functions, allowing for great flexibility in determining what to plot and how.
• The outline feature can be used to make points more visible, especially when overlapping or against a complex background.
• For large trees, consider using the target parameter to selectively add points to avoid overcrowding.
• This method does not modify the tree structure; it only adds visual elements to the plot.
• When using functions for size or colour, ensure they can handle all possible inputs from the selected branches to avoid errors.
• The zorder parameter can be used to control whether the points appear above or below other elements in the plot.
• Remember to set the aspect ratio of the axes to 'equal' to ensure the circular layout is not distorted.