gos 🦆

gos is a declarative (epi)genomics visualization library for Python. It is built on top of the Gosling JSON specification, providing a simplified interface for authoring interactive genomic visualizations.

Installation

The gos API is under active development. Feedback is appreciated and welcomed.

pip install gosling

Documentation

See the Documentation Site for more information.

Example

import gosling as gos

data = gos.multivec(
    url="https://server.gosling-lang.org/api/v1/tileset_info/?d=cistrome-multivec",
    row="sample",
    column="position",
    value="peak",
    categories=["sample 1", "sample 2", "sample 3", "sample 4"],
    binSize=5,
)

base_track = gos.Track(data, width=800, height=100)

heatmap = base_track.mark_rect().encode(
    x=gos.X("start:G", axis="top"),
    xe="end:G",
    row=gos.Row("sample:N", legend=True),
    color=gos.Color("peak:Q", legend=True),
)

bars = base_track.mark_bar().encode(
    x=gos.X("position:G", axis="top"),
    y="peak:Q",
    row="sample:N",
    color=gos.Color("sample:N", legend=True),
)

lines = base_track.mark_line().encode(
    x=gos.X("position:G", axis="top"),
    y="peak:Q",
    row="sample:N",
    color=gos.Color("sample:N", legend=True),
)

gos.vertical(heatmap, bars, lines).properties(
    title="Visual Encoding",
    subtitle="Gosling provides diverse visual encoding methods",
    layout="linear",
    centerRadius=0.8,
    xDomain=gos.GenomicDomain(chromosome="1", interval=[1, 3000500]),
)

Example Gallery

We have started a gallery of community examples in gosling/examples/. If you are interested in contributing, please feel free to submit a PR! Checkout the existing JSON examples if you are looking for inspiration.

Development

pip install -e '.[dev]'

The schema bindings (gosling/schema/) and docs (doc/user_guide/API.rst) are automatically generated using the following. Please do not edit these files directly.

# generate gosling/schema/*
python tools/generate_schema_wrapper.py

Release

git checkout main && git pull

Update version in setup.cfg and doc/conf.py:

git add setup.cfg doc/conf.py
git commit -m "v0.[minor].[patch]"
git tag -a v0.[minor].[patch] -m "v0.[minor].[patch]"
git push --follow-tags

Design & Implementation

gos is inspired by and borrows heavily from Altair both in project philosophy and implementation. The internal Python API is auto-generated from the Gosling specification using code adapted directly from Altair to generate Vega-Lite bindings. This design choice guarantees that visualizations are type-checked in complete concordance with the Gosling specification, and that the Python API remains consistent with the evolving schema over time. Special thanks to Jake Vanderplas and others on schemapi.