Metadata-Version: 2.4
Name: treeviz-phylo
Version: 0.5.0
Summary: TreeViz-native Python helpers for building .treeviz.json sessions
Project-URL: Homepage, https://treeviz.newlineages.com/
Project-URL: Issues, https://github.com/fmschulz/treeviz/issues
Project-URL: Documentation, https://github.com/fmschulz/treeviz/blob/main/docs/PYTHON.md
Project-URL: Agent-Skill, https://github.com/fmschulz/treeviz/tree/main/.agents/skills/treeviz-agent
Author: Frederik Schulz
License-Expression: MIT
Keywords: bioinformatics,jupyter,newick,phylogenetics,tree visualization
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.10
Requires-Dist: jsonschema>=4.0
Provides-Extra: dataframe
Requires-Dist: pandas>=2.0; extra == 'dataframe'
Provides-Extra: notebook
Requires-Dist: ipython>=8.0; extra == 'notebook'
Description-Content-Type: text/markdown

# 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:

```bash
pip install treeviz-phylo
```

Notebook extra:

```bash
pip install "treeviz-phylo[notebook]"
```

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

Minimal use:

```python
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.

```python
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:

```bash
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`.
