Of course! treeplotter is a fantastic, lightweight, and easy-to-use Python library specifically designed for plotting phylogenetic trees. It's particularly well-suited for beginners and for creating publication-quality figures with minimal code.

Here’s a comprehensive guide covering what it is, why you'd use it, and how to get started with code examples.

What is treeplotter?

treeplotter is a Python library focused on one primary task: visualizing phylogenetic trees. It's built on top of matplotlib, which means it integrates seamlessly with the rest of the scientific Python ecosystem (like NumPy and Pandas).

Key Features:

• Simplicity: The API is very intuitive. You can create a beautiful plot in just a few lines of code.
• Flexibility: It offers extensive customization options for colors, fonts, branch labels, node markers, and more.
• Modern Aesthetics: It produces clean, modern-looking figures that are perfect for publications and presentations.
• No External Dependencies: It only requires matplotlib and ete3 (for parsing tree files), making it very easy to install.
• Multiple Tree Formats: It can read trees from common formats like Newick ((.nwk)), Nexus (.nex), and PhyloXML.

Why Use treeplotter?

You might consider treeplotter over other popular options like ete3 or DendroPy for visualization because:

• Less Cluttered: ete3 is an incredibly powerful " Swiss Army knife " for tree analysis, but its plotting system can feel complex and its default styles can be a bit dated. treeplotter is purely for plotting, so its interface is cleaner and more focused.
• Easier Customization: While ete3 is customizable, treeplotter often provides more direct and "Pythonic" ways to tweak common plot elements like fonts and colors.
• matplotlib Integration: If you're already comfortable with matplotlib, treeplotter will feel right at home. You can easily combine tree plots with other matplotlib axes, add custom annotations, and save figures in any format matplotlib supports (PDF, PNG, SVG, etc.).

Installation

Installation is straightforward using pip. It's recommended to do this in a virtual environment.

pip install treeplotter

Quick Start: A Basic Example

Let's plot a simple tree from a Newick string.

import treeplotter
# 1. Define your tree as a Newick string
newick_string = "((A:0.5,B:0.5):0.5,(C:0.75,D:0.25):0.25);"
# 2. Create the plot
# The `plot_tree` function is the main entry point
fig, ax = treeplotter.plot_tree(newick_string)
# 3. Show or save the plot
fig.savefig("basic_tree.png", dpi=300, bbox_inches="tight")
# To display the plot in an interactive window (e.g., Jupyter Notebook, PyCharm):
# fig.show()

This will produce a clean, rectangular tree plot:

Customization is Key

The real power of treeplotter comes from its customization options. Let's make the tree more informative and visually appealing.

Example: Adding Colors, Labels, and a Title

import treeplotter
# A more complex Newick tree
newick_string = "((A:0.2,B:0.3):0.1,C:0.4,(D:0.15,E:0.25):0.05);"
# Define colors for the tips (leaves)
tip_colors = {
    "A": "#1f77b4", # A nice blue
    "B": "#ff7f0e", # A nice orange
    "C": "#2ca02c", # A nice green
    "D": "#d62728", # A nice red
    "E": "#9467bd"  # A nice purple
}
# Define a dictionary for branch labels (e.g., support values or gene names)
branch_labels = {
    "node_1": "0.95", # The internal node between A, B, and C
    "node_2": "1.00"  # The root node
}
# Create a customized plot
fig, ax = treeplotter.plot_tree(
    newick_string,
    # --- Tree Layout ---
    ladderize=True,         # Order the leaves from most to least derived
    show_support=True,      # Show internal node labels as support values
    # --- Tip (Leaf) Customization ---
    tip_labels=True,        # Show the names of the leaves
    tip_labels_colors=tip_colors, # Apply custom colors to tips
    # --- Branch Customization ---
    branch_labels=branch_labels, # Add custom labels to branches
    branch_labels_size=8,        # Font size for branch labels
    # --- Node Customization ---
    node_size=15,           # Size of the dots at internal nodes
    node_colors="black",    # Color of the node dots
    # --- General Plot Aesthetics ---
    label_size=12,          # Font size for tip labels"My Custom Phylogeny", # Add a title to the plot
    width=12,               # Figure width in inches
    height=6                # Figure height in inches
)
# Save the high-quality figure
fig.savefig("custom_tree.png", dpi=300, bbox_inches="tight")
fig.show()

This example demonstrates several key customization arguments:

• ladderize: Sorts the branches to make the tree easier to read.
• tip_labels_colors: A dictionary mapping leaf names to colors.
• branch_labels: Adds text to internal branches.
• node_size / node_colors: Controls the appearance of the dots at nodes., width, height: Standard figure parameters.

Working with Tree Files

In a real-world scenario, you'll likely have a tree file (.nwk, .nex, etc.) instead of a string. treeplotter handles this gracefully.

First, let's create a dummy Newick file named my_tree.nwk:

# This is just to create a file for the example
dummy_newick = "((Homo_sapiens:0.1,Pan_troglodytes:0.1):0.2,(Gorilla_gorilla:0.3,Pongo_pygmaeus:0.4):0.1);"
with open("my_tree.nwk", "w") as f:
    f.write(dummy_newick)

Now, let's plot it directly from the file:

import treeplotter
fig, ax = treeplotter.plot_tree(
    "my_tree.nwk",  # Pass the file path directly
    tip_labels_size=10,
    show_support=False
)
fig.savefig("tree_from_file.png", dpi=300, bbox_inches="tight")
fig.show()

Advanced Usage: Combining with matplotlib

Since treeplotter uses matplotlib, you have the full power of the ecosystem at your fingertips. For example, you can add a custom legend.

import treeplotter
import matplotlib.pyplot as plt
# Use the same tree as before
newick_string = "((A:0.2,B:0.3):0.1,C:0.4,(D:0.15,E:0.25):0.05);"
tip_colors = {"A": "blue", "B": "orange", "C": "green", "D": "red", "E": "purple"}
# Create the plot
fig, ax = treeplotter.plot_tree(newick_string, tip_labels_colors=tip_colors)
# --- Add a custom legend using matplotlib ---
# We need to create proxy artists for the legend
from matplotlib.lines import Line2D
legend_elements = [
    Line2D([0], [0], marker='o', color='w', label='Species A',
           markerfacecolor='blue', markersize=10),
    Line2D([0], [0], marker='o', color='w', label='Species B',
           markerfacecolor='orange', markersize=10),
    Line2D([0], [0], marker='o', color='w', label='Species C',
           markerfacecolor='green', markersize=10),
    Line2D([0], [0], marker='o', color='w', label='Species D',
           markerfacecolor='red', markersize=10),
    Line2D([0], [0], marker='o', color='w', label='Species E',
           markerfacecolor='purple', markersize=10)
]
ax.legend(handles=legend_elements, title="Species", loc="upper right")
# Add a custom annotation
ax.annotate('Important Node', xy=(0.4, 3), xytext=(0.6, 3.5),
            arrowprops=dict(facecolor='black', shrink=0.05, width=1, headwidth=8))
fig.savefig("tree_with_matplotlib.png", dpi=300, bbox_inches="tight")
fig.show()

Comparison with Other Libraries

Conclusion: Choose treeplotter when your main goal is to create a high-quality, easily customizable figure. Choose ete3 when you need to perform complex analyses on your trees and then visualize them. Choose Bio.Phylo for basic tree handling, especially if you're already working within the Biopython ecosystem.