# genome-spy-python

> Agent documentation for authoring, validating, and delivering GenomeSpy charts.

Read the relevant pages only. These are plain Markdown, separate from the human
HTML documentation. Start with a relevant gallery example and adapt its working
data, encodings, composition, and rendering path before adding workarounds.
Check installed signatures if an option is unavailable.

## Start here

- [Quickstart](https://genomespy.app/genome-spy-python/agents/quickstart.md): Create, validate, and deliver a table chart with a complete runnable example.
- [Install the agent skill](https://genomespy.app/genome-spy-python/agents/skill-distribution.md): Install for Codex or Claude Code, choose scope, and preserve local edits.
- [Visualization skill](https://genomespy.app/genome-spy-python/agents/skill.md): Portable authoring workflow, verification requirements, and recovery paths.
- [Reuse gallery examples](https://genomespy.app/genome-spy-python/agents/gallery.md): Find working Python examples by use case and adapt their maintained patterns.

## Author charts

- [Data inputs](https://genomespy.app/genome-spy-python/agents/data.md): Records, dataframes, URLs and AnnData; measurement sources, selection versus filtering, and preparation limits.
- [Encodings and composition](https://genomespy.app/genome-spy-python/agents/encodings.md): Typed fields, repeated labels with stable position IDs, panels, collected guides and browser transforms.
- [Scales, axes, and legends](https://genomespy.app/genome-spy-python/agents/scales-axes-legends.md): Fixed domains, explicit axis direction, numeric color bins, native color/size guides and guide configuration.
- [Python API signatures](https://genomespy.app/genome-spy-python/agents/api.md): Generated signatures for core chart authoring, channels, guides, and output; intentionally a focused subset.

## API details

- [Chart authoring signatures](https://genomespy.app/genome-spy-python/agents/api-chart.md): Construct charts and marks, encode fields, configure views, and resolve composition scales.
- [Encoding and guide signatures](https://genomespy.app/genome-spy-python/agents/api-encodings.md): Field/channel constructors, scale and axis methods, and legend options.
- [Validation and output signatures](https://genomespy.app/genome-spy-python/agents/api-output.md): Validate specs, save files, display charts, and retain notebook widgets.

## Deliver and verify

- [Notebooks and export](https://genomespy.app/genome-spy-python/agents/rendering.md): Notebook and file-export examples, installed-signature inspection, and a recovery checklist.
- [Table charts and reference fidelity](https://genomespy.app/genome-spy-python/agents/table-chart.md): Runnable chart, equal units, marker size/DPI conversion and registered plot-area capture checks.
- [Grouped summaries and matrices](https://genomespy.app/genome-spy-python/agents/grouped-charts.md): Native summary-point and matrix examples; normalization, ordering, and capability limits.

## User guide

- [Label points and genomic intervals](https://genomespy.app/genome-spy-python/user-guide/annotations.md): Labels and leader lines make the important parts of a chart easier to find. In this tutorial we combine ordinary text, rule, and interval marks with your main visualization to showcase how datapoints or intervals can be annotated.
- [Charts and marks](https://genomespy.app/genome-spy-python/user-guide/charts.md): A genome_spy.Chart combines data, one geometric shape called a **mark**, and encodings that control where and how those marks are drawn. A chart with one mark type is also called a *unit view*.
- [Composition](https://genomespy.app/genome-spy-python/user-guide/composition.md): Composition combines complete views into a larger visualization. GenomeSpy uses three concise operators for the most common layouts:
- [Configuration](https://genomespy.app/genome-spy-python/user-guide/configuration.md): GenomeSpy exposes appearance and layout at several levels. Choosing the narrowest appropriate level keeps a specification predictable:
- [Connect chart interactions to Python](https://genomespy.app/genome-spy-python/user-guide/connect-python.md): # Connect chart interactions to Python
- [Data and chart inputs](https://genomespy.app/genome-spy-python/user-guide/data.md): GenomeSpy works with tabular data: rows are **records**, and columns are named **fields**. Encodings refer to those field names when they assign values to position, color, size, or another visual channel.
- [Display controls and embed options](https://genomespy.app/genome-spy-python/user-guide/display-controls.md): # Display controls and embed options
- [Use chart interactions in Python](https://genomespy.app/genome-spy-python/user-guide/embed-api.md): Select a region in a chart and use its coordinates in your Python analysis. You can also send results back to the chart—for example, to show saved regions on an annotation track.
- [Encodings and channels](https://genomespy.app/genome-spy-python/user-guide/encodings.md): An **encoding** maps data to a visible property. The property being controlled is called a **channel**: `x` controls horizontal position, `color` controls color, and `size` controls mark size. The field supplies the values, while its data type tells GenomeSpy how those values should be interpreted.
- [Expressions](https://genomespy.app/genome-spy-python/user-guide/expressions.md): An **expression** is a small calculation, such as doubling a score or checking whether it is above a cutoff. You write it in Python; GenomeSpy works out the answer in the browser.
- [Build linked genome tracks](https://genomespy.app/genome-spy-python/user-guide/genome-browser-layouts.md): A genome browser is a set of aligned tracks that describe the same genomic region. The tracks share one horizontal locus scale, so a zoom or pan applies to all of them, but each track keeps the vertical scale appropriate for its own measurements.
- [Chromosomes and locus scales](https://genomespy.app/genome-spy-python/user-guide/genomic-axes.md): A genomic position has two parts: a chromosome or other **contig**, and a position within that contig. GenomeSpy uses an assembly's contig sizes and order to concatenate those coordinates into one continuous visual axis.
- [Large and indexed genomic data](https://genomespy.app/genome-spy-python/user-guide/genomic-data.md): A genome-wide signal or alignment file can contain far more rows than a browser should download at once. GenomeSpy's **lazy data sources** request only the part needed for the visible genomic region. Zooming or panning changes that region and causes the source to request another indexed slice.
- [Import remote view specifications](https://genomespy.app/genome-spy-python/user-guide/importing-specifications.md): genome_spy.import_view adds a view whose GenomeSpy JSON specification lives in another file. This is useful for composing published, reusable tracks or for splitting a large visualization into independently maintained specifications. The Python package records the import definition; GenomeSpy fetches the remote JSON in the browser when the chart is rendered.
- [User guide](https://genomespy.app/genome-spy-python/user-guide/index.md): The user guide begins with the general visualization grammar and then adds GenomeSpy's composition and genomic concepts.
- [Parameters and interaction](https://genomespy.app/genome-spy-python/user-guide/interaction.md): Interaction lets users explore a chart by moving a slider, selecting points, or zooming into a region. A **parameter** stores a value that can change, such as a slider's cutoff or the points a user selects. Create it in Python, attach it to a chart, and use it to control what the chart shows.
- [Charts in notebooks](https://genomespy.app/genome-spy-python/user-guide/notebooks.md): Create a chart in Python and display it in JupyterLab, Jupyter Notebook, VS Code notebooks, or Marimo. You can explore it with the mouse without writing any JavaScript.
- [Scales, axes, and legends](https://genomespy.app/genome-spy-python/user-guide/scales-axes-legends.md): An encoding says which data field controls a visual channel. A **scale** performs the conversion from data values to visible values. **Axes** and **legends** are guides that explain the conversion to the user.
- [Save, export, and share charts](https://genomespy.app/genome-spy-python/user-guide/serialization.md): Save an interactive chart as an HTML file, or download a picture of the current view. The examples below assume you have already created a `chart`; see Getting started for a complete first example.
- [Transforms](https://genomespy.app/genome-spy-python/user-guide/transforms.md): A **transform** changes the rows that flow from a chart's data source to its marks. Transforms can remove rows, add fields, summarize groups, or perform more specialized visualization operations. They run in the browser before the marks are drawn.
- [Using and sharing charts](https://genomespy.app/genome-spy-python/user-guide/using-charts.md): The previous sections covered chart definitions and interactions. This section covers displaying those charts, exporting them, and connecting their interactions to Python code.
- [Annotate genomic intervals](https://genomespy.app/genome-spy-python/user-guide/workflows/annotate-intervals.md): Brush the chart, enter a name, and click **Save annotation**. New marks appear in **Your annotations**. Click **Download BED** to keep them.
- [Edit a sequence](https://genomespy.app/genome-spy-python/user-guide/workflows/edit-sequence.md): Click an A/C/G/T letter to choose the nucleotide at that position. Chosen bases use their nucleotide colors; the other letters fade to gray. The reference and edited sequence use the same colors. Changes from the reference are outlined in the grid.
- [Interactive workflows](https://genomespy.app/genome-spy-python/user-guide/workflows/index.md): Try these demos in your browser, or use the results in Python with a notebook.
- [Pick individual genes](https://genomespy.app/genome-spy-python/user-guide/workflows/pick-genes.md): Click a point to select a gene. **Shift-click** adds or removes genes. Scroll to zoom and drag to pan; points grow as you zoom in. The table shows the selected records; download them as CSV.
- [Select genes for follow-up](https://genomespy.app/genome-spy-python/user-guide/workflows/select-genes.md): Scroll to zoom and drag to brush a region, then click **Download selected genes** to save a CSV. Points grow as you zoom in.

## Gallery: Association plots

- [Manhattan plot](https://genomespy.app/genome-spy-python/gallery/manhattan_plot.md): Genome-wide association hits on a locus-aware chromosome axis. Alternating chromosome colors separate the blocks, dashed rules mark significance thresholds, and the strongest peaks are outlined for emphasis.
- [Brush-linked genome tracks](https://genomespy.app/genome-spy-python/gallery/brush_linked_genome_tracks.md): A whole-genome overview brush controls three synchronized association tracks. The overview keeps its own scale while the detail views share a selection-driven locus domain.

## Gallery: Differential analysis

- [Volcano plot](https://genomespy.app/genome-spy-python/gallery/airway_volcano_plot.md): Log2 fold change against −log10 p-value, with color separating upregulated, downregulated, and background genes. Dashed guide lines mark the significance and fold-change cutoffs.
- [MA plot](https://genomespy.app/genome-spy-python/gallery/airway_ma_plot.md): Mean expression against log2 fold change, with color highlighting genes that pass a simple significance cutoff. This is the classic expression-change view for spotting strong shifts across the dynamic range.
- [Volcano plot](https://genomespy.app/genome-spy-python/gallery/volcano_plot.md): Effect size against −log10 p-value, with color highlighting points that clear both an effect-size and a significance cutoff.

## Gallery: Single-cell expression

- [PBMC UMAP](https://genomespy.app/genome-spy-python/gallery/pbmc_umap.md): Explore cell types in a zoomable single-cell embedding.
- [PBMC UMAP panels](https://genomespy.app/genome-spy-python/gallery/pbmc_umap_genes.md): Compare six marker genes, total counts, and cell types on one embedding.
- [PBMC marker matrix](https://genomespy.app/genome-spy-python/gallery/pbmc_marker_matrix.md): Compare mean marker expression across eight cell types, with aligned cell counts.
- [PBMC cell heatmap](https://genomespy.app/genome-spy-python/gallery/pbmc_cell_heatmap.md): Zoom through individual cells to inspect the same twelve markers within each cell type.
- [PBMC expression tracks](https://genomespy.app/genome-spy-python/gallery/pbmc_expression_tracks.md): Inspect individual marker values in twelve tracks that zoom together.

## Gallery: Regulatory model interpretation

- [Dynseq binding-QTL tracks](https://genomespy.app/genome-spy-python/gallery/dynseq_bqtl.md): Sequence-logo tracks compare reference and alternate SPI1 contribution scores over the same base-resolution locus.
- [Adaptive dynseq binding-QTL tracks](https://genomespy.app/genome-spy-python/gallery/dynseq_adaptive_bqtl.md): Reference and alternate SPI1 contribution scores switch from sequence-logo letters to labeled bars as the reader zooms in.
- [PISA squid plot](https://genomespy.app/genome-spy-python/gallery/pisa_squid.md): Brush input and output positions to explore base-to-base effects around the Drosophila sog enhancer, with accessibility, contribution, and motif tracks.
- [PISA interaction matrix](https://genomespy.app/genome-spy-python/gallery/pisa_interaction_matrix.md): Explore the signed effect of each input base on each ATAC-seq output position around the Drosophila sog enhancer, with synchronized marginal tracks.

## Gallery: Multi-track genome browsers

- [Genome tracks with gene annotations](https://genomespy.app/genome-spy-python/gallery/genome_tracks.md): A browser-style locus view with a quantitative signal track stacked above a gene-annotation track. The lower panel combines transcript bodies, exons, labels, and strand cues so the annotations stay readable while zooming.
- [Stacked genome browser tracks](https://genomespy.app/genome-spy-python/gallery/stacked_genome_browser.md): Several lazy hg38 resources share one zoomable genomic axis: signal tracks, regulatory intervals, sequence, and RefSeq gene annotations.
- [Composing a genome browser](https://genomespy.app/genome-spy-python/gallery/composing_genome_browser.md): Independent cytoband, six-frame translation, BAM alignment, and RefSeq views are imported by URL and aligned under a parent-owned genomic scale and axis.

## Gallery: Read alignments and RNA splicing

- [ONT direct-RNA coverage and read alignments along RNF7](https://genomespy.app/genome-spy-python/gallery/rnf7_direct_rna.md): An IGV-like browser connects condition-specific coverage and m6A site evidence to reference sequence, alignment edits, and the individual wild-type and METTL3-knockout molecules.
- [Sashimi plot](https://genomespy.app/genome-spy-python/gallery/sashimi_plot.md): A splice-junction view with coverage in the background and arc links connecting junction endpoints. Labels on the arcs show junction support while the signal track keeps local expression context visible.
- [BAM coverage and read pileup](https://genomespy.app/genome-spy-python/gallery/bam_read_pileup.md): Load a genomic window from an indexed BAM file and stack its reads by strand.
- [BAM read alignments](https://genomespy.app/genome-spy-python/gallery/bam_read_alignments.md): An IGV-like alignment view with depth, mismatch, CIGAR, and read-level tracks.

## Gallery: Genome annotations

- [Chromosome ideogram](https://genomespy.app/genome-spy-python/gallery/cytobands.md): A whole-genome cytoband ideogram with band labels and chromosome separators. Intervals are colored by stain to show familiar light, dark, centromeric, and other structural band types.
- [GFF3 gene annotations](https://genomespy.app/genome-spy-python/gallery/gff3_gene_annotations.md): A browser-style gene-annotation track built from a GFF3 source. Layered marks separate transcript bodies, exon structure, UTRs, and transcript labels within one shared locus view.
- [RefSeq genes with scored labels](https://genomespy.app/genome-spy-python/gallery/refseq_scored_genes.md): Transcript bodies and exons fade in at detailed zoom levels while a scored label transform keeps the most useful RefSeq gene symbols visible.
- [BigBed cCRE track](https://genomespy.app/genome-spy-python/gallery/bigbed_ccre_track.md): A regulatory-annotation track built from BigBed intervals. Candidate elements are drawn as locus spans and colored by their annotation class.

## Gallery: Sequences, alignments, and logos

- [Indexed FASTA six-frame translation](https://genomespy.app/genome-spy-python/gallery/six_frame_translation.md): The visible hg38 reference sequence is translated in all three reading frames on both strands and kept aligned with a base-level reference track.
- [Indexed FASTA sequence track](https://genomespy.app/genome-spy-python/gallery/indexed_fasta_sequence.md): A base-resolution sequence view for a small genomic window. Each position is drawn as both a colored tile and a base label on the locus axis.
- [Multiple sequence alignment](https://genomespy.app/genome-spy-python/gallery/multiple_sequence_alignment.md): An alignment view combines a sequence-logo summary with a zoomable row for each aligned sequence.
- [P53 multiple-sequence alignment with an overview brush](https://genomespy.app/genome-spy-python/gallery/p53_sequence_comparison.md): Explore a MAFFT alignment of the p53 proteins used by Dash Bio, with residue tiles, a sequence logo, position agreement, gap prevalence, and a linked overview.
- [Sequence logo](https://genomespy.app/genome-spy-python/gallery/sequence_logo.md): Letter marks are stacked by information content to show a compact sequence motif summary.

## Gallery: Mutation position plots

- [Lollipop plot](https://genomespy.app/genome-spy-python/gallery/needle_plot.md): Mutation counts aggregated by amino-acid position and drawn above a protein domain map. Color encodes the dominant mutation class at each site, making hotspots easy to spot.
- [PIK3CA mutation lollipop plot](https://genomespy.app/genome-spy-python/gallery/pik3ca_tcga_brca_lollipop.md): Recurrent TCGA-BRCA PIK3CA mutations are displaced just enough to keep dense hotspots readable while connectors retain their true protein positions.
- [Rainfall plot](https://genomespy.app/genome-spy-python/gallery/rainfall_plot.md): Inter-mutation distance across the genome for a single tumor sample. Point color encodes substitution class and arrow annotations call out compact kataegis-like clusters.
- [ClinVar variants track](https://genomespy.app/genome-spy-python/gallery/clinvar_variants.md): A categorical variant track with stems and points for germline classification. Colors encode pathogenicity classes across a focused genomic locus.

## Gallery: Oncoprints and cohort summaries

- [Oncoplot](https://genomespy.app/genome-spy-python/gallery/oncoprint.md): A cohort-level alteration matrix with per-sample burden bars above, recurrently altered genes in the center, and per-gene summary bars at the side.
- [LAML oncoplot with clinical and pathway annotations](https://genomespy.app/genome-spy-python/gallery/combined_laml_oncoplot.md): Combine alterations, pathway summaries, clinical annotations, and gene-level statistics for the 200 patients in the maftools TCGA LAML example.
- [LUAD oncoprint](https://genomespy.app/genome-spy-python/gallery/luad_oncoprint.md): A large cohort oncoprint adapted from the `pyoncoprint` TCGA LUAD notebook. The shared sample axis ties together top burden and clinical tracks, the main alteration matrix, and lower quantitative heatmaps.

## Gallery: Copy-number plots

- [Copy-number profile](https://genomespy.app/genome-spy-python/gallery/copy_number.md): Allele-specific copy-number segments drawn across the genome on a locus axis. Segment height shows total copy number, while color highlights loss of heterozygosity.
- [ASCAT copy-number segmentation](https://genomespy.app/genome-spy-python/gallery/ascat_copy_number.md): Aligned allele-specific copy-number, LogR, and B-allele-frequency tracks show segment estimates over raw probe values for simulated sample S96.
- [Interactive ASCAT purity/ploidy fitting](https://genomespy.app/genome-spy-python/gallery/ascat_fitting.md): A parameterized sunrise plot evaluates integer-copy-number fits while linked tracks show how the selected purity, ploidy, and LogR decompaction affect the rounded allele-specific solution.
- [HCC1954 structural variants and copy number](https://genomespy.app/genome-spy-python/gallery/hcc1954_sv_cnv.md): Somatic Severus structural-variant arcs are aligned with Wakhan total copy-number segments for the highly rearranged HCC1954 breast-cancer cell line.
- [TCGA ovarian cancer GISTIC landscape](https://genomespy.app/genome-spy-python/gallery/tcga_ov_gistic.md): Recurrent copy-number scores and their amplification and deletion peaks are shown over a shared hg19 genomic axis.

## Gallery: Set intersections

- [Set intersections with an UpSet plot](https://genomespy.app/genome-spy-python/gallery/upset_mutations.md): Aligned bars and a membership matrix show exact mutation intersections among five genes in the UpSetR glioblastoma cohort, with linked row highlighting.

## Gallery: Basic charts and composition

- [Point mark](https://genomespy.app/genome-spy-python/gallery/point_mark.md): An interactive point chart with a quantitative color channel and a smooth relationship generated by GenomeSpy transforms.
- [Rect heatmap](https://genomespy.app/genome-spy-python/gallery/rect_heatmap.md): A dense quantitative grid rendered with rect marks and a continuous color scale.
- [Horizontal stacked bars](https://genomespy.app/genome-spy-python/gallery/stacked_bar.md): Compare barley yields by variety, with each growing site shown as a segment.
- [Layered lollipop plot](https://genomespy.app/genome-spy-python/gallery/layered_lollipop.md): Combine rules and point marks to show positive and negative values.
- [Layered charts with independent scales](https://genomespy.app/genome-spy-python/gallery/independent_scales.md): Overlay probe measurements and segment means with separate vertical axes.
- [Point shapes and styles](https://genomespy.app/genome-spy-python/gallery/point_styles.md): Vary point shape, fill, size, outline, and rotation in a small grid.
- [Positive and negative bars](https://genomespy.app/genome-spy-python/gallery/diverging_bars.md): Draw bars from zero and color them according to their sign.
- [Ranged rule mark](https://genomespy.app/genome-spy-python/gallery/ranged_rule.md): Intervals are represented by rules with start and end encodings, a useful pattern for compact feature and confidence-interval tracks.
- [Coverage and interval pileup](https://genomespy.app/genome-spy-python/gallery/coverage_pileup.md): Show how overlapping intervals produce a coverage profile.
- [Link mark](https://genomespy.app/genome-spy-python/gallery/link_mark.md): Dome-shaped links connect paired positions and demonstrate interval-style relationships in a compact view.
- [Vertical concatenation](https://genomespy.app/genome-spy-python/gallery/vertical_concat.md): Two related views are stacked vertically while sharing the same input table.

## Gallery: Interaction and exploration

- [Heatmap with zoomable values](https://genomespy.app/genome-spy-python/gallery/heatmap_with_text.md): Zoom into a patterned heatmap to reveal the value of each cell.
- [Points that grow when zooming](https://genomespy.app/genome-spy-python/gallery/geometric_zoom.md): Explore 200,000 generated points without losing them as you zoom in.
- [Brush-linked penguin summaries](https://genomespy.app/genome-spy-python/gallery/penguin_brush.md): Select penguins in a scatter plot and count the selection by species and sex.
- [Scrollable viewport](https://genomespy.app/genome-spy-python/gallery/scrollable_viewport.md): A unit view keeps its row height while the outer container provides a vertical viewport for a longer categorical list.
- [Zoomable t-SNE scatter plot](https://genomespy.app/genome-spy-python/gallery/tsne.md): Explore a dense embedding with sample colors and points that grow on zoom.