genome-spy-python 0.5.0__tar.gz → 0.7.0__tar.gz

genome_spy_python-0.7.0/.agents/skills/commit/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: commit
+description: Commit repository changes in small thematic chunks using conventional commits and concise changelog staging.
+---
+
+# Commit workflow
+
+Prefer small, independently understandable commits. Keep unrelated user changes
+unstaged. Do not amend, rewrite history, revert, force-push, or add co-author
+trailers unless explicitly requested.
+
+## Inspect and commit
+
+1. Start with `git status --short` and `git diff --stat`.
+2. Group changes into thematic slices. Split separate features, fixes, refactors,
+   tooling/configuration, documentation, and unrelated test work when separable;
+   do not split mechanically by file.
+3. Keep implementation with its direct tests, API/schema changes with required
+   supporting code, and generated files with their source change.
+4. Read targeted diffs only when needed, including when grouping is unclear:
+   `git diff -- <files>`. Minimize token use; do not read the full diff or re-review
+   code by default.
+5. Stage one slice, check `git diff --cached --stat`, and commit with a conventional
+   message. Repeat for remaining slices.
+6. Finish with `git status --short`, update changelog staging once if needed, and
+   report commit hashes and remaining uncommitted files.
+
+## Commit messages
+
+Use `<type>(<scope>): <description>`. Common types: `feat`, `fix`, `refactor`,
+`perf`, `test`, `docs`, `chore`, `build`, and `ci`.
+
+```text
+feat(parser): add strand-aware bigwig loading
+fix(cache): invalidate stale entries
+refactor(pipeline): simplify track dispatch
+```
+
+## Changelog staging
+
+`CHANGELOG_STAGING.md` holds future release notes. Update it once per commit
+session only for release-relevant changes:
+
+- Read only the context needed.
+- Add concise bullets under `Added`, `Changed`, `Fixed`, `Removed`, or `Performance`.
+- Prefer one resulting-change bullet over one per commit; avoid duplicates.
+- Omit routine refactors, formatting, test-only work, and internal details unless
+  release-relevant.

genome_spy_python-0.7.0/.agents/skills/proper-code-review/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: proper-code-review
+description: Review code changes for correctness, simplicity, readability, maintainability, architectural fit, and meaningful system-level performance. Use when asked to review a diff, implementation, branch, or recent code changes.
+---
+
+# Code review
+
+Review as a senior engineer. Prioritize correctness and low lifecycle complexity:
+simple, readable, maintainable code that fits the repository and performs well for
+realistic workloads. Prefer a few high-confidence findings over exhaustive
+commentary; do not manufacture findings.
+
+Added complexity must provide a concrete benefit: correctness, meaningful reuse,
+change locality, real variation, necessary scalability, or material performance.
+Prefer local reasoning and localized changes. Reuse suitable repository concepts,
+avoid duplicated knowledge and parallel mechanisms, and reject speculative
+abstraction/extensibility. Judge performance across the system, not just locally.
+
+## Review method
+
+1. **Understand the change.** Read the diff first. Identify its problem, behavior
+   changes, affected interfaces, invariants, state, and architectural concepts.
+   Read only enough surrounding code to answer concrete questions, not the whole
+   repository. When relevant, inspect callers for compatibility, tests for intended
+   behavior/invariants, existing mechanisms before proposing new ones, analogous
+   implementations for duplication/fit, and broader execution paths for performance.
+2. **Verify hypotheses.** Check concerns against repository evidence when possible.
+   Locate duplicated representations, inspect callers before claiming breakage,
+   search for existing abstractions, and establish performance significance before
+   criticizing or recommending optimization. Do not present assumptions as facts.
+3. **Review correctness.** Look for concrete behavioral bugs/regressions, broken
+   invariants, invalid assumptions, relevant edge cases, unsafe mutations/state
+   transitions, error/resource lifecycle issues, concurrency problems, and
+   unintended compatibility changes. Passing tests are evidence, not proof.
+   Read [correctness](references/correctness.md) for deeper analysis.
+4. **Review design.** Consider simplicity (KISS), readability, maintainability,
+   cohesion, coupling, abstraction, change locality, blast radius, and fit together.
+   Check whether a simpler solution supports local understanding/change, whether
+   synchronized edits duplicate knowledge, whether machinery is unnecessary,
+   whether abstractions share real semantics, and whether scope is proportional.
+   Apply YAGNI: avoid cleverness or future machinery without concrete benefit.
+   Read [design](references/design.md) for deeper analysis.
+5. **Review performance.** Check algorithmic complexity, repeated expensive work,
+   I/O, memory/copying, serialization/data movement, CPU/GPU synchronization, and
+   realistic scaling. Judge end-to-end impact; reject meaningful complexity for
+   negligible local gains. Read [performance](references/performance.md) when relevant.
+6. **Validate findings.** Each problem must be concrete, consequential, supported
+   by evidence, and paired with a proportionate fix that reduces total complexity.
+   Remove speculative, cosmetic, generic, and low-value comments. No finding is
+   better than a weak finding.
+
+## Output
+
+Order findings by practical impact. For each, use:
+
+### `[Severity] Short problem statement`
+
+- **Location:** Smallest useful code region.
+- **Problem:** What is wrong.
+- **Impact:** Why it matters here.
+- **Recommendation:** Smallest reasonable fix.
+
+Severity:
+
+- **Critical:** Correctness, data loss, security, or severe failure.
+- **Important:** Substantial behavioral, architectural, maintainability,
+  performance, or scalability issue.
+- **Minor:** Worthwhile simplification or readability improvement.
+
+Combine findings with the same root cause and state uncertainty explicitly.
+Normally omit stylistic nits. Do not add generic best-practice advice, speculative
+future concerns, praise for unaffected code, or alternative architectures merely
+because they are possible. If none remain, say no significant issues were found.

{genome_spy_python-0.5.0 → genome_spy_python-0.7.0}/.gitignore

@@ -248,3 +248,6 @@ tools/__pycache__/
 scripts/*alphagenome*.py
 scripts/fetch_*_reference.py
 scripts/_fetch_reference.py
+
+# Local recording demos and working files
+/demos/

genome_spy_python-0.7.0/AGENTS.md

@@ -0,0 +1,65 @@
+# Repository instructions
+
+`genome-spy-python` wraps GenomeSpy in an idiomatic Python API, as Altair wraps
+Vega-Lite. Users author compatible specs, serialize JSON, and render in notebooks.
+Treat it as a library with a clean public API. Build the reusable Core grammar
+before app-specific concepts. Notebook rendering is first-class; prefer `anywidget`.
+
+## Layout
+
+| Path | Purpose |
+| --- | --- |
+| `src/genome_spy/` | Installable library |
+| `tests/` | pytest suite |
+| `scripts/` | Helpers run via `uv run` |
+| `plans/` | Plans, context, and implementation notes |
+| `material/` | Local reference documents; not committed |
+| `tmp/` | External reference code/repos; not committed |
+
+## Working rules
+
+- Think before coding: state assumptions and tradeoffs; push back when warranted.
+- Solve the current problem with minimal code. Avoid speculative features and
+  premature abstractions; duplicate a little first. If 200 lines could be 50,
+  rewrite them.
+- Make surgical changes: match existing style, remove imports/variables orphaned
+  by your edits, and leave unrelated code alone.
+- Set verifiable goals and give a brief plan for multi-step work.
+- Keep core logic pure Python; isolate I/O and integration at the edges.
+- Follow the linked [language, docstring, formatting, and gallery standards](docs/contributing/standards.md).
+  Read the relevant sections before Python or gallery edits; they are requirements.
+
+## Testing and handoff
+
+Use pytest. Add or update tests for behavior changes, with fixed seeds for random
+behavior. Keep tests small and focused on one behavior. Apply the "Suspicious
+Check": tighten any test that could pass for the wrong reason.
+
+Use `uv` for environments and dependencies. Before handoff, run targeted tests for
+changed behavior and lint. Format before finalizing non-trivial edits; type-check
+when public Python code changes. Report anything you could not validate locally.
+Ruff is the formatting/lint authority; fix issues rather than suppressing them by
+default.
+
+| Task | Command |
+| --- | --- |
+| Sync environment | `uv sync --dev` |
+| Run tests | `uv run pytest tests/ -x` |
+| Lint | `uv run ruff check .` |
+| Format | `uv run ruff format .` |
+| Type-check | `uv run mypy src/` |
+| Install hooks | `uv run pre-commit install` |
+
+Make small, thematic commits. Use conventional commits:
+`<type>(<scope>): <description>` when a scope helps. Do not rewrite history unless
+explicitly asked.
+
+## Plans and references
+
+| Document | Read when |
+| --- | --- |
+| `plans/implementation_plan.md` | Starting implementation; understand phases and open questions |
+| `plans/deferred.md` | Adding scope; avoid intentionally deferred work |
+| `plans/architecture.md` | Changing public API shape, schema strategy, or notebook integration |
+| `plans/tmp_repo_index.md` | Using `tmp/` repos for wrapper/widget design |
+| `plans/project_bootstrap.md` | Updating or extending the initial scaffold |

{genome_spy_python-0.5.0 → genome_spy_python-0.7.0}/CHANGELOG.md

@@ -5,6 +5,58 @@ 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.7.0] - 2026-10-20
+
+### Added
+
+- Typed facet and surround compositions, dendrogram transforms, secondary-offset
+  channels, and the remaining schema and expression additions from GenomeSpy 1.2.0.
+- Discoverable named field arguments on encoding constructors and named setters
+  for inline schema objects, with automatic public exports for generated channels.
+- A DepMap clustered heatmap gallery example adapted from the official GenomeSpy
+  surround specification.
+
+### Changed
+
+- Upgrade the bundled GenomeSpy Core, controls, Inspector, and schema to 1.2.0.
+- Use surround layouts in the PISA interaction matrix, UpSet mutations, PBMC
+  marker matrix, and PBMC cell heatmap examples.
+- Use named Python arguments and schema objects throughout gallery configuration,
+  and Python expression objects in the updated surround examples.
+
+### Fixed
+
+- Keep chart colors aligned with the documentation's selected light or dark theme.
+- Serialize named channel objects in shared surround-side encodings.
+- Preserve secondary-offset field and expression types according to the schema.
+- Support named resolution settings on unit charts and omit forbidden schema
+  properties from generated signatures.
+- Avoid redundant validation of nested schema objects when validation is explicitly
+  disabled, while retaining default validation checks.
+
+## [0.6.0] - 2026-10-01
+
+### Added
+
+- Add the prepared `airway_review` dataset for gene-review examples.
+
+### Changed
+
+- Upgrade GenomeSpy Core, controls, and Inspector to 1.0.0 and regenerate
+  the Python schema API, including configurable `displace2d` animation half-life.
+- Extend the sequence-editing notebook to support multi-base edits across the
+  displayed locus.
+- Improve interaction and PISA documentation, gallery expressions, and README
+  animations.
+
+### Fixed
+
+- Expose selection predicate classes through `gs` and support typed endpoint
+  projection setters, avoiding raw dictionaries in composed conditions.
+- Restrict sequence-logo and alignment-logo zoom to the position axis and share
+  one bottom alignment axis.
+- Render the ASCAT fitting example title as literal text.
+
 ## [0.5.0] - 2026-09-25
 
 ### Added
@@ -18,6 +70,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- Use browser-side `displace2d` label placement in the airway volcano and MA
+  gallery plots, with denser gene annotations and adaptive leader lines.
+
 - Reorganize the gallery into 13 categories, separating regulatory model
   interpretation, read alignments and RNA splicing, sequences and alignments,
   and interaction examples from the broader browser, annotation, and basic groups.
@@ -126,6 +181,8 @@ First public alpha release, targeting GenomeSpy Core 0.87.0.
 - Packaged example datasets, documentation, tutorials, and an interactive
   visualization gallery.
 
+[0.7.0]: https://github.com/genome-spy/genome-spy-python/compare/v0.6.0...v0.7.0
+[0.6.0]: https://github.com/genome-spy/genome-spy-python/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/genome-spy/genome-spy-python/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/genome-spy/genome-spy-python/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/genome-spy/genome-spy-python/compare/v0.2.0...v0.3.0

{genome_spy_python-0.5.0 → genome_spy_python-0.7.0}/CONTRIBUTING.md

@@ -90,6 +90,7 @@ Regenerate after changing that version or the generator:
 
 ```bash
 uv run python tools/generate_schema_wrapper.py
+uv run python tools/vendor_javascript.py
 ```
 
 This requires `npm` and internet access. Use `--package-dir` for a local package,
@@ -111,6 +112,25 @@ New transforms should be generated from the schema. Add overrides in
 `tools/generate_schema_wrapper.py` only for Python conventions the schema
 cannot describe.
 
+The generator emits explicit typed constructor and setter arguments from schema
+properties, including inline objects; avoid replacing these with untyped
+`**kwargs` or runtime-only signature patches. Channel imports and `__all__` are
+generated too. A new channel must appear in the public namespace automatically.
+New composition families still need renderable chart classes, serialization and
+round-trip support. The schema-derived root coverage test must fail until that
+support exists, rather than silently omitting unfamiliar roots.
+
+When adapting examples, use named schema objects or nested setters such as
+`gs.Scale().zoom(extent="data")`. Keep dictionaries for data records and authored
+names such as datasets, templates and parameter values. Test generated signatures
+and type-check a consumer example as well as validating its serialized JSON.
+
+Altair uses the same separation between a generated schema API and handwritten
+chart operations. Its [constructor and setter generator](https://github.com/vega/altair/blob/main/tools/schemapi/codegen.py)
+emits typed signatures and overloads; its [property-setter runtime](https://github.com/vega/altair/blob/main/altair/utils/schemapi.py)
+also supplies signatures for interactive completion. Prefer our existing explicit
+Python methods so completion, static checking and runtime calls agree.
+
 ## Documentation
 
 ### API reference

{genome_spy_python-0.5.0 → genome_spy_python-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: genome-spy-python
-Version: 0.5.0
+Version: 0.7.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/
@@ -33,6 +33,8 @@ Requires-Python: >=3.11
 Requires-Dist: anywidget>=0.11.0
 Requires-Dist: jsonschema>=4.26.0
 Requires-Dist: traitlets>=5.14.3
+Provides-Extra: anndata
+Requires-Dist: anndata>=0.11.0; extra == 'anndata'
 Provides-Extra: arrow
 Requires-Dist: pyarrow>=18.0.0; extra == 'arrow'
 Description-Content-Type: text/markdown
@@ -100,61 +102,130 @@ for supported tables and live updates.
 
 See the [getting-started guide](docs/getting-started.md) for the first example.
 
+## Agent skill
+
+The package bundles a visualization skill for Codex and Claude Code. Installation
+is explicit; importing or installing the Python package does not modify agent
+configuration. To install for both agents in the current project:
+
+```bash
+genome-spy-install-skills
+```
+
+Use `--agent codex` or `--agent claude` to select one agent, `--project PATH` for
+another project, or `--user` for personal installation. Existing modified skills
+are preserved unless `--force` is supplied. See
+[installation and update details](docs/agents/skill-distribution.md).
+
 ## Examples
 
+A zoomable Manhattan plot using the bundled HapMap data (requires `pandas`):
+
 ```python
 import genome_spy as gs
+from genome_spy.datasets import load_dataset
 
 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)
+    # Load data.
+    gs.Chart(load_dataset("hapmap_gwas"))
+    # Format chromosome names.
+    .transform_formula(expr="datum.CHR == 23 ? 'chrX' : 'chr' + datum.CHR", as_="chrom")
+    # Calculate −log10 p.
+    .transform_formula(expr="-log(datum.P) / log(10)", as_="neglogp")
+    # Draw variants.
+    .mark_point(size=12)
+    # Set positions and colors.
     .encode(
-        x="x:Q",
-        y="y:Q",
-        color="group:N",
+        x=gs.Locus("chrom", "BP").scale(assembly="hg18"),
+        y=gs.Y("neglogp:Q").title("−log10 p"),
+        color=gs.Color("CHR:N").scale(range=["#5b8fd6", "#8f98a3"]).legend(None),
     )
 )
-
 chart
 ```
 
-GenomeSpy also has locus-scaled axes for genomic coordinates. This small
-example renders intervals along a region of chromosome 1:
+![Manhattan plot zooming from the whole genome into an association peak](https://raw.githubusercontent.com/genome-spy/genome-spy-python/a6c724f48d94f86d8d0a8c3200549d7560a88a3c/docs/_static/readme-manhattan.webp)
+
+[Explore the full example and data provenance](https://genomespy.app/genome-spy-python/gallery/manhattan_plot.html).
+
+A sequence logo and aligned sequences with shared horizontal zoom:
 
 ```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"},
-]
-
+logo = (
+    gs.Chart()
+    # Count bases at each position.
+    .transform_aggregate(groupby=["pos", "sequence"])
+    # Handle gaps.
+    .transform_formula(expr="datum.sequence == '-' ? null : datum.sequence", as_="base")
+    # Stack bases by information content.
+    .transform_stack(
+        field="count",
+        groupby=["pos"],
+        offset="information",
+        baseField="base",
+        as_=["y0", "y1"],
+    )
+    # Draw logo letters.
+    .mark_text(logoLetters=True, fitToBand=True, fontWeight="bold")
+    # Set stack bounds.
+    .encode(
+        y=gs.Y("y0:Q").scale(domain=[0, 2], zoom=False).title("Bits"),
+        y2="y1:Q",
+        text="base:N",
+    )
+    .properties(height=100)
+)
+# Create sequence rows.
+rows = gs.Chart().encode(y=gs.Y("identifier:N").scale(zoom=False).axis(None))
+# Add base labels.
+letters = rows.mark_text(size=11, fitToBand=True, opacity=0.7).encode(
+    text="sequence:N", color=gs.value("black")
+)
+# Layer tiles and labels.
+sequences = (rows.mark_rect() + letters).properties(
+    height=gs.step(16), viewportHeight=160
+)
 chart = (
-    gs.Chart(intervals)
-    .mark_rect()
+    # Combine panels.
+    (logo & sequences)
+    # Load data.
+    .properties(
+        data=gs.Data(
+            url="https://data.genomespy.app/sample-data/16SRNA_Deino_87seq.aln",
+            format=gs.data_format(type="fasta"),
+        )
+    )
+    # Split sequences into bases.
+    .transform_flatten_sequence()
+    # Set positions and colors.
     .encode(
-        x=gs.Locus("chrom", "start"),
-        x2="end:Q",
-        y="name:N",
-        color="name:N",
+        x=gs.X("pos:I").scale(domain=[190, 310], zoom=True).title(None),
+        color=gs.Color("sequence:N")
+        .scale(
+            domain=list("ACTGN-"),
+            range=["#4FBF45", "#4D96E8", "#E85F78", "#E8B322", "#BDBDBD", "#f5f5f5"],
+        )
+        .legend(None),
     )
+    # Share zoom and colors.
+    .resolve_scale(x="shared", color="shared")
+    .resolve_axis(x="shared")
 )
-
 chart
 ```
 
+![Sequence logo and aligned sequences zooming across multiple regions](https://raw.githubusercontent.com/genome-spy/genome-spy-python/main/docs/_static/readme-sequence-logo.webp?v=4cd9f86a0d31)
+
 Charts can be serialized to a portable GenomeSpy specification or standalone
 HTML:
 
 ```python
+# Export JSON.
 chart.to_json()
-chart.save("intervals.html")
+# Save HTML.
+chart.save("chart.html")
 ```
 
 ### Update data without recreating the chart
@@ -165,12 +236,15 @@ existing GenomeSpy instance, so view state such as zoom is preserved.
 
 ```python
 chart = (
+    # Create an empty chart.
     gs.Chart(data={"name": "table"}, datasets={"table": []})
     .mark_point()
     .encode(x="x:Q", y="y:Q")
 )
+# Show widget.
 view = chart.widget()
 
+# Update data.
 view.set_dataset("table", updated_dataframe)
 ```
 

{genome_spy_python-0.5.0 → genome_spy_python-0.7.0}/README.md

@@ -61,61 +61,130 @@ for supported tables and live updates.
 
 See the [getting-started guide](docs/getting-started.md) for the first example.
 
+## Agent skill
+
+The package bundles a visualization skill for Codex and Claude Code. Installation
+is explicit; importing or installing the Python package does not modify agent
+configuration. To install for both agents in the current project:
+
+```bash
+genome-spy-install-skills
+```
+
+Use `--agent codex` or `--agent claude` to select one agent, `--project PATH` for
+another project, or `--user` for personal installation. Existing modified skills
+are preserved unless `--force` is supplied. See
+[installation and update details](docs/agents/skill-distribution.md).
+
 ## Examples
 
+A zoomable Manhattan plot using the bundled HapMap data (requires `pandas`):
+
 ```python
 import genome_spy as gs
+from genome_spy.datasets import load_dataset
 
 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)
+    # Load data.
+    gs.Chart(load_dataset("hapmap_gwas"))
+    # Format chromosome names.
+    .transform_formula(expr="datum.CHR == 23 ? 'chrX' : 'chr' + datum.CHR", as_="chrom")
+    # Calculate −log10 p.
+    .transform_formula(expr="-log(datum.P) / log(10)", as_="neglogp")
+    # Draw variants.
+    .mark_point(size=12)
+    # Set positions and colors.
     .encode(
-        x="x:Q",
-        y="y:Q",
-        color="group:N",
+        x=gs.Locus("chrom", "BP").scale(assembly="hg18"),
+        y=gs.Y("neglogp:Q").title("−log10 p"),
+        color=gs.Color("CHR:N").scale(range=["#5b8fd6", "#8f98a3"]).legend(None),
     )
 )
-
 chart
 ```
 
-GenomeSpy also has locus-scaled axes for genomic coordinates. This small
-example renders intervals along a region of chromosome 1:
+![Manhattan plot zooming from the whole genome into an association peak](https://raw.githubusercontent.com/genome-spy/genome-spy-python/a6c724f48d94f86d8d0a8c3200549d7560a88a3c/docs/_static/readme-manhattan.webp)
+
+[Explore the full example and data provenance](https://genomespy.app/genome-spy-python/gallery/manhattan_plot.html).
+
+A sequence logo and aligned sequences with shared horizontal zoom:
 
 ```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"},
-]
-
+logo = (
+    gs.Chart()
+    # Count bases at each position.
+    .transform_aggregate(groupby=["pos", "sequence"])
+    # Handle gaps.
+    .transform_formula(expr="datum.sequence == '-' ? null : datum.sequence", as_="base")
+    # Stack bases by information content.
+    .transform_stack(
+        field="count",
+        groupby=["pos"],
+        offset="information",
+        baseField="base",
+        as_=["y0", "y1"],
+    )
+    # Draw logo letters.
+    .mark_text(logoLetters=True, fitToBand=True, fontWeight="bold")
+    # Set stack bounds.
+    .encode(
+        y=gs.Y("y0:Q").scale(domain=[0, 2], zoom=False).title("Bits"),
+        y2="y1:Q",
+        text="base:N",
+    )
+    .properties(height=100)
+)
+# Create sequence rows.
+rows = gs.Chart().encode(y=gs.Y("identifier:N").scale(zoom=False).axis(None))
+# Add base labels.
+letters = rows.mark_text(size=11, fitToBand=True, opacity=0.7).encode(
+    text="sequence:N", color=gs.value("black")
+)
+# Layer tiles and labels.
+sequences = (rows.mark_rect() + letters).properties(
+    height=gs.step(16), viewportHeight=160
+)
 chart = (
-    gs.Chart(intervals)
-    .mark_rect()
+    # Combine panels.
+    (logo & sequences)
+    # Load data.
+    .properties(
+        data=gs.Data(
+            url="https://data.genomespy.app/sample-data/16SRNA_Deino_87seq.aln",
+            format=gs.data_format(type="fasta"),
+        )
+    )
+    # Split sequences into bases.
+    .transform_flatten_sequence()
+    # Set positions and colors.
     .encode(
-        x=gs.Locus("chrom", "start"),
-        x2="end:Q",
-        y="name:N",
-        color="name:N",
+        x=gs.X("pos:I").scale(domain=[190, 310], zoom=True).title(None),
+        color=gs.Color("sequence:N")
+        .scale(
+            domain=list("ACTGN-"),
+            range=["#4FBF45", "#4D96E8", "#E85F78", "#E8B322", "#BDBDBD", "#f5f5f5"],
+        )
+        .legend(None),
     )
+    # Share zoom and colors.
+    .resolve_scale(x="shared", color="shared")
+    .resolve_axis(x="shared")
 )
-
 chart
 ```
 
+![Sequence logo and aligned sequences zooming across multiple regions](https://raw.githubusercontent.com/genome-spy/genome-spy-python/main/docs/_static/readme-sequence-logo.webp?v=4cd9f86a0d31)
+
 Charts can be serialized to a portable GenomeSpy specification or standalone
 HTML:
 
 ```python
+# Export JSON.
 chart.to_json()
-chart.save("intervals.html")
+# Save HTML.
+chart.save("chart.html")
 ```
 
 ### Update data without recreating the chart
@@ -126,12 +195,15 @@ existing GenomeSpy instance, so view state such as zoom is preserved.
 
 ```python
 chart = (
+    # Create an empty chart.
     gs.Chart(data={"name": "table"}, datasets={"table": []})
     .mark_point()
     .encode(x="x:Q", y="y:Q")
 )
+# Show widget.
 view = chart.widget()
 
+# Update data.
 view.set_dataset("table", updated_dataframe)
 ```