TreeViz Python

treeviz-phylo builds TreeViz-native .treeviz.json sessions from Python scripts and notebooks. It handles tree input, metadata binding, schema validation, notebook iframe views, basic tree inspection, and static export through an external TreeViz renderer.

Documentation · Issues

The package does not vendor the TreeViz browser app or frontend source. It ships only the Python helpers and the TreeViz session schema.

Install or update from PyPI:

pip install --upgrade treeviz-phylo

Notebook extra:

pip install --upgrade "treeviz-phylo[notebook]"

Minimal use:

from treeviz import (
    binding_diagnostics,
    build_session,
    leaf_names,
    render_tree,
    save_session,
    tree_stats,
    validate_session,
    view_session,
)

tree = "(A:0.1,B:0.2,(C:0.3,D:0.4):0.5);"
metadata = [
    {
        "id": "A",
        "group": "alpha",
        "value": 1.2,
        "node_diameter": 10,
        "node_color": "#5eead4",
        "branch_width": 2.6,
        "branch_color": "#5eead4",
    },
    {
        "id": "B",
        "group": "alpha",
        "value": 0.8,
        "node_diameter": 9,
        "node_color": "#67e8f9",
        "branch_width": 2.3,
        "branch_color": "#67e8f9",
    },
    {
        "id": "C",
        "group": "beta",
        "value": 2.1,
        "node_diameter": 9,
        "node_color": "#fb923c",
        "branch_width": 2.0,
        "branch_color": "#fb923c",
    },
    {
        "id": "D",
        "group": "beta",
        "value": 1.6,
        "node_diameter": 8,
        "node_color": "#fdba74",
        "branch_width": 1.7,
        "branch_color": "#fdba74",
    },
]
tracks = [
    {"kind": "color_strip", "column_key": "group", "title": "Group", "palette": "okabe-ito"},
    {"kind": "gradient", "column_key": "value", "title": "Value", "palette": "Viridis"},
]
view = {
    "nodeCircleDiameterAttribute": "node_diameter",
    "nodeCircleColorAttribute": "node_color",
    "branchWidthAttribute": "branch_width",
    "branchColorAttribute": "branch_color",
    "prettyTerminalBranches": True,
}

session = build_session(tree, metadata=metadata, tracks=tracks, row_key_column="id", view=view)
validate_session(session)
save_session(session, "example.treeviz.json")
print(leaf_names(session))
print(tree_stats(session))
print(binding_diagnostics(session))

view = view_session(session, open_browser=False)
print(view.url)

In Jupyter, display the interactive tree inline:

from IPython.display import display

display(view)

Static export requires a TreeViz renderer command, such as the source checkout CLI. render_tree defaults to bun run treeviz render; pass cwd when the current working directory is not the checkout root.

from pathlib import Path

render_tree(
    tree,
    metadata=metadata,
    tracks=tracks,
    format="pdf",
    output="example.pdf",
    width=1400,
    height=620,
    auto_crop=True,
    crop_padding=24,
    metrics="example.metrics.json",
    cwd=Path("/path/to/treeviz"),
)

Use auto_crop=True to trim exported SVG/PNG/PDF artifacts to the visible tree content. The optional metrics JSON records the content box, crop box, whitespace margins, fill ratios, and crop warnings for automated checks.

Metadata rows must contain one key column whose values match tree leaf labels (surrounding whitespace is ignored; binding_flags turns on case, underscore, and quoted-suffix matching). Pass it as row_key_column. Values may be strings, numbers, booleans, None, or empty strings; empty strings, None, and NaN become missing values (JSON null). Supported track kinds are color_strip, gradient, heatmap, bar, stacked_bar, text, and binary_dots. Legends, connections, node metadata, and saved views can be passed as keyword arguments; see the Python guide.

Use column_keys for heatmaps and stacked bars. Stacked bars normalize each row by default; set normalize=False to show unnormalized values.

For compact metadata lanes, color_strip accepts display_mode="symbol" or "wedge" and symbol_shape; bar accepts display_mode, manual bins, or automatic auto_bins. Snake_case and camelCase field names are both accepted.

Palette ids match the browser registry returned by window.__treeviz.palettes(). Common ids are okabe-ito, Viridis, Magma, Cividis, Blues, blue-orange, RdBu, BrBG, gray, and slate.

Use view keys such as nodeCircleDiameterAttribute, nodeCircleColorAttribute, branchWidthAttribute, branchColorAttribute, and prettyTerminalBranches to preserve exact node circles, branch widths, branch colors, and the pretty terminal branch setting in saved sessions. Direct per-node overrides can also be stored in view["cladeStyles"][stable_key] with fields such as labelFontSize, nodeCircleDiameter, and nodeCircleColor; these are usually easier to create from the browser Inspector.

The source checkout includes a runnable script:

PYTHONPATH=packages/python/src pixi run -e py python packages/python/examples/plot_treeviz_examples.py --out /tmp/treeviz-python-plots