tracy-visualisations

A Python package that bundles Tracy JSON output files together with the TraceView and Indigo web components into self-contained HTML files that can be opened in any modern browser with no server required.

Installation

pip install .

Quick start

As a CLI tool

# Auto-detect visualisation type from the JSON content
tracy-vis results.json

# Explicit output path
tracy-vis results.json report.html

# Force indigo visualisation type
tracy-vis results.json report.html --type indigo

As a Python module

from tracy_visualisations import bundle

# Write to file and return the HTML string
html = bundle("results.json", "report.html")

# Return HTML string only (no file written)
html = bundle("results.json")

# Force a specific visualisation type
html = bundle("results.json", "report.html", data_type="trace")

As a Docker container

# Build the image
docker build -t tracy-vis .

# Run it against files in the current directory
docker run --rm -v "$PWD:/work" tracy-vis results.json

# Explicit output path and visualisation type
docker run --rm -v "$PWD:/work" tracy-vis results.json report.html --type indigo

# Run using precompiled image
docker run --rm -v "$PWD:/work" ghcr.io/biosustain/tracy-visualisations results.json 

The container starts the tracy-vis CLI directly, so any CLI arguments can be passed after the image name.

Visualisation types

Type	Detected when	Components used
trace	JSON contains a gappedTrace key	<trace-view> from traceView.js
indigo	JSON contains alt1align, decomposition, or variants	<trace-view>, <alignment-view>, <decomposition-view>, <variants-view> from elements.js

Running tests

pip install ".[dev]"
pytest

LICENSING

This project depends on GPL-3.0 licensed libraries. As a result, this project is also distributed under the GPL-3.0 license.