Metadata-Version: 2.4
Name: treeviz-phylo
Version: 0.8.3
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://fmschulz.github.io/treeviz/PYTHON/
Project-URL: Agent-Skill, https://github.com/fmschulz/treeviz/tree/main/.agents/skills/treeviz-agent
Author: Frederik Schulz
License-Expression: MIT
License-File: LICENSE
Keywords: bioinformatics,jupyter,newick,phylogenetics,tree visualization
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
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: Programming Language :: Python :: 3.13
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.

[Documentation](https://fmschulz.github.io/treeviz/PYTHON/) ·
[Issues](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 or update from PyPI:

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

Notebook extra:

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

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)
```

In Jupyter, display the interactive tree inline:

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

```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 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](https://fmschulz.github.io/treeviz/PYTHON/).

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:

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