TissuePlex User Manual

What You'll Need

Interface Overview

TissuePlex has four main areas:

• The Viewer. The large central area showing the tissue image and all data layers. Pan by clicking and dragging; zoom with the scroll wheel or pinch gesture.
• The Layer Panel. The right-hand panel for controlling layer visibility, color mappings, gene filters, and LRM selections.
• The Annotation Toolbar. A compact bar at the top of the viewer with tools for drawing regions, measuring distances, toggling split-screen mode, and saving images.
• Info Panels. Floating panels that appear when you click on a cell or edge, showing metadata and scores for that object.

Dataset & Image Picker

At the top of the Layer Panel are two dropdowns:

• Dataset: lists all datasets found in your DATA_PATH folder.
• Image: lists the available OME-TIFF files in the dataset. Most Xenium datasets have one.

Switching datasets reloads all layers automatically. The first time each image is viewed, TissuePlex builds a tile pyramid (10–30 seconds); if the canvas looks blank, wait and refresh.

In split-screen mode these dropdowns move into each panel's own header instead, because the two panels can show different datasets and an image or edge file only means something relative to one of them.

Morphology Image

The morphology image is the tissue photograph that forms the base of the viewer. In the Layer Panel, the Morphology row lets you toggle it on or off and adjust its opacity. Reducing opacity can help other data layers stand out more clearly on a dark background.

The image is streamed as a tile pyramid, so it renders sharply at every zoom level without loading the entire file into memory at once.

Cell Segments

The Cell Segments section controls how individual cells are drawn. Each detected cell is shown as a polygon matching its actual measured boundary.

Visibility and Opacity

Separate opacity sliders control the cell fill (solid interior) and outline (border line):

• Use the checkbox next to Cell Segments to show or hide boundaries entirely.
• The fill slider adjusts interior opacity.
• The outline slider adjusts the border line weight.

The sample slider controls what fraction of cell boundaries are loaded. At low zoom it adjusts automatically; raise it when zoomed in to load more cells.

Color By

The Color by dropdown colors each cell by a data value.

Off (default)

Cells shown in a neutral color. Use this to view cell positions without a data overlay.

Gene Set

Colors each cell by the combined expression of a selected set of genes. High-expressing cells appear at the hot end of the color scale; low-expressing cells at the cold end.

• The gene set is defined by the selection in the Transcripts gene filter.
• Choose a color palette: viridis (yellow→purple), plasma (yellow→magenta), magma (yellow→black), or inferno. Viridis is recommended for colorblind accessibility.
• A color legend shows the data range. Use the clamp sliders to restrict the color range to a specific window, useful when outliers at the high end compress the variation across the rest of the dataset.
• The fade to slider sets the fill opacity of the lowest-expressing cells; the fill slider stays the maximum. At the maximum nothing fades. Drag it down to let low-expressing cells recede so the high expressers stand out.

Cell Metadata

Colors each cell by any metadata column, including supplemental columns added to the cell-metadata/ folder.

• Use the field dropdown to select the column.
• Continuous columns (pseudotime, module scores, etc.) use a gradient palette with clamp controls.
• Categorical columns (cluster labels, cell type names, etc.) are assigned distinct colors automatically, one per category, with a legend of editable color swatches.

Treat as Categorical

When you pick a numeric column, a treat as categorical checkbox appears beneath the dropdown. This is the control you want for integer-coded categories.

Cluster IDs are the usual case: fwrite on a Seurat @meta.data writes seurat_clusters as plain integers, so nothing in the file distinguishes "cluster 7" from a measurement. TissuePlex guesses — an integer column with 30 or fewer distinct values is treated as categorical — and the checkbox overrides that guess in either direction:

• Checked — one distinct, editable color per value, with the legend in numeric order, so cluster 10 comes after cluster 2 rather than between 1 and 2.
• Unchecked — a continuous gradient with clamp sliders. Useful for a coded column with few levels that you would rather read as a scale.
• An auto button returns the column to automatic detection.

The choice is remembered per column for the session. It applies to edge metadata too, in the Edge Data section.

Filtering by Metadata

The Cell Filter section restricts the whole view to a subset of your data — one sample, a few cell types, a range of values. Everything outside the subset is simply not drawn.

How to use it

• Pick a column from the dropdown. Any cell metadata column works, including supplemental ones.
• Categorical columns give you a checkbox per value. Tick the ones you want; all and none buttons are provided. With nothing ticked, everything is shown — an empty selection means "no restriction", not "hide everything".
• Continuous columns give you min and max boxes, both optional and both inclusive. The placeholder text shows the column's actual range.
• clear filter removes the restriction.

What the filter affects

• Cell segments — only matching cells are drawn, and only they can be clicked or captured by a region selection.
• Nothing else. The cell filter does not touch edges or the tissue graph — filtering cells and filtering edges are independent actions. To narrow the edges, use the sending and receiving filters described below.
• Transcripts are not filtered. Several platforms ship no transcript-to-cell assignment at all, so there is nothing to match on.

Filtering edges by sending and receiving cell

Edge Filter inside Edge Data has two dropdowns side by side — Sending cell and Receiving cell. Each offers any cell metadata column, the same list the cell filter uses, and each constrains one end of an edge.

• Set one and that end is constrained while the other is free — "everything sent from crypt cells, to anywhere".
• Set both and you get the intersection: senders in one group, receivers in the other. This is how you ask for fibroblast → endothelial signalling and nothing else.

Below the two dropdowns, a third filter works on columns of the edge table itself, including annotations from an edge-metadata/ folder — a curation call, a confidence score, a review flag.

All of these are distinct from the LRM Mechanisms checklist. The checklist chooses which mechanisms are scored on every edge; the filters choose which cell pairs are drawn at all.

The order things happen in

Understanding this makes the controls predictable:

1. every edge in view
2. density — keeps a spatially random fraction
3. the result is the Tissue Graph layer
4. sending, then receiving, then the edge-table filter
5. the result is the Edge Data layer

Because the edge data is filtered from the tissue graph, it can never appear where there is no graph edge beneath it. Both layers respond to the one sample slider and stay aligned as you move it.

Transcripts

The Transcripts layer renders individual detected RNA molecules as colored dots, each colored by gene identity.

Quality Filter (Xenium)

Each Xenium transcript has a Q-Score, the instrument's estimate of how reliably it was decoded. Like Xenium Explorer, TissuePlex hides transcripts with a Q-Score below 20 by default. On a typical run that is about one transcript in ten.

• Tick show low-quality (Q < 20) in gray under the Transcripts layer to show them. They are drawn gray whatever their gene, as in Xenium Explorer.
• The counter includes low-quality transcripts only while they are shown.
• The option appears only for datasets that record a Q-Score (Xenium). Other platforms are unaffected.

Gene Filter

By default, transcripts from all detected genes are shown, each in its own color. To restrict the display to specific genes:

• The current status reads either all N genes or M / N genes selected.
• Click select ▼ (or edit ▼ if a filter is active) to open the gene picker.
• Search by gene name and check or uncheck any gene.
• Click all to remove the filter, or none to start a fresh selection.
• Selected genes have an ✕ button for individual removal.
• Click clear to reset to all genes.

Importing a Gene List

To show a list of genes you already have, such as markers from a Seurat analysis, click import next to the gene count and choose a CSV file. The selection is replaced by the genes in the file. export saves the genes currently shown in the same format, so a selection can be saved and loaded again later.

gene,group
Epcam,epithelium
Lgr5,stem
Muc2,goblet

• The first row must contain a column named gene, in any letter case. Other columns are ignored, so a Xenium Explorer gene-group file (gene,group) imports unchanged.
• Gene names must match the dataset exactly, including letter case: EPCAM does not match Epcam. Names that do not match are skipped.
• If no name in the file matches, nothing changes and a red message explains why. The same happens for a file with no gene header, and for an Excel workbook. Save those with File → Save As → CSV UTF-8.

Gene-color assignments can be imported and exported as CSV with the import palette / export palette buttons, useful for reproducing a color scheme across sessions.

Connectivity Layers

These layers require edges.parquet in the dataset folder (see Step 8). They visualize cell-cell communication as a spatial graph overlaid on the tissue.

Sample

The sample slider, at the top of the Edge Data section, controls what fraction of the available edges are drawn — for the Tissue Graph and the Directed Edges alike, so the two always line up. It works exactly like the sample slider under Cell Segments. The default is 10%.

• At a low sample (1–10%): a sparse graph useful for viewing overall connectivity patterns.
• At a high sample (50–100%): many more edges, revealing densely connected hubs. Rendering may slow for large datasets.

Tissue Graph

The Tissue Graph row, just below the sample slider, is a structural background layer showing which cells are spatial neighbors, independent of any LRM information. Each line indicates spatial adjacency between two cells. Use the checkbox to toggle it and the opacity slider to adjust its visual weight.

Directed Edges

The Directed Edges layer is the quantitative counterpart to the Tissue Graph. Each arrow represents a directed signal from a sending cell to a receiving cell, with appearance determined by the active ligand-receptor mechanisms (LRMs).

When two cells communicate in both directions (A → B and B → A), both arrows are offset from each other, keeping bidirectional signals visually distinct.

Style Controls

Directional

The Directional checkbox renders A → B and B → A as two offset parallel lines. On by default.

Arrowheads

The Arrowheads checkbox adds directional tips at the receiving end of each edge (available only when Directional is on). Two additional controls appear when arrowheads are active:

• arrow scale: adjusts arrowhead size.
• Full / Harpoon: solid triangle or single-sided chevron. Harpoon style mimics the chemistry ⇌ notation and is often cleaner for dense graphs.

Autocrine

The Autocrine checkbox draws autocrine signalling — a cell signalling to itself — as a ring around that cell. NICHESv2 emits one autocrine edge per cell, so on real output expect a ring on every cell that has any self-signal.

Autocrine rings behave exactly like directed edges in every other respect:

• They are colored by the same control and the same scale. Set edge color to LRM Set and the rings are shaded by signal strength alongside the lines; set it to a metadata column and they take that column's colors. One legend describes everything on screen.
• They obey the LRM Mechanisms checklist. Narrow to one mechanism and only the cells with autocrine signal through that mechanism keep their ring.
• They obey the cell and edge metadata filters, and the sample slider.
• Clicking a ring opens the same edge detail panel, listing the mechanisms scored for that self-edge.

Two sliders appear when the checkbox is on:

• ring r: ring radius, in image pixels. Increase it on large tissues where the default is small relative to the field of view.
• ring w: ring line width.

Width and Offset

• width: thickness of all edge lines.
• offset (visible when Directional is on): perpendicular separation between the A → B and B → A lines.

Minimum Strength Filter

The min strength slider hides edges below a total interaction score threshold. Raising it restricts the view to stronger interactions and reduces visual clutter.

Edge Color

The edge color dropdown has three modes:

• Default (uniform): all edges in a single neutral color.
• LRM Set (selected mechanisms): edges colored by total communication score across active LRMs. The color scale adapts to the current viewport. A palette picker, a fade to slider and clamp controls appear below. Fade to is the opacity of the weakest edge: leave it at the maximum and every edge draws at the Edges opacity; drag it down and weak edges become translucent while the strongest keep the full opacity.
• Metadata column: color edges by a metadata field such as sending or receiving cell type. Continuous fields use a gradient palette; categorical fields use distinct colors with a legend.

LRM Mechanisms Checklist

The LRM Mechanisms list shows every ligand-receptor mechanism in your edges.parquet data. Toggle individual mechanisms on or off to focus the visualization.

• A counter shows how many are active (e.g. 488 / 488 active).
• The all and none buttons select or deselect everything.
• Use the search box to filter by gene name (e.g. type "Tgfb" to find all TGF-β mechanisms).
• Hiding an LRM reduces each edge's visible score by that mechanism's contribution; edges whose score reaches zero are hidden.

Importing a Mechanism List

Click import in the checklist header and choose a CSV file. Only the mechanisms in the file stay active; every other mechanism is unchecked. export saves the active mechanisms in the same format. Either of two layouts is accepted:

lrm
Wnt5a|Fzd1
Notch1|Dll4

ligand,receptor
Wnt5a,Fzd1
Notch1,Dll4

• The first row must contain an lrm column, or both a ligand and a receptor column, in any letter case. If both layouts are present, lrm is used.
• Names must match the edge file exactly, including letter case and direction: Fzd1|Wnt5a is a different mechanism from Wnt5a|Fzd1 and will not match.
• Receptors made of several subunits contain commas, so put them in quotes: Fn1,"Itgav,Itgb3". Excel adds the quotes itself when it saves a CSV.
• If nothing in the file matches, or the header is missing, nothing changes and a red message explains why.
• The imported list belongs to one edge file. Switching the edge source or the dataset makes every mechanism active again; import the file again if you need it.

Clicking to Explore

Clicking on cells or edges opens floating info panels with detailed information.

Clicking on a Cell

Click inside a cell to open the Cell Info Panel, which shows the barcode ID, all metadata values for that cell, and the current color-by value highlighted. Click on empty canvas to dismiss.

The Local Neighbourhood

With a cell selected, show local neighbourhood at the bottom of the info panel reveals everything that cell is connected to in the tissue graph. The canvas marks the clicked cell in white, its connected neighbours in yellow, and draws a circle at the distance of the furthest one. The panel reports:

• neighbours and local edges — how many cells it touches, and how many directed edges that is;
• radius in µm, so the reach can be quoted without measuring it off the screen;
• composition — the neighbours broken down by whichever metadata column you are colouring cells by;
• mechanisms — the strongest LRMs across its edges.

Clicking on an Edge or Tissue Graph Line

Click on any line in the Tissue Graph or Directed Edges layer to open the Edge Info Panel, showing the sending and receiving cell barcodes and the top-scoring LRMs for that edge.

Split-Screen Mode

Split-screen mode divides the viewer into two side-by-side panels. Each has its own pan and zoom, and each can show a different dataset — so you can put two samples, two platforms, or two timepoints next to each other. Both panels can also show the same dataset rendered two different ways.

• Click ⊞ Split in the annotation toolbar to enter split-screen mode.
• Click □ Single to return to a single panel.
• In split mode each panel gets its own dataset, image and edge-source picker in its header, since those only mean something relative to one dataset.

Choosing Which Panel You Are Editing

The sidebar drives both panels. At the top of it, Panel 1 / Panel 2 tabs choose which one your edits apply to, and a checkbox below them controls whether they are linked:

• Linked (the default): every change — opacity, palette, color-by, filters, mechanism selection, edge geometry — applies to both panels at once. This is what makes a side-by-side comparison actually comparable.
• Unlinked: edits apply only to the tab you are on. Use this to show cluster coloring on one side and gene expression on the other, or two palettes, or two filters.

Copying Settings From One Panel to the Other

While the panels are unlinked, a copy panel 1 → panel 2 button appears under the checkbox. It copies every display setting from the tab you are on to the other panel in one go, and then leaves the panels independent again — so you can establish a common baseline and diverge from it.

Settings that name something the other dataset does not have are dropped rather than copied: a metadata filter on a column it lacks, a gene allowlist with no genes in common, mechanisms absent from its edge file. Color range limits also reset when the two panels show different datasets, because a range measured in one dataset's units is meaningless in another's.

Matching Zoom Between Panels

The ⇔ Match button sets the other panel to your current panel's zoom while each panel stays centered on its own region.

Color Scales Across Panels

The shared colour scale across panels checkbox, on by default, makes both panels map color through one range computed across both. Leave it on for any figure. Two panels that each auto-scaled to their own data look comparable and are not — one panel's yellow might be 40 counts and the other's 4,000. Turn it off only when one panel's range is so much narrower that sharing flattens it, and say so in the legend.

Annotation Tools

The annotation toolbar offers four interaction modes:

• Pan: the default mode. Click and drag to pan.
• ⬡ Region: draw a polygon on the tissue. Click to place vertices; double-click to close. Regions are colored and labeled, and remain visible on top of all data layers.
• ⟷ Measure: click two points to measure the distance between them in micrometers.
• ▭ Rectangle: drag a rectangle to frame an area for high-resolution figure export. See Saving Images.

The Clear button removes the regions, measurements and export rectangle belonging to that panel — each panel has its own toolbar, so clearing one leaves the other's work alone.

Exporting Cells Within a Region

Each drawn region appears in the Layer Panel's Regions list. The export button saves a CSV of the barcodes of all enclosed cells, for downstream analysis in R.

Saving Images

There are two ways to save an image, for two different purposes.

Save PNG — a quick screenshot

Click Save PNG in the annotation toolbar. This composites the morphology image and all visible data layers exactly as shown, at your screen's resolution, and saves it as tissueplex_[timestamp].png (or tissueplex_panel1_[timestamp].png in split-screen mode). Good for slides, notes and sharing a view. Its resolution is limited to the size of the viewer on screen, so it is not usually enough for print.

Export… — a publication figure

Click Export… to render the data layers again at whatever resolution you ask for. Because the layers are geometry — lines, polygons and points — they are redrawn at the output size rather than enlarged, so they stay sharp at any resolution.

1. Optionally choose ▭ Rectangle and drag to frame the area you want. Without a rectangle, the whole current view is used.
2. Click Export….
3. Set the output width in pixels and the DPI, then click Export PNG.

Options

• Background — black by default, matching the viewer. Transparent is useful for compositing in Illustrator or Photoshop; white suits a printed page. Some submission systems flatten transparency unpredictably, so choose a solid background if you are unsure.
• Scale bar — drawn in a margin band below the plot rather than over the tissue, at a rounded length (50 µm, 100 µm, 500 µm…) computed from the dataset's pixel size.
• Include annotations — off by default; turn it on to draw your regions and measurements into the figure.

Points to watch

• Sampling is not changed for you. The figure shows exactly what the panel shows, including the edge sample and transcript sampling in effect. If you want the full edge set in a figure, raise the sample slider before exporting — and record the value you used in the legend.
• Keep the rectangle on screen. Data is loaded for the current view, so if you pan away from your rectangle the export would be missing whatever is off screen. The dialog warns you when this happens.
• Line weights are preserved, not re-tuned. Strokes are scaled so the export matches what you approved on screen. A weight that reads well on a monitor may still look heavy or thin in print — adjust edge width for the figure and export again.
• If you rotate after drawing the rectangle, the export keeps the orientation the rectangle was drawn at. Redraw it to use the new angle.