Metadata-Version: 2.5
Name: genome-spy-python
Version: 0.2.0
Summary: genome-spy-python is a declarative genomics visualization library for Python, built on top of the genome-spy JSON specification.
Project-URL: Homepage, https://github.com/genome-spy/genome-spy-python
Project-URL: Documentation, https://genomespy.app/genome-spy-python/
Project-URL: Repository, https://github.com/genome-spy/genome-spy-python
Project-URL: Issues, https://github.com/genome-spy/genome-spy-python/issues
Author-email: Oskari Lehtonen <oskarilehtonen4@gmail.com>
License-Expression: MIT AND BSD-3-Clause
License-File: LICENSE
License-File: LICENSES/ALTAIR-BSD-3-Clause.txt
License-File: LICENSES/GALLERY-DATA-MIT.txt
License-File: THIRD_PARTY_NOTICES.md
Keywords: anywidget,genome-spy,genomics,jupyter,visualization
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Jupyter
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.11
Requires-Dist: anywidget>=0.11.0
Requires-Dist: jsonschema>=4.26.0
Requires-Dist: traitlets>=5.14.3
Provides-Extra: arrow
Requires-Dist: pyarrow>=18.0.0; extra == 'arrow'
Description-Content-Type: text/markdown

<p align="center">
  <img src="docs/_static/snaketie.svg" width="180" alt="GenomeSpy for Python logo">
</p>

<h1 align="center">genome-spy-python</h1>

<p align="center">
  <a href="https://github.com/genome-spy/genome-spy-python/actions/workflows/ci.yml"><img src="https://github.com/genome-spy/genome-spy-python/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI status"></a>
  <a href="https://pypi.org/project/genome-spy-python/"><img src="https://img.shields.io/pypi/v/genome-spy-python" alt="PyPI version"></a>
  <a href="https://colab.research.google.com/github/genome-spy/genome-spy-python/blob/main/notebooks/brush_linked_genome_tracks.ipynb"><img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open brush example in Colab"></a>
</p>

`genome-spy-python` is a Python interface for
<a href="https://genomespy.app/" target="_blank" rel="noopener noreferrer">GenomeSpy</a>,
a grammar for interactive and scalable genomic visualization. It lets Python
users build GenomeSpy specifications with a declarative, fluent API, serialize
them to JSON, and display them in Jupyter or Marimo notebooks.

Read the [documentation](https://genomespy.app/genome-spy-python/) for the
getting-started guide, user guide, examples, and API reference.

<a href="https://altair-viz.github.io/" target="_blank" rel="noopener noreferrer">Altair</a>
is the project's main source of inspiration. This codebase follows Altair's
approach of combining schema-backed specification objects with a small
handwritten Python API for marks, encodings, composition, and rendering. It
adapts that model to GenomeSpy's genomics-native grammar: locus scales, genomic
data sources, and coordinated genomic views.

The project is under active development. The current focus is the reusable
GenomeSpy Core grammar and notebook rendering; GenomeSpy App-specific features
will come later.

## Installation

The package requires Python 3.11 or newer.

From PyPI:

```bash
pip install genome-spy-python
```

From source:

```bash
pip install uv
git clone https://github.com/genome-spy/genome-spy-python.git
cd genome-spy-python
uv sync
```

For notebook use, install with Arrow support. This includes PyArrow for
dataframe transport:

```bash
pip install "genome-spy-python[arrow]"
```

See [creating and updating charts in notebooks](docs/user-guide/notebooks.md)
for supported tables and live updates.

See the [getting-started guide](docs/getting-started.md) for the first example.

## Examples

```python
import genome_spy as gs

chart = (
    gs.Chart(
        [
            {"x": 1, "y": 4, "group": "A"},
            {"x": 2, "y": 3, "group": "B"},
            {"x": 3, "y": 5, "group": "A"},
        ]
    )
    .mark_point(size=80)
    .encode(
        x="x:Q",
        y="y:Q",
        color="group:N",
    )
)

chart
```

GenomeSpy also has locus-scaled axes for genomic coordinates. This small
example renders intervals along a region of chromosome 1:

```python
import genome_spy as gs

intervals = [
    {"chrom": "chr1", "start": 100, "end": 220, "name": "gene A"},
    {"chrom": "chr1", "start": 280, "end": 420, "name": "gene B"},
]

chart = (
    gs.Chart(intervals)
    .mark_rect()
    .encode(
        x=gs.Locus("chrom", "start"),
        x2="end:Q",
        y="name:N",
        color="name:N",
    )
)

chart
```

Charts can be serialized to a portable GenomeSpy specification or standalone
HTML:

```python
chart.to_json()
chart.save("intervals.html")
```

### Update data without recreating the chart

For reactive Jupyter or Marimo notebooks, create a widget with an explicitly
named dataset and replace that dataset as inputs change. The browser keeps the
existing GenomeSpy instance, so view state such as zoom is preserved.

```python
chart = (
    gs.Chart(data={"name": "table"}, datasets={"table": []})
    .mark_point()
    .encode(x="x:Q", y="y:Q")
)
view = chart.widget()

view.set_dataset("table", updated_dataframe)
```

See [creating and updating charts in notebooks](docs/user-guide/notebooks.md)
for the Marimo pattern.

## Contributing

Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for development
setup, testing, code generation, documentation, gallery, and pull-request
guidelines.

## References

- <a href="https://genomespy.app/" target="_blank" rel="noopener noreferrer">GenomeSpy</a>
  — the upstream visualization grammar and JavaScript renderer.
- <a href="https://altair-viz.github.io/" target="_blank" rel="noopener noreferrer">Altair</a>
  — a schema-wrapper design reference.
- <a href="https://gosling-lang.org/" target="_blank" rel="noopener noreferrer">Gos</a>
  — a related grammar and Python-wrapper design reference for
  genomics visualization.

Portions of the schema-wrapper implementation and selected tests are adapted
from Altair under its BSD-3-Clause license. See
[Third-party notices](THIRD_PARTY_NOTICES.md) for the exact sources and license.
