genome-spy-python 0.1.0__tar.gz → 0.3.0__tar.gz

{genome_spy_python-0.1.0 → genome_spy_python-0.3.0}/.github/workflows/ci.yml

@@ -68,3 +68,32 @@ jobs:
       - run: uv run python tools/generate_schema_wrapper.py
       - run: uv run ruff format src/genome_spy/schema src/genome_spy/helpers.py src/genome_spy/api.py src/genome_spy/__init__.py
       - run: git diff --exit-code src/genome_spy/schema src/genome_spy/helpers.py src/genome_spy/api.py src/genome_spy/__init__.py tools
+
+  notebook-rendering:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v9.0.0
+        with:
+          python-version: "3.11"
+      - run: uv build --wheel
+      - name: Install the wheel with the minimum supported AnyWidget
+        run: |
+          uv venv --seed --python 3.11 "$RUNNER_TEMP/notebook-env"
+          for wheel in "$GITHUB_WORKSPACE"/dist/*.whl; do
+            uv pip install --python "$RUNNER_TEMP/notebook-env/bin/python" \
+              "$wheel[arrow]" "anywidget==0.11.0" jupyterlab pandas numpy playwright pillow
+          done
+          "$RUNNER_TEMP/notebook-env/bin/python" -m playwright install --with-deps chromium
+      - name: Render the brush notebook in JupyterLab
+        run: |
+          "$RUNNER_TEMP/notebook-env/bin/python" tools/check_notebook_rendering.py \
+            notebooks/brush_linked_genome_tracks.ipynb \
+            --screenshot "$RUNNER_TEMP/notebook-rendering.png"
+      - uses: actions/upload-artifact@v7
+        if: always()
+        with:
+          name: notebook-rendering
+          path: ${{ runner.temp }}/notebook-rendering.png
+          if-no-files-found: ignore

genome_spy_python-0.3.0/CHANGELOG.md

@@ -0,0 +1,64 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.3.0] - 2026-09-09
+
+### Changed
+
+- **Dataset format change:** `p53_sequence_comparison` now contains 34 protein
+  sequences aligned with MAFFT L-INS-i, replacing the unaligned JSON tables.
+  Load the aligned FASTA with
+  `load_dataset("p53_sequence_comparison", as_format="text")`; code expecting
+  the previous mapping of prepared tables must be updated.
+- Updated the P53 gallery example to show the aligned sequences and calculate
+  conservation, gap-free fractions, and sequence logos in GenomeSpy.
+- Made the brush notebook build progressively from a simple p-value chart to
+  linked tracks, and added an effect-size zero baseline in the notebook and gallery.
+
+## [0.2.0] - 2026-09-09
+
+### Added
+
+- Python lists and tuples in `gs.expr()` for array expressions containing
+  values, parameters, and calculations.
+- A brush-linked notebook example with an Open in Colab link in the README.
+
+### Changed
+
+- Require AnyWidget 0.11.0 or newer to match the widget lifecycle API used for rendering.
+- Simplified the contributing guide and added brief notebook troubleshooting advice.
+
+### Fixed
+
+- PIK3CA lollipop connectors now reach the protein track.
+- Packaged datasets can be imported on Python 3.14.
+
+## [0.1.0] - 2026-09-09
+
+First public alpha release, targeting GenomeSpy Core 0.87.0.
+
+### Added
+
+- Declarative, schema-backed Python API for authoring GenomeSpy specifications.
+- Altair-style marks, encodings, transforms, parameters, conditions, and chart
+  composition.
+- Genomics-native locus channels, genome assemblies, genomic data sources, and
+  coordinated multi-view interactions.
+- Specification validation and serialization to dictionaries, JSON, and
+  standalone HTML.
+- Interactive notebook rendering in Jupyter, VS Code, and Marimo through
+  `anywidget`.
+- Arrow transport and live named-dataset updates for pandas, Polars, and
+  PyArrow tables.
+- Per-render GenomeSpy controls and embed options, including image export and
+  full-window display controls.
+- Packaged example datasets, documentation, tutorials, and an interactive
+  visualization gallery.
+
+[0.3.0]: https://github.com/genome-spy/genome-spy-python/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/genome-spy/genome-spy-python/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/genome-spy/genome-spy-python/releases/tag/v0.1.0

genome_spy_python-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,201 @@
+# Contributing to genome-spy-python
+
+Bug reports, documentation, examples, tests, and code contributions are welcome.
+
+## How to contribute
+
+Open an issue before starting a large change. Small fixes can go straight to a
+pull request.
+
+Explain what your pull request changes and why. Keep unrelated changes separate,
+and update tests and docs when behavior or the public API changes.
+
+## Development setup
+
+Use Python 3.11 or newer and [`uv`](https://docs.astral.sh/uv/). Install the
+development and docs dependencies from the repository root:
+
+```bash
+uv sync --group dev --group docs
+```
+
+Main directories:
+
+- `src/genome_spy/` — library code
+- `tests/` — tests
+- `docs/examples/` — gallery examples
+- `tools/` — code and documentation generators
+
+Install pre-commit hooks to check changes before committing:
+
+```bash
+uv run pre-commit install
+```
+
+## Coding practices
+
+### Python and typing
+
+Use type hints such as `list[T]`, `dict[K, V]`, and `X | Y` for public APIs.
+Add Google-style docstrings covering purpose, arguments, results, exceptions,
+and an example. Keep file, network, and notebook code separate from core logic.
+
+Keep changes small. Prefer generating APIs from the GenomeSpy schema over
+adding handwritten alternatives.
+
+### Formatting and linting
+
+Format and lint with [Ruff](https://docs.astral.sh/ruff/):
+
+```bash
+uv run ruff format .
+uv run ruff check .
+```
+
+Check types after changing library code:
+
+```bash
+uv run mypy src/
+```
+
+### Testing
+
+Add a focused test for each behavior change. Run the Python tests with:
+
+```bash
+uv run pytest tests/ -x
+```
+
+Run the widget's JavaScript tests with:
+
+```bash
+node --test tests/widget.test.mjs
+```
+
+Run the checks relevant to your changes before submitting a pull request.
+CI also checks generated code, docs, and the installed package.
+
+### Performance
+
+Avoid unnecessary data copies and large chart specifications. Measure performance
+before adding complexity to make code faster.
+
+## Generated schema and expression APIs
+
+Do not edit generated files in `src/genome_spy/schema/` by hand. The generator
+uses the GenomeSpy version in `pyproject.toml`, its schema, and the matching
+GenomeSpy and Vega expression documentation.
+
+Regenerate after changing that version or the generator:
+
+```bash
+uv run python tools/generate_schema_wrapper.py
+```
+
+This requires `npm` and internet access. Use `--package-dir` for a local package,
+or both `--genome-spy-expression-docs` and `--vega-expression-docs` for local
+expression docs.
+
+Then check the results:
+
+```bash
+uv run pytest tests/test_schema_codegen.py -x
+uv run ruff format src/genome_spy/schema src/genome_spy/helpers.py src/genome_spy/api.py src/genome_spy/__init__.py
+git diff --check
+```
+
+Review and commit the generated files alongside your changes. CI checks that
+regenerating them produces no differences.
+
+New transforms should be generated from the schema. Add overrides in
+`tools/generate_schema_wrapper.py` only for Python conventions the schema
+cannot describe.
+
+## Documentation
+
+### API reference
+
+After changing the public API, regenerate `docs/api.md` from `genome_spy.__all__`:
+
+```bash
+uv run python tools/generate_api_docs.py
+```
+
+Sphinx creates the individual pages in `docs/generated/`; do not commit them.
+
+### Build and preview
+
+Build the docs and check for warnings:
+
+```bash
+uv run sphinx-build -b html -W --keep-going docs docs/_build/html
+```
+
+Rerun the same command to rebuild changed pages and examples. Keep `docs/_build/`
+and avoid `-E` and `-a` for faster builds. Changes to shared code, data, build
+tools, or the lockfile regenerate all examples.
+
+To force example regeneration, delete the gallery cache (normally
+`docs/_build/html/.doctrees/genomespy-gallery`). Changes to remote data or files
+outside the tracked dependencies are not detected automatically.
+
+Preview locally:
+
+```bash
+cd docs/_build/html
+python3 -m http.server
+```
+
+Open <http://localhost:8000>. Interactive examples need internet access to load
+GenomeSpy.
+
+### Gallery examples
+
+Write examples in `docs/examples/`. Put explanations, data sources, any
+necessary disclaimers, and upstream links in an optional Markdown file with
+the same name.
+
+Focus on plotting, not data preparation: load prepared packaged datasets and
+prefer Python expressions such as `gs.datum.score > 0`. Remember that
+`.transform_*()` defines work that GenomeSpy runs in the browser, not Python.
+
+After editing an example, run:
+
+```bash
+uv run pytest tests/test_docs_gallery.py -q
+uv run sphinx-build -b html -W --keep-going docs docs/_build/html
+```
+
+Check the chart visually before updating its committed thumbnail.
+
+### Notebook rendering
+
+CI checks that the brush notebook renders in a fresh environment. Follow
+[the workflow](.github/workflows/ci.yml) for setup, then run with that
+environment's Python:
+
+```bash
+python -m playwright install chromium
+python tools/check_notebook_rendering.py notebooks/brush_linked_genome_tracks.ipynb --screenshot /tmp/notebook-rendering.png
+```
+
+## Commit guidelines
+
+Keep each commit focused on one change. Use
+[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/):
+
+```text
+feat(expressions): generate runtime helpers
+fix(widget): preserve zoom during data updates
+docs(gallery): add a sequence example
+```
+
+Do not rewrite shared history unless reviewers ask you to.
+
+## Community and communication
+
+Report wrapper bugs and request features in the
+[Python package issue tracker](https://github.com/genome-spy/genome-spy-python/issues).
+For GenomeSpy's grammar or renderer, use the upstream
+[discussions](https://github.com/genome-spy/genome-spy/discussions) or
+[issues](https://github.com/genome-spy/genome-spy/issues).

{genome_spy_python-0.1.0 → genome_spy_python-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: genome-spy-python
-Version: 0.1.0
+Version: 0.3.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/
@@ -23,7 +23,7 @@ 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.9.18
+Requires-Dist: anywidget>=0.11.0
 Requires-Dist: jsonschema>=4.26.0
 Requires-Dist: traitlets>=5.14.3
 Provides-Extra: arrow
@@ -36,6 +36,12 @@ Description-Content-Type: text/markdown
 
 <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

{genome_spy_python-0.1.0 → genome_spy_python-0.3.0}/README.md

@@ -4,6 +4,12 @@
 
 <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

{genome_spy_python-0.1.0 → genome_spy_python-0.3.0}/THIRD_PARTY_NOTICES.md

@@ -4,12 +4,11 @@
 
 `tcga_laml_combined_oncoplot.json.gz` contains prepared TCGA LAML tables from
 maftools revision `015a4cf8c69ba89a55a3fdcea911421509e9a198` (Anand Mayakonda,
-MIT). `p53_sequence_comparison.json.gz` contains p53 sequences and derived
-display tables from Plotly's datasets revision
-`0c447c47b757ad74edecab31f0d72f849d2e67c2` (Plotly Technologies Inc., MIT).
-Source file hashes are retained in the packaged data. The corresponding gallery
-pages describe processing. Copyright notices and terms are included in
-`LICENSES/GALLERY-DATA-MIT.txt`.
+MIT). `p53_sequence_comparison_aligned.fasta.gz` contains p53 sequences from
+Plotly's datasets revision `0c447c47b757ad74edecab31f0d72f849d2e67c2`
+(Plotly Technologies Inc., MIT), aligned with MAFFT v7.526 using L-INS-i. The
+corresponding gallery pages describe processing. Copyright notices and terms
+are included in `LICENSES/GALLERY-DATA-MIT.txt`.
 
 ## Code adapted from Vega-Altair
 

{genome_spy_python-0.1.0 → genome_spy_python-0.3.0}/docs/datasets.md

@@ -1,10 +1,10 @@
 # Example datasets
 
 The combined LAML oncoplot uses `load_dataset("tcga_laml_combined_oncoplot")`;
-the p53 sequence comparison uses `load_dataset("p53_sequence_comparison")`.
-Both return mappings of prepared chart tables, display domains, and source
-provenance. Their MIT-licensed sources, processing, and interpretation limits
-are described in the [combined oncoplot](gallery/combined_laml_oncoplot.md) and
+the p53 sequence comparison loads aligned FASTA text with
+`load_dataset("p53_sequence_comparison", as_format="text")`. Their
+MIT-licensed sources and processing are described in the
+[combined oncoplot](gallery/combined_laml_oncoplot.md) and
 [p53 comparison](gallery/p53_sequence_comparison.md) gallery pages.
 
 The package ships the tables that the [gallery](gallery/index.md) examples use,
@@ -30,7 +30,7 @@ for JSON files. Pass `as_format="text"` to get the raw file contents instead.
 | `tcga_laml_maf` | Somatic mutation calls for TCGA acute myeloid leukemia |
 | `tcga_laml_annotations` | Clinical annotations for those leukemia samples |
 | `tcga_laml_combined_oncoplot` | Prepared mutation, copy-number, clinical, pathway, VAF, and MutSig tables |
-| `p53_sequence_comparison` | 34 unaligned p53 sequences, padded residue tiles, consensus, identity, and coverage |
+| `p53_sequence_comparison` | 34 p53 protein sequences aligned with MAFFT L-INS-i, compressed FASTA |
 | `pyoncoprint_tcga` | Alteration matrix for TCGA lung adenocarcinoma samples |
 | `tcga_ov_gistic_scores` | GISTIC2 copy-number scores for TCGA ovarian tumors |
 | `tcga_ov_gistic_lesions` | GISTIC2 peak regions for the same cohort |

{genome_spy_python-0.1.0 → genome_spy_python-0.3.0}/docs/examples/brush_linked_genome_tracks.py

@@ -86,7 +86,7 @@ association_track = (
 )
 
 # Show effect sizes for the same range.
-effect_track = (
+effect_points = (
     gs.Chart()
     .mark_point(filled=True, size=24, opacity=0.78, color="#f58518")
     .encode(
@@ -96,10 +96,16 @@ effect_track = (
         y=gs.Y("EFFECTSIZE:Q").scale(domain=[-3, 3]).title("Effect size"),
         tooltip=["SNP:N", "GENE:N", "EFFECTSIZE:Q"],
     )
-    .properties(
-        name="effect-size",
-        height=95,
-    )
+)
+
+# Put a zero line behind the points to separate positive and negative effects.
+effect_baseline = (
+    gs.Chart([{"EFFECTSIZE": 0}])
+    .mark_rule(color="#888888", size=1, tooltip=None)
+    .encode(y=gs.Y("EFFECTSIZE:Q").scale(domain=[-3, 3]).title("Effect size"))
+)
+effect_track = (effect_baseline + effect_points).properties(
+    name="effect-size", height=95
 )
 
 # Add Z-scores as the third view of the selected range.

genome_spy_python-0.3.0/docs/examples/p53_sequence_comparison.md

@@ -0,0 +1,41 @@
+## What to notice
+
+Drag the overview at the bottom to choose the positions shown above. The
+summary tracks, sequence logo, and residue matrix stay aligned as the view
+moves. Move the pointer across the detail tracks to follow one position with
+the vertical ruler. Hover a tile for its accession and position. Zoom in to
+read letters.
+
+**Conservation** shows the fraction of non-gap sequences that share the most
+common amino acid at each alignment column. **Gap-free** shows
+the fraction of sequences containing a residue there. Keeping the two measures
+separate makes it clear whether a low score reflects disagreement or missing
+aligned residues. The sequence logo shows the full non-gap residue mixture,
+with larger letters for larger shares. The x-axis reports one-based alignment
+columns, not residue numbers in any individual protein.
+
+This adapts [Dash Bio AlignmentChart](https://dash.plotly.com/dash-bio/alignmentchart)
+with GenomeSpy rectangles, text, bars, a sequence logo, and a shared brush.
+
+:::{admonition} Data use and provenance
+:class: note
+
+The 34 UniProt-labelled p53 protein sequences come from the
+[Plotly FASTA](https://github.com/plotly/datasets/blob/0c447c47b757ad74edecab31f0d72f849d2e67c2/Dash_Bio/Genetic/alignment_viewer_p53.fasta)
+in Plotly's MIT-licensed datasets repository. They were aligned with MAFFT
+v7.526 using the L-INS-i strategy:
+`mafft-linsi p53.unaligned.fasta > p53.aligned.fasta`. The resulting alignment
+is packaged as `p53_sequence_comparison_aligned.fasta.gz`.
+:::
+
+## Python and GenomeSpy processing
+
+Python reads the packaged compressed FASTA, splits its 34 records, preserves
+the UniProt identifiers and headers, and verifies that every aligned sequence
+has the same length. GenomeSpy then flattens each sequence into residues in the
+browser and declaratively calculates gap-free fractions, non-gap conservation,
+and logo stacks. The Python API authors and serializes
+those transforms; GenomeSpy executes them while rendering and interacting with
+the visualization. For comparison, the
+[multiple sequence alignment example](multiple_sequence_alignment.md) sends
+FASTA directly to GenomeSpy and parses it in the browser-side dataflow.