Method `baltic.tree.plotPoints`

tree.plotPoints() Method

Description

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

Syntax

def plotPoints(self, ax, x_attr=None, y_attr=None, target=None, size=None, colour=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 objects.
• 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).
• 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. 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 size and color of the point (and outline if applicable).
3. Adds the points to the plot using matplotlib's scatter method.
4. If outlines are enabled, adds a second layer of larger points behind the main points.
5. Returns the modified axes object.

Use Cases

1. Highlighting specific nodes or tips on the tree.
2. Representing additional data points associated with tree nodes.
3. Creating visual indicators for certain traits or characteristics.
4. Enhancing 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=(12, 8))

# Plot the tree
tree.plotTree(ax)

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

# Add points to internal nodes with high support
tree.plotPoints(ax,
                target=lambda n: n.is_node() and n.traits.get('posterior', 0) > 0.95,
                x_attr=lambda n: n.x - 0.1,  # Offset slightly
                size=50,
                colour='red',
                outline_colour='darkred')

# 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.plotPoints(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)

plt.tight_layout()
plt.show()

Notes

• The target, x_attr, y_attr, 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.
• The zorder parameter can be used to control whether the points appear above or below other elements in the plot.
• Additional point formatting can be controlled through the **kwargs, which are passed directly to matplotlib's scatter() function.
• This method is particularly useful for adding data visualization elements directly onto the tree structure.
• For large trees, consider using the target parameter to selectively add points to avoid overcrowding.
• 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.
• When using functions for size or colour, ensure they can handle all possible inputs from the selected branches to avoid errors.