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.

Public documentation: https://github.com/fmschulz/treeviz/blob/main/docs/PYTHON.md

Issues and usage reports: https://github.com/fmschulz/treeviz/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 after a release is uploaded to PyPI:

pip install treeviz-phylo

Notebook extra:

pip install "treeviz-phylo[notebook]"

Development source-checkout installs are maintained separately and are not required for package users.

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)

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 exactly match tree leaf labels. Pass it as row_key_column. Values may be strings, numbers, booleans, None, or empty strings; missing values are handled explicitly. Supported track kinds are color_strip, gradient, heatmap, bar, text, and binary_dots.

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

Full documentation is in docs/PYTHON.md.