Skip to content

QA: Spatial omics

Test cases for the Spatial omics plot types, the Spatial omics panel, colouring, gene filters, selection, distribution charts, transcripts and the fallbacks without WebGPU. See How to use the plan. Reference: Spatial omics, Distribution charts.

Datasets are in the demo's spatial-omics gallery folder:

Short name Gallery entry Use for
Visium Adult mouse brain Visium H&E · 2,688 spots 2D over tissue, group/gene/measurement, selection, charts
Demo SYNTHETIC · fabricated expression · Visium geometry (demo) Quick 2D checks
seqFISH Mouse embryo seqFISH · 19,416 cells No tissue image, embeddings
ABC Allen Brain Cell Atlas → Whole mouse brain MERFISH · 3D (and · 1-in-10) 3D, volume, class tree, class volumes, large data

Transcript, cell-segmentation and gene-heatmap "All genes" cases need a dataset that has them (in JIT).

Opening datasets and plot types

ID Title Pri Preconditions / data Steps Expected result
SPA-001 Dataset list P1 Demo page 1. Open the spatial-omics folder. Tiles marked "OMIC" named "name · N obs"; a source with 4 or more datasets has its own sub-folder; the hint "Click a dataset to open it over its tissue image, then pick Spatial omics…".
SPA-002 Open a dataset with tissue P1 Visium 1. Click the Visium tile. "Preparing the tissue image…" then "Loading observations…"; the H&E opens in the Image view.
SPA-003 Spatial omics plot types offered P1 Visium 1. Open the plot-type dropdown. Spatial omics is listed (with Image, Heatmap, Surface…); Spatial omics 3D is not (no z).
SPA-004 Switch to Spatial omics P1 Visium 1. Pick Spatial omics. Spots are drawn over the tissue, coloured by the first categorical column. The Spatial omics controls button appears in the toolbar.
SPA-005 Dataset without tissue image P1 seqFISH 1. Click the seqFISH tile. The view opens directly in Spatial omics (or Spatial omics 3D if the cells have z). Image, Heatmap and Surface are not offered.
SPA-006 Dataset with a reference volume P1 ABC 1-in-10 1. Click the tile. 2. Open the dropdown. The volume opens in Image as a z-stack; Spatial omics 3D is offered.
SPA-007 Spatial omics 3D P1 ABC 1-in-10; WebGPU 1. Pick Spatial omics 3D. 2. Rotate. The cells are drawn as a 3D cloud in the volume; it rotates, pans and zooms with the 3D camera controls; the 3D axes and wireframe toggles are present.
SPA-008 Plot types removed when the dataset closes P2 Visium in Spatial omics 1. Open img01.png from the gallery. Spatial omics types disappear from the dropdown; the view falls back to Image.
SPA-009 Large dataset P2 ABC full (3.7 M cells) 1. Open it, pick Spatial omics 3D. The cloud renders (it may take time); the page stays responsive. Integrated graphics may be slow; the 1-in-10 subset is the light alternative.
SPA-010 Click-to-zoom off P2 Visium in Spatial omics 1. Click on the map (no tool armed). 2. Scroll. 3. Use Zoom box. A click does not zoom (it selects, see SPA-096); scroll, zoom buttons and zoom box still zoom.

Panel

ID Title Pri Preconditions / data Steps Expected result
SPA-020 Open the panel P1 Visium in Spatial omics 1. Click "Spatial omics controls". Tooltip "Spatial omics (colour by column or gene, legend, selection, distributions)". A non-modal, resizable, draggable panel "Spatial omics" opens on the left (30rem; 90vw below 960 px).
SPA-021 Header P2 Panel open 1. Read the header. The dataset name and "2,688 observations" (locale formatting).
SPA-022 Sections (2D with tissue) P1 Visium, Spatial omics 1. Look at the sections. Images (closed), Observations (open), Regions (closed, switch off), Distribution (collapsed), Reset. No Volume section.
SPA-023 Sections (3D with volume) P2 ABC, Spatial omics 3D 1. Open the panel. Volume replaces Images; no Images section.
SPA-024 Images section P3 Visium 1. Expand Images. 2. Untick its switch. The note "Channels, colours and contrast are in the Channels & Histogram dialog."; unticking hides the tissue image.
SPA-025 Volume opacity P2 ABC, 3D 1. Expand Volume. 2. Move Opacity. 3. Untick the switch. Opacity 0.05–1, step 0.05, default 0.5; the hint "The registered anatomy the observations sit in."; the slider is disabled while the volume is hidden.
SPA-026 Hide the observations P2 Visium 1. Untick the Observations switch ("Show the observations"). The spots disappear; the tissue stays.
SPA-027 Fold sections P3 Panel open 1. Click each chevron. Each section folds and unfolds.
SPA-028 Reset P1 Gene colouring, gene filter, regions on 1. Click Reset. Flat colour, no gene filter, Regions off, sliders at defaults, selection cleared.
SPA-029 Resize re-fits charts P3 A chart showing 1. Resize the panel. The chart re-fits when the resize is released.
SPA-030 No data source P3 A host without SPATIAL_DATA_PORT (developer build) 1. Open the panel. "No spatial-omics data source is configured. A host provides one by binding SPATIAL_DATA_PORT."

Colour by

ID Title Pri Preconditions / data Steps Expected result
SPA-040 Modes offered P1 Visium 1. Look at Colour by. Group, Gene, Measurement, Single colour (each only when the dataset has that kind of data).
SPA-041 No colour source P3 Visium, after Reset 1. Look at the map and panel. Spots in one neutral blue; hint "One flat colour. Choose what colours the observations."
SPA-042 Group colouring P1 Visium 1. Colour by Group, column cluster. Spots coloured by cluster; the Groups list shows "All groups (total)" and one row per cluster (checkbox, colour dot, name, count), largest first.
SPA-043 Hide a group P1 After SPA-042 1. Untick one cluster. 2. Untick "All groups (total)". 3. Tick it. That cluster's spots disappear; all disappear; all return.
SPA-044 Change a group colour P2 After SPA-042 1. Click a colour dot ("Colour"). 2. Pick a preset. 3. Reopen, Reset to default. Picker "Group Color" with hex input and presets; the spots recolour; Reset restores the default colour.
SPA-045 Column families P3 seqFISH (or a dataset with k-means k=2…10) 1. Open the Groups dropdown. A family is listed once with a second dropdown for the variant.
SPA-046 Import groups P3 JIT (a host supporting group import) 1. Click "Import cell groups (CSV of cell_id, group)". 2. Choose a CSV. A new column named after the file appears and is selected. Errors show in red. Not shown in the demo.
SPA-047 Gene colouring P1 Visium 1. Colour by Gene. 2. Type Ttr in "Search 18078 genes…". 3. Pick it. Spots coloured by Ttr expression; the key shows "Gene · Ttr" with a low–high colour bar; Log scale is preset from the dataset's hint.
SPA-048 Gene search messages P3 Visium, Gene mode 1. Type zzzz. "No match" (or "No match — keep typing" for a remote gene list).
SPA-049 Measurement colouring P2 Visium 1. Colour by Measurement, pick total_counts. Placeholder "Pick a measurement"; options read name (unit); spots coloured on a continuous scale with a key.
SPA-050 Single colour P2 Visium 1. Colour by Single colour, pick red. All spots red. Default value #4fc3f7.
SPA-051 Colormap P2 Gene colouring 1. Open Colormap in the key. 2. Pick Magma. 3. Clear it. Tooltip "Colour scale for gene and numeric values — the markers, the gene map and this bar. Clear it to follow the image's colormap". Cleared: follows the image colormap (Viridis if grayscale).
SPA-052 Log scale P2 Gene colouring 1. Toggle Log scale. The colour distribution changes; tooltip "Counts collapse against their outliers on a linear ramp".
SPA-053 Clip outliers P2 Gene colouring 1. Open Clip outliers. None / 1% / 2% / 5%, default 1%; tooltip "Percentile the contrast window is taken at"; changing it changes the key's window.
SPA-054 Colouring exclusive P3 Group colouring 1. Switch to Gene. The Groups list is replaced by the gene picker and key; only one source drives colours.
SPA-055 Hover tooltip P2 Group colouring, then gene 1. Hover a spot. Group: the category and column. Gene: the value (2 decimals, exponent notation for ≥ 1000 or < 0.01) and the gene name. Nothing with no colour source.

Show observations expressing

ID Title Pri Preconditions / data Steps Expected result
SPA-060 Filter by one gene P1 Visium 1. In "Any gene (every observation)", pick Ttr. Only spots with Ttr > 0 are drawn; the hint explains that the others are hidden.
SPA-061 Any vs All genes P2 Visium 1. Pick Ttr and Mbp. 2. Switch Any gene / All genes. Any: spots expressing either; All: only spots expressing both.
SPA-062 Colour by these genes P2 Two genes picked 1. Toggle Colour by these genes (on by default). On: each spot takes the colour of the gene it expresses most (relative to that gene's max). Off: the Colour by colours apply.
SPA-063 Gene icon and colour P3 Two genes picked 1. Click a gene's swatch ("Icon and colour"). 2. Pick another icon and colour. 3. Reset. Popover "Observation Icon" / "Observation Color", hint "Icons show on the 2D observation markers."; icons change on the map; Reset restores the palette colour and circle.
SPA-064 Remove a gene P3 Two genes picked 1. Click × ("Remove"). The gene leaves the filter.
SPA-065 More than three genes P3 Visium 1. Pick 4 genes. The box shows "4 genes".
SPA-066 Read failure P3 Block expression requests in DevTools 1. Pick a gene. "The expression of the picked genes could not be read, so the observations still show the previous filter. Try again"; Try again retries.

Markers, gene map and 3D options

ID Title Pri Preconditions / data Steps Expected result
SPA-070 Point size P2 Visium 1. Move Point size to 0.25× and 5×. Range 0.25×–5×, step 0.25, default 1×; spots shrink and grow. When zoomed out spots never go below 2 screen pixels.
SPA-071 Marker opacity P2 Visium 1. Move Opacity. Range 0.1–1, step 0.05, default 1.
SPA-072 Gene map P2 Visium, colour by gene Ttr 1. Tick Gene map (expression field). 2. Lower spot opacity. A smooth field is drawn under the spots, transparent where nothing was measured; Smoothing 0.5×–4× (default 1×) and Map opacity 0.1–1 (default 0.85) appear with the explanatory hint.
SPA-073 Gene map only for genes P3 Visium, Group colouring 1. Look for the Gene map. Not shown.
SPA-074 3D gene map options P3 ABC, 3D, colour by a gene 1. Tick Gene map. 2. Tick Volume rendering (interpolate along z). 3. Untick it, tick One map section at a time. Per-section fields; interpolation smooths them into a volume (note says it is an ESTIMATE); one section at a time shows the Map section slider ("k of n", opens on the middle section).
SPA-075 One section at a time P3 ABC, 3D 1. Tick One section at a time. 2. Move Section. A single imaged section's cells are drawn; the slider reads "k of n" and opens on the middle section.
SPA-076 Empty "Show" group P3 seqFISH in 3D (unsectioned) or ABC with observations hidden 1. Look at the 3D options. Record behaviour: "Show" may appear with nothing under it. ⚠ see Known issues (KI-38).
SPA-077 Cluster density volumes P3 ABC, 3D, group colouring 1. Tick Cluster density volumes. Density volumes for up to the 6 largest clusters (or the selection); Smoothing 0.5×–4×; the estimate note shows.
SPA-078 Cell segmentations P2 JIT dataset with cell boundaries 1. Show as → Cell segmentations. 2. Try View cells as Fill / Outline / Both. 3. Change Cell fill opacity. Cells drawn as fills/outlines; opacity 5–100% (default 55%), hidden for Outline only; Boundaries switches per set.
SPA-079 3D cells P3 JIT 3D dataset with segmentations 1. In 3D → By cell type, then Individual cells. One surface per type; individual cells build progressively with "Building cells… n shown so far", capped to the cells nearest the view centre.

Selection

ID Title Pri Preconditions / data Steps Expected result
SPA-090 Select from ROIs (2D) P1 Visium, Spatial omics 1. Draw a freeform region around one brain area. 2. Expand Regions. 3. Click Select from ROIs. Tooltip "Select every observation inside the drawn regions". Spots inside are selected, the rest muted; hint "n of 2,688 selected — the rest are muted." Clear appears.
SPA-091 Several regions and holes P2 Visium 1. Draw two regions and a donut. 2. Select from ROIs. The union is selected; spots inside the hole are not.
SPA-092 Works while regions are hidden P3 After SPA-090 1. Untick the Regions switch. 2. Select from ROIs again. The selection still works.
SPA-093 Miss P3 A region with no spots in it 1. Select from ROIs. "No observations fell inside the drawn regions."
SPA-094 Clear P1 A selection 1. Click Clear. All spots return to full opacity; Clear disappears.
SPA-095 Select a group by name P2 Group colouring 1. Click a cluster name ("Select name"). 2. Click it again. That cluster is selected, others muted; the second click clears.
SPA-096 Click a marker P2 Group colouring 1. Click a spot. 2. Click it again. Its group is selected; clicking again clears. Dragging (pan) does not select.
SPA-097 No click selection with gene colouring P3 Gene colouring 1. Click a spot. Nothing is selected.
SPA-098 3D lasso P2 ABC, 3D 1. Draw a freeform region over the cloud. 2. Select from ROIs. 3. Orbit, draw again, select. Selected cells cut through the full depth as seen from the camera; hint "In 3D a region cuts through the cloud's full depth. Orbit and draw again…".
SPA-099 3D class-volume selection P1 ABC, 3D 1. Region Editor → class tree: pick a brain region. 2. Select from ROIs. Tooltip "Select every observation inside the volumes of the classes picked in the Region Editor"; hint "Selects inside the volume of class…"; the cells inside that brain region are selected.
SPA-100 Class pick superseded P3 ABC, 3D 1. Pick a class, click Select from ROIs. 2. Immediately click Clear (or pick another class). The first result is discarded; only the latest action applies.
SPA-101 Dataset switch clears the selection P2 A selection on Visium 1. Open the Demo dataset. 2. Open Visium again. No selection; the gene filter is empty; custom group colours reset.
SPA-102 Observations in selection P2 A selection, Group colouring 1. Expand "Observations in selection". The selection label, "plane k of n" or "whole volume", "N observations · G groups of column", bars per group, mean measurements. Copy puts tab-separated "group, observations" on the clipboard.
SPA-103 Observations in selection — empty P3 No selection 1. Expand it. 2D: "Select a cell or a region to list the observations in it." 3D: "Select a cell, or pick a cell type, to list the observations in it."

Distribution charts

ID Title Pri Preconditions / data Steps Expected result
SPA-120 Expand Distribution P1 Visium, Group colouring 1. Click Distribution of cluster. The section expands and scrolls into view; the Counts chart is shown.
SPA-121 No colour source P3 After Reset 1. Expand Distribution. "nothing selected to chart" / "Colour the map by a column or a gene to chart its distribution."
SPA-122 Chart types for a categorical source P2 Group colouring 1. Look at the chart tabs. Counts, Heatmap, and Embedding (when the dataset has embeddings). No Histogram/Violin/Box.
SPA-123 Chart types for a continuous source P2 Gene colouring 1. Look at the tabs. Histogram (default), Violin, Box, Heatmap, Embedding. Switching to a gene from a group switches Counts to Histogram automatically.
SPA-124 Counts P1 Group colouring 1. Show Counts. Horizontal bars, largest at the top; hover "n obs"; x axis "observations".
SPA-125 Counts top 25 P3 A column with more than 25 categories 1. Show Counts. 25 bars plus a grey "other (N categories)" bar.
SPA-126 Counts with a selection P2 A selection 1. Show Counts. An "All" bar (faded) with a "Selected" bar overlaid; a "n selected" badge.
SPA-127 Histogram P1 Gene colouring 1. Show Histogram. 2. Turn Log scale on. Bins √n clamped to 10–100; y axis "observations"; x axis the gene, then "log1p(gene)".
SPA-128 Histogram with a selection P2 A selection 1. Show Histogram. "All" and "Selected" overlaid with a legend; hint "The selection is overlaid on the full distribution."
SPA-129 Violin and Box grouped P2 Gene colouring 1. Violin; grouping cluster. 2. Box. One trace per cluster in the map's colours (empty clusters dropped). Grouping tooltip "Split a violin or box by a categorical column".
SPA-130 Violin ungrouped hint P3 Gene colouring, No grouping 1. Show Violin. A single "All" trace and the hint "Pick a grouping to compare categories."
SPA-131 Violin/Box with a selection P3 A selection 1. Show Violin. Only the selection is shown; hint "Showing the selection only."
SPA-132 Grouping disabled for Histogram P3 Histogram 1. Try the grouping dropdown. Disabled.
SPA-133 Chart help P2 Each chart 1. Hover the ? icon for each chart type. A help text specific to the chart (Counts, Histogram, Violin, Box, Heatmap; Embedding text depends on PCA / t-SNE / UMAP), including what not to read into it.
SPA-134 Heatmap seeded from the gene P2 Colour by gene Ttr, no grouping 1. Show Heatmap. Rows start with Ttr; the first categorical column is chosen as grouping.
SPA-135 Heatmap picked genes P1 Visium 1. Heatmap, grouping cluster. 2. Pick 6 genes in "Pick genes for the rows". Genes down, clusters across, z-scored (diverging blue–white–red, colour bar "z"); height grows with genes.
SPA-136 z-score off P2 After SPA-135 1. Untick z-score. Raw means with a sequential blue scale (colour bar "mean").
SPA-137 Heatmap column cap P3 A grouping with more than 40 groups 1. Show Heatmap. At most 40 columns, the strongest kept; the note says "Showing the 40 strongest of M…".
SPA-138 Heatmap per cell P3 A selection of ≤ 200 cells 1. Show Heatmap. One column per selected cell; note "One column per selected cell (n)…".
SPA-139 Heatmap empty P3 No genes picked 1. Show Heatmap. "Pick one or more genes for the rows."
SPA-140 Heatmap All genes P2 JIT dataset with a gene heatmap 1. Switch Picked genes → All genes. Every gene against every cell, zoomable (scroll, Shift: genes only, Alt: cells only; drag to pan; double-click resets). Cells / Groups view, scale options, Detected genes only (on), Find a gene, Reset zoom. Not offered by the demo server. ⚠ see Known issues (KI-40).
SPA-141 Embedding P1 seqFISH, group colouring 1. Show Embedding. A scatter of the embedding coloured like the map; dropdown "Which embedding to draw" when there are several; caption "label. Coloured to match the map.".
SPA-142 Embedding axes P3 seqFISH 1. Pick a PCA, then UMAP. PCA axes show "(xx.x%)"; UMAP axes do not.
SPA-143 Lasso on the embedding P1 seqFISH 1. Use the chart's lasso to circle a cluster. Those cells are selected on the map too (others muted); an empty lasso clears.
SPA-144 Embedding with gene colouring P3 seqFISH, gene colouring 1. Show Embedding. Points not coloured; caption "Colour the map by a categorical column to colour these points."
SPA-145 3D embedding P3 seqFISH 1. Pick a 3D embedding. A rotatable 3D scatter.
SPA-146 t-SNE compute offered only when allowed P3 A JIT dataset with PCA, no t-SNE, ≤ 5,000 observations 1. Embedding dropdown. "t-SNE (compute)" and "t-SNE 3D (compute)" are offered; button "Compute (~Ns)". Not offered for the demo datasets (they ship a t-SNE).
SPA-147 t-SNE compute run and cancel P3 As SPA-146 1. Click Compute. 2. Cancel during "Optimising…". Progress "Building the neighbour graph…", "Optimising… on webgpu/wasm/cpu", Cancel stops it. Results are not kept after a reload.
SPA-148 t-SNE over the limit P3 A dataset with PCA and > 5,000 observations, no t-SNE 1. Embedding. "t-SNE is not offered here for N observations — it is quadratic…".
SPA-149 Detach a chart P2 Any chart 1. Click Detach. 2. Switch chart type. 3. Click Put back (or close the window). The chart opens in its own window "Kind · subject" (34rem × 30rem, right side); the panel shows "Shown in its own window."; it stays detached across chart types; Put back or closing returns it.
SPA-150 Chart load error P3 Block a column request in DevTools 1. Colour by that column. "X" could not be charted: … (or "A gene could not be charted: …").

Transcripts (JIT datasets with transcripts)

ID Title Pri Preconditions / data Steps Expected result
SPA-170 Transcripts section shown P2 Xenium-type dataset (JIT) 1. Open the panel. A Transcripts section (closed, off). Not shown for datasets without transcripts.
SPA-171 Pick genes and show points P1 Same 1. Search 3 genes in "Search for genes to visualize…". 2. View transcripts as Points. Points in each gene's colour; the "Selected genes" tree lists them; footer "3/N genes selected".
SPA-172 Icons and Density Map P2 Same 1. Switch to Icons, then Density Map. Icons per gene; then a density raster with opacity 5–100%, bin size 10/20/40/80 µm, scale threshold (Auto), colormap (default Inferno).
SPA-173 Max markers P2 Many genes, zoomed out 1. Look at "Estimated Transcript Points". 2. Edit Max → 25k. Max choices 25k / 50k / 100k (default) / 200k / 400k. Over the budget transcripts are grouped by area with the hint "Max points reached…".
SPA-174 Marker genes of clusters P3 Same 1. ⋮ → Add marker genes of clusters…, Per cluster 5, choose clusters, Add marker genes. "Finding marker genes…" then the genes are added.
SPA-175 Gene groups P3 Same 1. ⋮ → New group from selected genes, name it. 2. ⋮ → Import gene groups (CSV)… with a bad file. The group appears in the tree; a bad file shows No "group,gene" rows found in that file.
SPA-176 Transcripts in selection P2 A selection 1. Expand "Transcripts in selection". "N transcripts · G genes · C cells" with a copy button; on large sections the "lower bound" caveat.
SPA-177 Density hidden with gene filter P3 Density Map, gene filter on 1. Pick a gene in Show observations expressing. The density map is hidden with the explanatory hint.

Fallback without WebGPU

ID Title Pri Preconditions / data Steps Expected result
SPA-190 2D WebGL fallback P1 Visium; WebGPU off 1. Pick Spatial omics. Spots are drawn over the tissue (as plain discs); colouring, gene filter, selection muting, hover and click-to-select work. The console logs "[visualizer] spatial view drawn with WebGL (no WebGPU)…".
SPA-191 Fallback limitations P3 WebGPU off 1. Try gene icons, cell outlines, transcripts. Gene icons show as discs; cell outlines/fills, transcripts and the density map are not drawn.
SPA-192 No tissue image without WebGPU P2 seqFISH; WebGPU off 1. Open seqFISH. Record behaviour: the dataset cannot be drawn in 2D without a tissue image; no uncaught error.
SPA-193 3D without WebGPU P2 ABC; WebGPU off 1. Pick Spatial omics 3D. Record behaviour (3D needs WebGPU; the chain falls back to Plotly); no blank page or uncaught error.
SPA-194 Error toast P3 A dataset that fails to draw 1. Open it. Toast "Could not draw the dataset".