Plotting#

The phylozoo.viz module provides plotting for phylogenetic networks and graphs. Plots are rendered using matplotlib and return matplotlib.axes.Axes objects.

The plot() function accepts any of four object types and dispatches by type to the appropriate plotter:

How to Plot#

The plot() function has the following parameters:

  • obj — The object to plot (one of the four supported types).

  • layout (str, default=’auto’) — Layout algorithm. Use 'auto' for the default per type, or specify a name (e.g. 'pz-dag', 'spring', 'circular'). See the layout section below for more details.

  • style — Style object. See the Styling documentation for more details. Use None for the default style for the object type.

  • ax — Optional matplotlib axes. Plot on existing axes (e.g. for subplots).

  • show (bool, default=False) — If True, display the plot. If False, return the axes for saving or customization.

  • **kwargs — Layout-specific parameters (e.g. layer_gap=2.0 for 'pz-dag').

For quickly plotting a network, and you don’t need to customize the layout or style, you can use the following simple code to plot the network:

from phylozoo.viz import plot
from phylozoo import DirectedPhyNetwork

dnet = DirectedPhyNetwork.load("network.enewick")
plot(dnet)

Layouts#

A layout algorithm determines how nodes are positioned on the canvas. PhyloZoo supports three sources of layouts: NetworkX (built-in, no extra dependencies beyond phylozoo[viz]), Graphviz (requires pip install phylozoo[graphviz] and the Graphviz system library), and PhyloZoo (custom layouts for directed and semi-directed networks).

Pass the layout name as the layout argument; layout-specific parameters (e.g. layer_gap for pz-dag) go in **kwargs:

plot(network, layout='spring', k=2.0, iterations=50, show=True)
plot(network, layout='pz-dag', layer_gap=2.0, leaf_gap=1.5, show=True)

NetworkX and Graphviz layouts are supported by all four object types. PhyloZoo layouts are type-specific (see below).

NetworkX#

NetworkX layouts are built-in and require no extra installation. Common parameters: k (optimal distance between nodes), iterations, seed.

  • spring — Force-directed layout (Fruchterman-Reingold). Well-suited for general networks and graphs.

  • circular — Nodes arranged on a circle. Good for compact overviews.

  • kamada_kawai — Force-directed layout. Often produces evenly spaced, readable layouts for networks.

  • planar — Planar embedding (only for planar graphs).

  • random — Random node positions. Useful for testing.

  • shell — Nodes in concentric shells.

  • spectral — Uses eigenvectors of the graph Laplacian.

  • spiral — Spiral arrangement of nodes.

  • bipartite — Two-column layout for bipartite graphs.

For full parameter documentation (e.g. k, iterations, seed, scale, center), see the NetworkX layout reference.

Graphviz#

Graphviz layouts produce high-quality layouts and scale well to larger graphs. Install with:

pip install phylozoo[graphviz]

You must also install the Graphviz system library (e.g. apt install graphviz graphviz-dev on Debian/Ubuntu, brew install graphviz on macOS). See the PyGraphviz installation guide for details.

  • dot — Hierarchical (layered) layout. Well-suited for directed acyclic graphs and phylogenetic trees.

  • twopi — Radial layout with root at center. Good for trees and semi-directed networks (default for SemiDirectedPhyNetwork).

  • neato — Spring-model layout.

  • fdp — Force-directed placement.

  • sfdp — Scalable force-directed layout for large graphs.

  • circo — Circular layout.

For layout program parameters and attributes, see the PyGraphviz documentation and the Graphviz documentation.

PhyloZoo#

Custom layouts optimized for phylogenetic networks. Only available for specific types:

  • pz-dag (DirectedPhyNetwork only) — Tree-backbone layout with crossing minimization. Parameters:

    • layer_gap (float, default 1.5) — Spacing between hierarchical layers;

    • leaf_gap (float, default 1.0) — Spacing between leaves within a layer;

    • trials (int, default 2000) — Number of random child orderings to try for crossing minimization;

    • seed (int or None) — Random seed for reproducibility;

    • direction (str, default 'TD') — Layout direction: 'TD' (top-down) or 'LR' (left-right);

    • x_scale (float, default 1.5) — Scaling factor for x coordinates;

    • y_scale (float, default 1.0) — Scaling factor for y coordinates.

  • pz-radial (SemiDirectedPhyNetwork only, trees only) — Radial layout with root at center. Parameters:

    • radius (float, default 1.0) — Maximum radius for leaf nodes;

    • start_angle (float, default 0.0) — Starting angle in radians for the first leaf;

    • angle_direction (str, default 'clockwise') — Angle progression: 'clockwise' or 'counterclockwise'.

Saving a Figure#

The plot() function returns a matplotlib axes object. Set show=False and call the matplotlib savefig method on the figure:

ax = plot(network, show=False)
ax.figure.savefig("network.png", dpi=300, bbox_inches="tight")

Here, dpi controls the resolution of the saved image and bbox_inches='tight' crops the figure to the smallest bounding box that contains all plot elements, removing excess whitespace and ensuring labels are not cut off.

See Also#

  • Styling — Colors, sizes, and appearance