Using the viewer
Open a bundle with ?d=<url> or choose a dataset from a gallery with ?d=<id>. The URL records the selected gene, annotations, filters and view layout. Drawn regions are saved separately as JSON; see Regions. Links to a local server require that server to be running on the computer opening them.
Layout
The spatial view holds every section as a grid or a strip, at true physical scale, under one set of settings. If the dataset has embeddings (snRNA-seq UMAPs), they render in a second embedding view beside it; drag the divider to resize, use the swap button or the top bar to put it left or right, or turn it off.
| Action | How |
|---|---|
| Focus one sample | double-click it, or the ⤡ button in the sample list |
| Step through samples | ← → (or PageUp PageDown) |
| Back to all samples | Esc, or "show all" |
| Fit to view | f |
| Hide samples from the layout | the top bar's platform buttons, or hs=<id> in the link |
| Turn a section on screen | click the section, then the ↻ tool in the top bar (or the ↻ on its row in the sample list): 90° clockwise per click, kept in the link; transform: { rotate } in the dataset yaml makes it permanent |
| Show one platform | the top bar: All / Visium / Xenium …; shift-click toggles |
| Grid vs strip | Samples → grid / strip |
| Cluster names on the embedding | Cells → Drawing → Embedding labels |
| Compare groups side by side | the top bar: split by → a sample metadata key |
Panes: comparing groups side by side
When the dataset's samples carry metadata (meta: in the yaml: condition, sex, genotype, ...), the top bar offers split by. Choosing a key divides the tissue canvas into one pane per level, control on one side and stress on the other, a third pane for a third level; with more levels than panes, each pane's header has a select to choose which group it shows. Every pane has its own camera, scale bar and caption ("control · 2 sections"), and the one the pointer last touched is underlined: ← →, Esc and double-click work inside it. Colour, filters, the legend, images, the lasso and regions stay shared, exactly as they are between the tissue and the embedding; hover rows show the section's metadata.
match scale, on by default, keeps every pane at the same microns per pixel: zoom in one and the others follow in scale while each keeps its own centre, so two sections can be read side by side at equal size. One click releases it; f fits every pane again. Drag the handles between panes to resize them (double-click a handle to equalise); under about 900 px of width the panes stack vertically. Sections that have no value for the key are not drawn while the canvas is split, and the top bar says how many. The split, the groups shown, the handle positions and each pane's camera travel in the URL, so a copied link reopens the same comparison.
Pinned windows: two sections side by side
Two sections that are not neighbours in the grid can be put side by side. The canvas is then two windows, left and right. Press the pin tool (top left, next to the lasso): every section in the grid gets a frame, and the words next to the pointer say what a click does ("pin Section 151673 on the left"). The first click opens that section in the left window; the grid moves to the right, where you click a second section to fill the right window. Right-clicking a section offers the same two choices, Pin left and Pin right, without arming the tool. Each window has its own camera, scale bar, point size and header: a select to swap the section it shows, the side it is pinned to, and an × to unpin. Each window zooms and pans on its own; with both pinned, match scale in the top bar links them at the same microns per pixel when you want that. Unpinning gives the window back to the grid; the embedding pane steps aside while a section is pinned and returns when the last pin goes. A pinned section keeps a frame in the grid in the pin colour. The two slots travel in the URL as pins=<left>,<right>, with the left window's share as pf.

The view above compares one gene in two donors of the DLPFC example: MOBP, a white matter gene, in section 151507 beside section 151673, with the H&E hidden and the spots enlarged. Its URL parameters: c=g:MOBP, img=0, pins=vis_151507,vis_151673, psg=1.60,1.60.
Color by
- Gene: type to search. Values are log-normalized expression; the range slider rescales the colormap, "hide zeros" removes non-expressing cells.
- Feature groups: non-gene features such as RCTD cell type weights appear under their own tab with a scrollable list.
- Gene sets: two gene sets, one gene or fifty each. Each set's score is the mean normalized expression of its genes; the two scores index a 2D color table. Schemes: yellow / blue → green, cyan / magenta → white, red / green → yellow. The legend becomes a color square.
- Annotation: any categorical or continuous field. Categorical legends show counts; click a category to hide it, double-click to solo it. Fields that only some samples carry are grouped separately in the menu.
Samples that don't carry the selected feature are drawn in grey ("not measured") rather than hidden.
Features that take negative values (module scores, motif deviations) are stored symmetrically around zero and drawn with a diverging colormap centred on zero, whatever the colormap setting; the legend shows the real minimum and maximum.
When an embedding is colored by an annotation, each category's name floats at the centre of its cells, largest clusters first and never overlapping; hidden categories lose their label. Embedding labels under Cells → Drawing turns them off (cl=0 in the URL).
Filter by
Independent of coloring: keep cells whose gene expression or continuous value falls in a range (with a live histogram), or cells in chosen categories of an annotation. The map, counts and dot plot all respect it. The URL carries it as fl=.
What a filter and the numbers around it count: a cell is shown when its section is on screen, its category is not hidden in the legend, it passes the filter, and (with hide zeros on) it expresses the gene on screen. Hover and the lasso see only shown cells, so a selection never contains a cell you could not see. The legend counts cells of each category among the sections on screen that pass the filter (a category you hid keeps its count); the dot plot and the filter panel's shown line use the same population. A gene filter is set on one scale across sections, the largest per-section maximum, like the colour scale, so the same expression value passes everywhere; with scale each sample to its own max it is per section. A section that does not measure the filter's gene or annotation shows no cells while the filter is on, and the panel says how many cells that hides.
Expression by annotation
When coloring by a gene (or by gene sets, where it reads the first set), this panel shows mean expression and percent expressing per category of any annotation across the visible samples, with a per-sample heatmap toggle. Clicking a row filters the map to that category; several rows combine.
Hover
The tooltip lists the current gene's value, the filter gene's value if different, every categorical annotation of the cell with its swatch, and the cell id.
Lasso
Press L or the ⌒ lasso button, drag around a region, release. Selected cells get a white ring and the Selection panel shows counts per sample, the composition of every annotation, and the current gene's mean and percent expressing in the selection next to the same numbers over all cells of the sections the selection touches (shown as "vs … overall"). "export CSV" downloads sample,cell_id,row rows, row being the cell's position in the bundle. Esc clears.
Gene color scale
Gene colors share one scale across all samples on screen, so the same color means the same log-normalized value in every section; the legend shows the numeric range. Every number the viewer shows for a gene (legend range, hover value, selection mean, dot plot, filter histogram) is reconstructed from the bundle's 8-bit storage, where each gene is kept as 256 levels between its minimum and maximum in that sample, so they are display summaries good to about 0.4% of a gene's range, not the values in your object; compute statistics on the object, with s.selection() from a notebook if the selection came from the viewer. Tick scale each sample to its own max to stretch every section to its own maximum instead, which brings out structure in low-count platforms at the cost of comparability: the legend then reads in fractions of each sample's range, and a gene filter's threshold becomes a fraction of each sample's own maximum rather than one expression level. The two gene sets of Gene sets mode are scored as the mean log-normalized expression of their genes, scaled against the largest selected gene maximum across samples, or within each sample when per-sample scaling is on.
Sharing and export
copy link in the panel header copies a URL that reproduces the whole view: dataset, coloring, filters, hidden categories, camera, split and point sizes. From spatialscape serve that URL points at 127.0.0.1 and opens only on your computer (the button says "copied · local link"); links to send around come from a published site. PNG downloads the current frame at screen resolution (2× on high-density displays) with the legend and scale bar drawn in. Press ? for the list of keyboard and mouse shortcuts.
Point size
The slider at the bottom left of each pane multiplies the point radius, from a quarter to four times the platform's default (Visium spots at their true 55 µm, cells at 5 µm). The tissue canvas and the embedding each have their own value. When the canvas is split by a group, every pane has its own slider too: a dense section and a sparse one can be read side by side at different sizes, and a double-click on a group pane's slider makes it follow the shared value again; on the other sliders it resets the size. The values travel in the URL (ps, pse, psg).
How many cells are drawn
Zoomed out, a section holds more cells than it has pixels, so the viewer draws a random sample of each: about 0.6 points per screen pixel of the section, the same cells every time. Zooming in adds cells until every one is drawn, for any section or embedding of up to two million points; a larger one stays a sample of two million. The legend's counts, the filters and the tests always use every cell, and hover finds the cells that are drawn.
Regions: your own annotation
The Regions panel turns the lasso into an annotation tool. Add a group, then lasso as many areas as you like, in any section or in the embedding; each lasso becomes a translucent polygon in the group's colour, labelled, and stays attached to its section through layout changes. Add the next group and keep going; click a group (or press 1–9) to draw into it, Backspace removes the last area, Esc stops drawing. Where lassos overlap, the last one drawn wins. Double-click a name to rename it; the swatch changes the colour. The switch on the ROIs bar hides the drawn regions and the lasso's highlight to see the tissue under them; the groups, their cells and the test results stay, and drawing anything switches them back on (roi=0 in the URL).
The groups are a live annotation called Regions: colour the cells by it, and the legend shows the counts per region (plus "unassigned", which you can hide), hover rows name the region, the dot plot can be grouped by it and filters can use it. export CSV writes sample, cell_id, region for every cell inside a region; save writes the drawing itself (groups and polygons) as JSON and load brings it back, including onto a rebuilt bundle, since polygons are stored in each section's own coordinates. In a notebook, s.regions() returns the same table as a pandas Series aligned with your object (In a notebook).
Differential expression between regions
Under the region list, Differential expression tests the regions you drew, in the browser, on the cells themselves. Choose what to compare and press run the test:
- one region against the other, when you drew two: positive log2FC means higher in the first.
- each region against the rest: every region in turn against every other cell, of the sections you drew on or of every section, as you choose (one region alone is always tested this way).
Each side is tested per platform, never pooled across them: with regions on a Visium section and a Visium HD section the result has a Visium and a Visium HD column, so the same contrast can be read on both. Per gene and column the panel holds the log2 fold change of mean expression (on the expm1 scale, with a pseudocount of 1, as Seurat reports it), the two-sided Wilcoxon rank-sum p-value with ties corrected, the Benjamini-Hochberg padj over the genes expressed in at least 10 % of either side, the percent expressing on each side, the AUROC the rank statistic implies, and sections agreeing: of the sections holding at least three cells on both sides, how many show the same direction on their own. A side larger than the cap (3,000 cells, or 10,000) is cut to it by whole blocks of the row store, so the download shrinks with the cap; the i button in the panel header lists how many cells each side used, per section. Runtime depends on the number of genes, selected cells and data host.
The result opens in the Compare panel like a comparison shipped with the dataset, is listed in the Comparisons group until the next run, and exports with the panel's CSV button. It needs the bundle's per-cell row store (rows.zarr, which build writes for tissue sections; a bundle built before it existed lacks it, and the panel says so), and sections without one are left out and named. The test treats cells as independent: spots of one section are not replicates, and a difference between regions drawn on different donors is a difference between donors too. For a result to publish, fit a model with replicates and add it as a comparison.

Above, a box over white matter and one over layer 3 on each of two pinned sections of the DLPFC example, tested against each other: the genes sorted by log2 fold change, the myelin genes MBP and PLP1 at the top, and MBP's distribution in each region on the right.
Compare panel: a test's results next to the tissue
When the dataset carries comparisons, the side panel has a Comparisons group, one row per comparison. Choosing one splits the canvas by its groups (unless you had split by another key), filters the map to the population the test was fit in when the comparison names one (a chip in the panel header says so and clears it), and opens a panel under the maps:
- The matrix, left: one row per gene, one column per level (every cluster of a marker table, every cell type a contrast was fit in, or the one column of a plain two-group result), each cell the log2 fold change tinted by sign and size (hover for padj, % in / out and rank; blank where a filtered table has no row). Click a column head to focus that level and sort by it (again to flip), the box to find a gene; the select in the corner shows another statistic in every cell (padj, % expressing, rank, and for a test run in the viewer AUC and sections agreeing). Clicking a row colours every pane by that gene;
↑and↓step through the table as sorted. Genes no section measures stay listed, greyed, with a count in the header. CSV in the header downloads the whole matrix, every level's statistics per gene. - The distribution, right, for the gene on screen. When the levels are an annotation's categories (a marker table, a per-cell-type contrast): violins of the gene's expression per category, drawn from the same per-cell values the maps use, the focused level in full colour with a tick at each median. When the comparison carries pseudobulk values: one dot per mouse or donor in the comparison's group order and colours, a median line per group, quartile boxes on request (box), and a line joining a subject that appears in several groups (a paired design); hovering a dot names the replicate, its value and its sections, clicking it focuses its first section. Under the plot: the table's numbers for that gene in the focused level and the comparison's description, verbatim.
The focused level travels as cmp=<id>:<level> in the URL. For a markers comparison the map is not filtered (the question is whether the gene is specific, which the whole tissue answers); only Astro on the map filters it to the focused cluster on request and follows the focus; each legend row of the matching annotation shows a markers button on hover that opens the table focused on that cluster. The violins and the expression by annotation dot plot in the Cells group read the same field, so the two agree.
For a comparison shipped with the dataset nothing in the panel is computed by the viewer: the effects, p-values and replicate values are the ones the tables held, and the dots are the values you fitted, not a re-aggregation of the 8-bit expression the maps are drawn from. The one exception is a test on drawn regions, computed in the browser and marked as such. The chosen comparison travels in the URL as cmp; closing the panel with × leaves the split and the filter as they are.
Genome panel
An ATAC sample built with tracks: (Genome tracks) adds a genome panel under the maps, drawn by the same renderer as the maps: scroll to zoom around the cursor, drag to pan, double-click to zoom in, and drag the panel's top edge to resize it. From top to bottom it shows the coordinate axis, one accessibility track per visible category of the annotation you last colored by (in the vocabulary's colors, on one shared scale printed in the header and set by the highest value in view, drawn through a rolling mean the header lets you set from raw bins to 1 kb, so hiding a category in the legend removes its track), the sample's peaks, and gene models with exons and strand arrows. Coloring by a gene keeps the per-category tracks, so a locus reads per cell type.

The locus follows what you color by: a gene (with room around it), a gene's activity score, or a peak (plus or minus 10 kb), and a band marks it. The search box takes a gene name, completed from the genome's gene models, or a locus such as chr11:60,405,808-60,512,181; the chromosome menu shows a whole chromosome. Hovering shows the position and the value of the track under the cursor; clicking a gene colors the maps by its expression (or its activity score when the sample has no RNA), clicking a peak colors them by that peak's accessibility. The locus travels in the URL as gl; the genome switch in the top bar hides the panel (gb=0).
Images and cell shapes (details)
H&E or fluorescence images render beneath the points. Use the opacity slider to blend the image with the background. For multichannel images, click a channel to show or hide it, or double-click to show it alone. The viewer displays up to six channels at once; switch one off before enabling a seventh. Channels are matched by name across samples. Only enabled channels are fetched, and enabling a channel may load tiles that are not already cached. Hide cell categories or reduce point size to see more of the underlying image.
When the bundle has cell boundaries, cells turn from dots into their shapes once a cell is about 6 px across. Draw cells as in the Cells group chooses how: filled, in the cell's colour with a darker edge (the default when no image is drawn), outlined, in the cell's colour over the image (the default when one is), or dots to keep the dots. Shapes follow everything the dots do: the gene or annotation colour, blends, filters and hidden categories, with no extra download when the colour changes. Only the tiles in view are fetched, once the camera stops moving; while they arrive the dots stay. When a view holds more than about 40,000 cells the status line says zoom in for cell shapes. The choice travels in the URL as cs.
The side panel
The panel is up to six groups, each a bar that opens its controls; closed bars show a one-line summary, several can be open at once, and what is open is remembered per browser. Image, Transcripts and Comparisons appear only when the dataset has them:
- Image: its switch in the bar, opacity and, for fluorescence, the channel list.
- Cells: its switch in the bar (off leaves the image and the transcripts alone on the canvas), colour by (gene, cell type weights, gene sets, annotation), the legend, expression by annotation, the filter, and Drawing: how cells draw once zoomed in (dots, filled, outlined), a second segmentation to compare with, cluster labels.
- Transcripts: its switch in the bar, selected genes or all genes, the pinned genes with their colours, the point size.
- Comparisons (when the dataset carries any): its switch in the bar opens or closes the panel under the maps; one row per comparison, the active one with its level (a cluster, a cell type).
- ROIs: the lasso's selection and your drawn regions.
- Samples: the grid or strip layout, show all, and the list of sections, each with its focus and turn buttons.
The groups are what is drawn, not how; a Transcripts bar reading "GAD1 · 2 pinned" tells you what the molecules show without opening it.
Comparing segmentations
When a bundle carries another segmentation of a section (Xenium's nucleus boundaries are picked up automatically next to the cell boundaries; others come from segmentations: in the yaml), Compare with in the Cells group draws it as dashed amber edges over the cells, the image and the molecules once zoomed in, and shows a small table, cells and median area, for the focused section (or every section) against the cells' own shapes. The choice travels in the URL as ov.
Molecules
When a bundle carries molecules (Xenium transcripts, from molecules: in the yaml), the Transcripts group draws them once a view holds at most about one per screen pixel, counted from the tiles in view (about a million in a large window, which keeps a laptop near 60 frames per second; every molecule of a view is drawn, none are sampled). Until then the status line says zoom in for molecules. A size slider in the group scales the points (double-click to reset; msz in the URL). Selected genes draws only the genes you have chosen: the gene you are looking at in the colormap's top colour, the two gene sets in their colours, and the genes you pin, each in its own colour. No other transcript is drawn, so with an annotation on screen and nothing pinned the map shows none and the status line says pick a gene to draw its transcripts.
Zoomed out, a cell can show one gene; zoomed in, the molecules can show several. The Transcripts group lists the gene on screen and lets you pin more, each in a fixed colour, with a search box; a pin stays while you step through other genes, so a few anchors remain visible, and click × to unpin. All genes draws every transcript, each gene in its own hue, the view for seeing where transcripts of different kinds gather and for judging a segmentation; pins and the gene on screen keep their colours on top of it (mc=all in the URL). Molecules not assigned to a cell draw dimmer, and the cell dots fade under them. Only the tiles in view are fetched, once the camera stops; pinning and unpinning download nothing. Click a pinned gene's colour square to choose another colour for it. The switch, the pins and their chosen colours travel in the URL as mol=1 and mg.
Sharing a view
Copy the URL. It encodes the dataset, the focused sample, color and filter settings, hidden categories, split layout and camera. See URL parameters for the keys.