Save and inspect charts

A GenomeSpy Python chart can be converted to the JSON-compatible specification that GenomeSpy renders in the browser. Most readers only need this when saving a chart, passing it to another tool, or inspecting the generated grammar.

Inspect the specification

to_dict() returns the complete specification as Python dictionaries, lists, strings, and numbers:

spec = chart.to_dict()

mark_definition = spec["mark"]
x_definition = spec["encoding"]["x"]
schema_url = spec["$schema"]

The result uses GenomeSpy property names. For example, gs.X becomes an x-channel definition with field and type. The root $schema URL identifies the GenomeSpy schema used to validate the chart. Those property names are the ones documented in the GenomeSpy grammar, so a serialized chart can be read against it directly.

Use to_json() when another program expects JSON text:

json_spec = chart.to_json()

Both methods validate the chart by default. Inline tables become ordinary JSON records, while URL and lazy data sources remain URLs for the browser to load.

Save JSON or HTML

The filename extension selects JSON or standalone HTML output:

def save_examples(directory: Path) -> tuple[Path, Path]:
    """Save JSON and browser-runnable HTML examples in a directory."""
    json_path = directory / "measurements.json"
    html_path = directory / "measurements.html"
    chart.save(json_path)
    chart.save(html_path)
    return json_path, html_path

from pathlib import Path

json_path, html_path = save_examples(Path("output"))

The JSON file contains the validated specification. The HTML file contains the chart container and embedding code, but still loads the GenomeSpy JavaScript bundle and any remote datasets over the network. Inline data is included in the file.

Use to_html() when integration code needs the HTML as a string rather than a file. Complete method signatures and validation options are listed in the API reference.

See Display controls and embed options to choose controls or pass settings to GenomeSpy’s embed API.