treeviz-phylo 0.1.0

TreeViz-native Python helpers for building .treeviz.json sessions

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.

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]"

From a source checkout:

pixi run -e py python -m pip install -e packages/python

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},
    {"id": "B", "group": "alpha", "value": 0.8},
    {"id": "C", "group": "beta", "value": 2.1},
    {"id": "D", "group": "beta", "value": 1.6},
]
tracks = [
    {"kind": "color_strip", "column_key": "group", "title": "Group"},
    {"kind": "gradient", "column_key": "value", "title": "Value"},
]

session = build_session(tree, metadata=metadata, tracks=tracks, row_key_column="id")
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.

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.