Syntviz

Syntviz prepares genome comparisons locally and draws portable synteny figures: gene neighborhoods, protein links shaded by identity, repeat arms, chromosome comparisons, circular maps and metadata tracks. A session file holds the evidence and the figure state; the same session opens in a notebook, in the command line renderer and in the web viewer.

Install

pip install syntviz

The package needs Python 3.11 or later. The interactive notebook figure needs only Python; without Node.js the notebook skips its static SVG preview. Validation, edits and SVG, PNG or PDF export run the bundled renderer through Node.js 22.12 or later, which must be on PATH. Sequence searches (MMseqs2, minimap2) and gene calling (Pyrodigal) need those tools installed separately.

Use

Import a genome and show it in a notebook:

from pathlib import Path

from syntviz.importers import ImportFile, ImportSpec, import_genome
from syntviz.notebook import Figure

session = import_genome(
    ImportSpec(
        genome_id="phage",
        name="Phage A",
        files=[ImportFile(path=Path("phage.gbk"), role="genbank")],
        organism_context="virus",
    )
)
Figure(session)  # interactive viewer in the cell output, works offline

Load a saved session, check it and export a figure:

from pathlib import Path

from syntviz.models import Session
from syntviz.runtime import render, validate

session = Session.model_validate_json(Path("figure.syntviz.json").read_text())
validate(session)  # {"valid": True, "diagnostics": [...]}
render(session, Path("figure.svg"))

The syntviz command offers the same operations:

syntviz discover                                  # session and command schemas
syntviz edit figure.syntviz.json commands.json edited.syntviz.json
syntviz render edited.syntviz.json figure.pdf
syntviz view figure.syntviz.json                  # local viewer on loopback

commands.json holds a JSON array of commands such as setView, which takes a complete view; syntviz discover lists every command and its schema.

License

Lawrence Berkeley National Laboratory non-commercial use only license; see LICENSE. Questions about rights to use or distribute the software go to Berkeley Lab's Intellectual Property Office.