Metadata-Version: 2.4
Name: treeviz-phylo
Version: 0.1.0
Summary: TreeViz-native Python helpers for building .treeviz.json sessions
Project-URL: Homepage, https://treeviz.newlineages.com/
Project-URL: Repository, https://github.com/fmschulz/treeviz
Project-URL: Issues, https://github.com/fmschulz/treeviz/issues
Project-URL: Documentation, https://github.com/fmschulz/treeviz/blob/main/docs/PYTHON.md
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.

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

From a source checkout:

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

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},
    {"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.

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

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