viz#

Network visualization and plotting (viz).

The visualization module provides a flexible plotting system for phylogenetic networks and graphs with support for multiple layout algorithms and customizable styling. Use plot() for all supported types (it dispatches by object type) and to_preview_string() for a text drawing that needs no matplotlib.

Plotting#

phylozoo.viz.plot(obj: Any, layout: str = 'auto', style: Any = None, ax: Any | None = None, show: bool = False, **kwargs: Any) → Any[source]#

Plot a phylogenetic network or graph.

Dispatches by object type: DirectedPhyNetwork, SemiDirectedPhyNetwork, DirectedMultiGraph, or MixedMultiGraph. Use layout=’auto’ for the default layout per type, or specify a layout name.

Parameters:

  • obj (DirectedPhyNetwork | SemiDirectedPhyNetwork | DirectedMultiGraph | MixedMultiGraph) – The network or graph to plot.

  • layout (str, optional) – Layout algorithm. Use ‘auto’ for the default per type. DirectedPhyNetwork: ‘pz-cladogram’ (default), ‘pz-layered’, ‘pz-radial’, ‘pz-unrooted’, or NetworkX (‘spring’, ‘circular’, ‘kamada_kawai’, ‘planar’, ‘random’, ‘shell’, ‘spectral’, ‘spiral’, ‘bipartite’) or Graphviz (‘dot’, ‘neato’, ‘fdp’, ‘sfdp’, ‘twopi’, ‘circo’). SemiDirectedPhyNetwork: ‘pz-unrooted’ (default), ‘pz-radial’, or NetworkX/Graphviz (e.g. ‘neato’). DirectedMultiGraph / MixedMultiGraph: NetworkX or Graphviz only (no PhyloZoo layouts). By default ‘auto’.

  • style (DNetStyle | SDNetStyle | DMGraphStyle | MGraphStyle, optional) – Styling configuration. If None, uses default style for the object type. By default None.

  • ax (matplotlib.axes.Axes, optional) – Existing axes to plot on. If None, creates new figure and axes. By default None.

  • show (bool, optional) – If True, automatically display the plot using plt.show(). By default False.

  • **kwargs – Additional parameters for layout computation (e.g. layer_gap, leaf_gap for pz-cladogram).

Returns:

The axes object containing the plot.

Return type:

matplotlib.axes.Axes

Raises:

Examples

>>> from phylozoo import DirectedPhyNetwork
>>> from phylozoo.viz import plot
>>>
>>> net = DirectedPhyNetwork(
...     edges=[(3, 1), (3, 2)],
...     nodes=[(1, {'label': 'A'}), (2, {'label': 'B'})]
... )
>>> ax = plot(net)
>>> ax = plot(net, layout='spring', show=False)

Terminal preview#

phylozoo.viz.to_preview_string(network: DirectedPhyNetwork | SemiDirectedPhyNetwork, col_width: int | None = None, rows_per_leaf: int | None = None, max_width: int = 120, max_leaves: int = 80, root_location: Any = None, **layout_kwargs: Any) → str[source]#

Draw a network as text, root on the left and leaves on the right.

Tree edges are box-drawing lines (─ │ ┌ └ ├ …), hybrid edges dotted lines (┄ ┊) ending in an arrowhead at the hybrid node (◆); the root is ○, other nodes ●, and leaf labels follow their leaf. The placement is that of the rectangular pz-cladogram layout, so hybrid edges are horizontal or vertical where the network allows it and sibling subtrees stay together. A semi-directed network is rooted first with to_d_network().

Parallel edges are drawn as a loop: the second copy detours one row above (or below) the first, so both stay visible.

Large networks are compacted automatically: the column width shrinks until the drawing fits max_width characters (down to 3) and the blank row between leaves is dropped above 25 leaves. Networks with more than max_leaves leaves are refused, because one text row per leaf stops being readable; raise max_leaves or use plot().

Parameters:

  • network (DirectedPhyNetwork | SemiDirectedPhyNetwork) – The network to draw.

  • col_width (int | None, optional) – Characters per layer. None picks the largest of 8, 6, 4, 3 that fits max_width. By default None.

  • rows_per_leaf (int | None, optional) – Rows per leaf: 2 leaves a blank row between leaves, 1 is compact. None chooses 2 up to 25 leaves and 1 above. By default None.

  • max_width (int, optional) – Target maximum line length used to pick col_width. By default 120.

  • max_leaves (int, optional) – Refuse networks with more leaves than this. By default 80.

  • root_location (node or edge, optional) – Semi-directed networks only: where to root (see to_d_network). None lets to_d_network choose. By default None.

  • **layout_kwargs – Options of compute_pz_cladogram_layout() (e.g. trials, seed, horizontal_reticulations).

Returns:

The drawing, lines separated by newlines, without trailing spaces.

Return type:

str

Raises:

Examples

>>> from phylozoo import DirectedPhyNetwork
>>> from phylozoo.viz import to_preview_string
>>> net = DirectedPhyNetwork(
...     edges=[(5, 3), (5, 4), (3, 2), (4, 2), (2, 1), (3, 6), (4, 7)],
...     nodes=[(1, {'label': 'A'}), (6, {'label': 'B'}), (7, {'label': 'C'})]
... )
>>> print(to_preview_string(net))
        ┌───────────────● B
┌───────●
○       └┄┄┄┄┄┄>◆───────● A
│               ^
└───────────────●───────● C

Submodules#