Worked examples
Each example takes a few minutes, uses one of the demo datasets, and names every control exactly as it appears in the sidebar. They are written so that someone who has never used a spatial transcriptomics viewer can follow them and see what the tool is for. The user manual explains each control in full; this page shows why you would reach for it.
Every screenshot on this page was taken from the viewer itself, on the dataset the example names, with the settings the example gives. Nothing was drawn afterwards.
The demo datasets
Four small datasets come with the repository and appear in the Dataset menu as soon as the viewer opens. Three larger, real datasets are published as release assets; one command fetches them:
python3 sample_data/fetch_samples.py
| Menu entry | Platform | What it is | Used in |
|---|---|---|---|
mouse_ileum_tiny | Xenium | Three 640-px patches of mouse ileum (36 cells) from 10x's tiny example run, with generated edges and example metadata: a test fixture. In the clone. | — |
visium_hd_tiny | Visium HD | A corner of 10x's "Tiny Mouse Brain" Space Ranger output, 8 µm and 16 µm bins. In the clone. | 4 |
visium_tiny | Visium | Synthetic classic Visium slide, 252 spots, a test fixture. In the clone. | — |
seqfish_synthetic | seqFISH | Synthetic Spatial Genomics GenePS region, 36 cells, a test fixture. In the clone. | — |
xenium_human_breast_2fov | Xenium | 10x's human breast example, two fields of view, 7,275 cells, DAPI image, a NICHESv2 run and 10x's own graph clusters. Fetched. | 1, 3, 5, 7 |
visium_mouse_kidney | Visium | 10x's mouse kidney coronal section, 1,438 spots on tissue, NICHESv2 spot–spot edges. Fetched. | 4 |
cosmx-mousebrain | CosMx | Bruker/NanoString 1000-plex mouse brain, coronal section, 38,996 cells, no image. Fetched; non-commercial licence. | 1, 2, 6 |
When the viewer opens, Morphology, Transcripts and Edges are unticked, so you see cell outlines on a dark canvas. Every example below starts by ticking what it needs.
1Where is the signalling?
NICHESv2 scores every neighbouring pair of cells for every ligand–receptor mechanism it can see in the panel. TissuePlex draws that as a graph on the tissue: first the tissue graph, every pair of cells close enough to be scored, then the scores as colour on those same lines. Start with the structure, then ask where the signalling is. A coronal mouse brain section is a good first dataset because you already know its anatomy, so you can judge the answer.
- Choose cosmx-mousebrain in the Dataset menu. This dataset ships no image, so the cells are drawn on a frame sized from the data.
- Under Cell Segments, drag sample to 100% and fill down to about 12%, so the 38,996 cells sit as a faint ghost under the lines.
- Under Edge Data, drag sample to 100% and set the Tissue Graph opacity to about 60%. This is figure 1a.
- Tick Edges, raise its opacity to 100%, lower width to 1, and drop the tissue graph back to 15% so it reads as a faint scaffold under the coloured lines.
- In the legend under edge color, switch auto to robust 5–95%. This is figure 1b.
What to notice
- The strongest summed signalling follows the dense cell layers: the pyramidal layers of the hippocampus and the dentate gyrus light up, as do the midline structures. That is partly biology and partly geometry, since a cell with more neighbours accumulates more scored pairs. Example 2 is how you separate the two.
- Untick a mechanism in LRM Mechanisms and the colours update at once; the lines that only carried that mechanism disappear. Tick none, then one mechanism, to see where a single ligand–receptor pair is active.
- Edges are directed. Zoom in, raise offset, and A→B and B→A separate into two parallel lines with harpoon arrowheads, like a chemistry equilibrium arrow.
- Hold Shift and click a line. A floating EDGE panel lists the sending and receiving cell, every mechanism scored on that pair with its share of the total, and any annotations from
edge-metadata/.
The same two steps on a different platform
Nothing above is specific to CosMx. The pair below is the Xenium human breast example (two fields of view, 7,275 cells, 181,523 directed pairs scored over 32 mechanisms) drawn with the same settings and the same robust 5–95% range.
edge-metadata/, then every mechanism NICHESv2 scored on it with its share of the total: here seven, led by CXCL12 → CD4 and CXCL12 → CXCR4.On the breast dataset, open Edge Filter and set Sending cell to graphclust, then keep one cluster. Only edges leaving that cluster remain; the tissue graph underneath is untouched, so you can still see the neighbourhood structure the filter removed.
2One cell's neighbourhood
The scored graph answers "where"; the neighbourhood view answers "who, and through what". Zoom into the hippocampus first: at this scale the dentate gyrus and the CA pyramidal layer resolve into individual cells, and the graph becomes readable as a graph. Then click any cell and TissuePlex will show every cell it exchanges signal with, how far they reach, and which mechanisms dominate across those edges.
- With the settings from example 1, zoom into the hippocampus with the mouse wheel until single cells are clear.
- Click a cell in the pyramidal layer (a plain click, no Shift). The Cell Info block at the foot of the sidebar fills with its id, position and metadata.
- Click show local neighbourhood at the bottom of that block.
- Zoom in once more, until the cell and its neighbours fill the view. Untick Tissue Graph, raise offset to 3 and choose Harpoon, so each pair of cells shows its two directions as separate half-arrows.
The neighbourhood is computed from the whole edge file on the server, not from the lines currently drawn. So the count is complete even when the edge sample slider is below 100%, and it is the same wherever you have scrolled to. Colour cells by a metadata column first and the block also reports the neighbourhood's composition by that column.
3Your own annotations, without touching the data
Most analysis happens in R or Python after the instrument has finished. TissuePlex reads that work from two plain folders dropped beside the dataset, so clusters, scores or review flags appear in the viewer without regenerating anything:
cell-metadata/, one row per cell, keyed on the cell barcode.write.csv(df, "cell-metadata/clusters.csv")from R works as is.edge-metadata/, one row per cell pair, keyed on"Sender|Receiver".
The breast dataset ships both. cell-metadata/graphclust_10x.csv is 10x's own
graph-based clustering of this run, copied from the analysis/ folder Xenium
Onboard Analysis writes, with nine integer levels: integers are the common case for
cluster ids and the awkward one for a viewer. edge-metadata/example_annotations.csv
holds three per-pair summaries computed from the NICHESv2 file (whether the pair is
autocrine or paracrine, a score tercile, and a score percentile), standing in for the
columns a lab would write about its own pairs.
- Choose xenium_human_breast_2fov and zoom into the edge of the tumour, where the stroma runs through it as a dark band. Set Cell Segments → fill to 55% and outline to 40%, Morphology to 40%.
- Under Cell Color, tick Color cells, choose Cell metadata, then graphclust.
- The legend lists clusters 1 to 9 in numeric order with a swatch each; click a swatch to change its colour, or import palette to load a
category,#hexfile. - Tick Edges at about 55% with width 2 so the signalling graph sits over the clusters, then hold Shift and click a line: the EDGE panel opens with an Annotations block from
edge-metadata/above the mechanisms.
graphclust from a CSV in cell-metadata/, 437 cells in a 258 × 185 µm field at the tumour edge, with every NICHESv2 pair drawn over them at 55%. The viewer recognised nine integer levels as categories rather than a 1–9 gradient; treat as categorical is there to override that call either way. The clusters follow the tissue: the three tumour clusters (red 4, green 3, blue 1) fill the nests, and the purple cluster 5, whose enriched genes are VWF, PDGFRB, POSTN and LRRC15, is the stromal band between them.
1 to 9, not 1.0, even though two cells in the file have no cluster. Right: the EDGE panel for one pair in the stroma; the Annotations block is the row for this pair from edge-metadata/, and below it the seven mechanisms NICHESv2 scored on it.What to notice
- The same column is offered under Cell Filter. Choose graphclust there and untick all but cluster 5: only the stroma remains, drawn at full density, because the filter is applied on the server before sampling.
- Annotation columns also appear in the edge color and Edge Filter menus, so
score_tiercan colour the edges andinteraction_classcan subset them directly. - The clusters carry no names. What each one is enriched for can be read off the transcripts (example 5): cluster 6 for CD163, C1QA and LYZ, cluster 8 for KRT14 and KRT5, cluster 9 for PTPRC. Naming them is the analyst's job, in the CSV.
Open Edge Filter, set Sending cell to graphclust and keep only cluster 5. The edges that remain all leave the stroma; the tissue graph underneath is untouched, so the neighbourhood structure the filter removed is still visible.
4Spots and bins: the array platforms
Classic Visium measures 55 µm spots on a 100 µm hexagonal lattice, each covering one to ten cells; Visium HD tiles the capture area with 2, 8 or 16 µm square bins. Neither has per-molecule coordinates. TissuePlex draws a polygon per unit, a 16-sided circle for a spot and a square for a bin, so colouring, clicking, filtering and NICHESv2 edges all work exactly as they do for cells. The sidebar relabels itself: Spot Segments and Spot Info on Visium, Bin Segments on HD.
- Choose visium_mouse_kidney. Tick Morphology and raise it to about 85%: this one is a brightfield H&E, so it wants to be bright. Set spot fill to 0 and outline to 50% so the stain shows through the rings.
- Tick Edges (100%, width 1), leave the Tissue Graph at 15%, and set both sample sliders to 100%. Keep the colour range on robust 5–95%: spot-level scores are summed over many cells and have a long tail.
- Zoom into the cortex until the lattice resolves and raise offset to 2. Each spot now shows its six neighbours' edges as paired half-arrows converging on its centre.
- Use ⟷ Measure between two adjacent spot centres: the label reads 100 µm, the lattice pitch, which is how the pixel size of this platform is derived (Space Ranger does not record one).
- Choose visium_hd_tiny. The tissue sits in one corner of the frame, because 10x's "tiny" dataset is a corner crop; zoom into it.
- Untick Edges and Tissue Graph, tick Color bins and choose Gene set (selected species). With every gene selected that is total UMI per bin, on an auto range.
Edges on classic Visium connect spots, each a mix of one to ten cells. Say so in a figure legend. The HD bins are closer to single cells but still a grid, not a segmentation.
5Transcripts inside their cells
Imaging platforms record every transcript as a point with a gene name. TissuePlex draws those points where they were detected, over the nuclear stain and inside the cell outlines they were assigned to, coloured by gene, and filters them by gene in the browser without a round trip to the server. The question this answers is the one a histologist asks of an in-situ stain: which cells, exactly, express this?
- Choose xenium_human_breast_2fov. Tick Transcripts and drag its sample to 100%; leave dot at 3 px. Under Cell Segments, drag sample to 100%, fill to 0 and outline to 60%. Tick Morphology at 70% for the DAPI.
- Zoom into the stroma, the darker tissue to the left of the tumour, until single cells are clear, about 200 µm across. Hover a dot: the tooltip names its gene and, on Xenium, its Q-Score. This is figure 5a.
- Under Transcript Species, click select ▼, then
none, and tick LUM, ACTA2, CD68 and PECAM1; or click
import and choose
sample_data/example_lists/breast_stroma_markers.csv. The dots update at once. import palette withbreast_marker_palette.csvgives them the colours used here. This is figure 5b. - Pan right to the edge of the tumour and import
breast_tumour_markers.csv(EPCAM, LUM, MKI67). This is figure 5c.
Every layer at once: one mechanism, its transcripts, and the cells
The layers above were introduced one at a time. On real data the point is to stack them: pick one ligand–receptor mechanism, draw its edges, draw the transcripts of its ligand and its receptor, and colour the cells by an independent clustering. Five layers, each from a different file, in one field 115 µm across.
- Keep the settings of 5a, with Morphology down to 40%, Cell Segments → fill up to 35% and the transcript dot at 4 px.
- Under Cell Color, tick Color cells, choose
Cell metadata, then graphclust. That column
is 10x's own graph-based clustering of this run, read from
cell-metadata/graphclust_10x.csvbeside the dataset; the viewer recognises its nine integer levels as categories and gives each a colour. - Under Transcript Species, select only CXCL12 and CXCR4; give them white
and red with the swatches, or import palette with
breast_cxcl12_palette.csv. - Tick Edges, drag its sample to 100%, set width 2.5, offset 2 and Harpoon, and under LRM Mechanisms click none and tick only CXCL12 → CXCR4. Set the edge legend to robust 5–95%. Zoom in until about 80 cells fill the view.
Reading it from the bottom up:
- DAPI, grey, from the morphology image: where the nuclei are. It is the one layer that is a picture rather than data.
- Cell outlines, blue, from the segmentation: which pixels the instrument assigned to which cell. Every other layer is joined to these by cell id.
- Cell fill, one colour per cluster, from a CSV of analysis results dropped beside the data. Here nine clusters from 10x's pipeline; the tan cluster (cluster 6, 44 of these cells) is enriched for CD163, C1QA, LYZ and ITGAX, the purple one (cluster 5) for VWF, PDGFRB and POSTN. A Seurat or scanpy label column works the same way.
- Transcripts, white for the ligand CXCL12 and red for the receptor CXCR4, each dot at the position it was detected. This is the evidence: the nine cells of cluster 5 in view, the stromal cluster, hold 87 of the 252 CXCL12 dots, while CXCR4 is spread over the macrophage-like cluster 6 and the PTPRC-rich cluster 9.
- Edges, one per sending → receiving pair, from NICHESv2: each line is that pair's score for this one mechanism, drawn from sender to receiver with the harpoon at the receiving end, offset so that A → B and B → A are separate lines. The fan of yellow lines converging on a cell is a cell whose neighbours send it CXCL12 while it expresses CXCR4; the transcripts underneath show why.
Every number in the caption can be checked against the files: the cells and
transcripts against the platform's own output, the clusters against 10x's
analysis/ folder, the edges against edges/niches_rad30.parquet.
Nothing was drawn by hand.
Xenium scores each transcript's decoding quality. Like Xenium Explorer, TissuePlex hides transcripts below Q 20 by default; tick show low-quality (Q < 20) in gray to draw them in gray. The counter counts only what is drawn.
6Side by side
Split mode shows two panels driven by one sidebar, and there are two different questions it answers. Which one you are asking decides what you hold fixed:
- The same mechanisms in two places. Hold the mechanism selection, change the view. This asks is this signalling stronger here or there? The sidebar stays linked, so the two panels cannot drift apart in anything but where they are looking.
- Two sets of mechanisms in the same place. Hold the view, change the selection. This asks which signalling does this structure carry? The sidebar is unlinked for the mechanism lists and nothing else.
In both cases the pair is only readable because of one setting: shared colour scale across panels, on by default. The two panels are coloured through a single window, the union of what each would have chosen on its own, and the legend says shared. Two panels that each auto-range to their own data look comparable and are not.
- Start from the settings of example 1: both sample sliders at 100%, cell fill 12%, Tissue Graph 15%, Edges 100% at width 1, and the edge legend on robust 5–95%. Click ⊞ Split in the left panel's toolbar. The right panel opens on the same dataset with the same settings, and the sidebar gains Panel 1 / Panel 2 tabs above a ticked settings linked — edits apply to both panels box.
- Zoom the left panel into the midline, where the third ventricle holds its choroid plexus between two dense cell layers, and the right panel into the lateral ventricle at the edge of the section. Click ⇔ Match on the left panel so the right one shows the same number of microns across. This is figure 6a.
- Untick settings linked. The sidebar now edits whichever tab
is selected. With Panel 1 selected, click none
in LRM Mechanisms and tick the 31 neuropeptide mechanisms, or click
import and choose
sample_data/example_lists/mouse_brain_neuropeptides.csv. Select Panel 2, click none, and tick the 22 glial support mechanisms, or importmouse_brain_glial_support.csv. Bring both panels to the midline view and ⇔ Match them. This is figure 6b.
settings linked decides what is drawn: untick it to give one panel its own mechanism list, filter or opacity, and use copy panel 1 → panel 2 to push one side's settings onto the other in one step. shared colour scale across panels decides how it is coloured. Leave the second one on for any figure; untick it only when one panel's range is so much narrower that sharing flattens it, and say so in the legend.
7A figure for the paper
A screenshot is limited to the pixels on your screen. Export… redraws the data layers at whatever size you ask for, because they are geometry rather than pixels, and writes the DPI you choose into the file so a journal's resolution check reads it. Here the view is the one from figure 5d: CXCL12 → CXCR4 edges, the two genes' transcripts, cell outlines and 10x's clusters.
- Choose ▭ Rectangle and drag over the region you want. The rectangle stays on the tissue while you pan; it is stored in image coordinates, not screen ones.
- Click Export…. Pick a preset, 3.5in @500 for a single column or 7in @500 for a double, or type a width in pixels. Choose a background, tick scale bar, and click Export PNG.
- For a quick slide, Save PNG saves the panel as shown, image included, at screen resolution.
- Line weight is fixed in output pixels, so export every panel of one figure at the same pixel width or their lines will not match.
- The morphology image is not included in Export…; it cannot be sharper than the source TIFF. Use Save PNG when you need the image, and the vector export for the data layers.
Where to go from here
User manual
Every control, the install steps, and the R commands that produce edges.parquet with NICHESv2.
Edge file format
The column specification for edges.parquet, so any pipeline can produce one.
Datasets and licences
Where each demo dataset comes from, what was trimmed, and further public data to try.