Composing a genome browser

Independent cytoband, six-frame translation, BAM alignment, and RefSeq views are imported by URL and aligned under a parent-owned genomic scale and axis.

Data use and provenance

The imported specifications and their data come from the official GenomeSpy examples listed below. The URLs are pinned to one upstream commit so the gallery does not silently change when GenomeSpy’s main branch changes.

Imported track specifications

This example intentionally loads four existing JSON view specifications. Each source has a corresponding Python-authored gallery example that shows how the track itself can be constructed:

Imported JSON specification	Python-authored example	Official GenomeSpy example
cytobands.json	Chromosome ideogram	Cytobands
indexed-fasta-six-frame-translation.json	Indexed FASTA six-frame translation	Six-frame translation
bam-read-alignments.json	BAM read alignments	BAM alignments
scored-refSeq-genes.json	RefSeq genes with scored labels	RefSeq genes

What to notice

The parent specification supplies the assembly, locus domain, and shared genome axis. The imported children keep their own dataflows, marks, and vertical scales while panning and zooming together.

Python implementation

This is deliberately an import example rather than a reimplementation of its tracks. gs.import_view(url=...) creates each child and gs.vconcat() arranges them vertically. GenomeSpy retrieves and resolves the JSON specifications in the browser when the visualization is rendered.

See Import remote view specifications for URL handling, version pinning, and reuse considerations. The official composed genome browser provides the original composition discussion.

Code

"""Composing a genome browser.

Independent cytoband, six-frame translation, BAM alignment, and RefSeq views
are imported by URL and aligned under a parent-owned genomic scale and axis.
"""

import genome_spy as gs


# Use a fixed version of the hosted examples so their contents stay the same.
EXAMPLE_ROOT = (
    "https://raw.githubusercontent.com/genome-spy/genome-spy/"
    "d2e9bd71/examples/docs/examples/genomic-data"
)

# Load four ready-made charts from JSON files and stack them vertically.
chart = (
    gs.vconcat(
        gs.import_view(url=f"{EXAMPLE_ROOT}/cytobands.json"),
        gs.import_view(url=f"{EXAMPLE_ROOT}/indexed-fasta-six-frame-translation.json"),
        gs.import_view(url=f"{EXAMPLE_ROOT}/bam-read-alignments.json"),
        gs.import_view(url=f"{EXAMPLE_ROOT}/scored-refSeq-genes.json"),
    )
    .properties(
        assembly="hg38",
        description=(
            "Imported cytoband, six-frame translation, BAM alignment, and "
            "RefSeq views composed into a shared-locus genome browser."
        ),
        # Start all four tracks at the same region on chromosome 20.
        scales=gs.scales(
            x=gs.Scale(
                domain=[
                    {"chrom": "chr20", "pos": 10006452},
                    {"chrom": "chr20", "pos": 10006533},
                ]
            )
        ),
        axes=gs.axes(x=gs.GenomeAxis(orient="top", title=None)),
    )
    # Show one position axis for the whole browser.
    .resolve_axis(x="shared")
    .configure_legend(disable=True)
)

Show specification