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.

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.

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.
• Edges and the tissue graph — an edge is drawn only when both of its endpoints match. The point of narrowing to two or three cell types is the signalling within that subset, and an edge with one endpoint outside would run off to a cell that is not on screen.
• Transcripts are not filtered. Several platforms ship no transcript-to-cell assignment at all, so there is nothing to match on.

Filtering edges

The Edge Filter inside Edge Data works the same way but on columns of the edge table itself, including annotations from an edge-metadata/ folder — a curation call, a confidence score, a review flag. It composes with the cell filter: set both and you see only the annotated edges among your chosen cells.

This is distinct from the LRM Mechanisms checklist below it. The checklist chooses which mechanisms are scored on every edge; the edge filter chooses which cell pairs are drawn at all.

Transcripts

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

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.

Gene-color assignments can be imported and exported as CSV using the corresponding 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.

Edge Density

The density slider controls what fraction of available edges are rendered. The default is 10%.

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

Tissue Graph

The Tissue Graph 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 density 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 and clamp controls appear below.
• 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.

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.

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 independent side-by-side panels, each with its own pan and zoom position. Use it to compare two tissue regions or to view the same region with different filter settings.

• Click ⊞ Split in the annotation toolbar to enter split-screen mode.
• Click □ Single to return to a single panel.
• Both panels share all layer settings (visibility, color-by, LRM filter, etc.) but have independent pan and zoom positions.

Matching Zoom Between Panels

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

Annotation Tools

The annotation toolbar offers three 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.

The Clear button removes all regions and measurements at once.

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

TissuePlex has a built-in image export that composites the morphology image and all visible data layers into a single PNG file.

Click Save PNG in the annotation toolbar. The file is saved to your Downloads folder as tissueplex_[timestamp].png (or tissueplex_panel1_[timestamp].png in split-screen mode).

Tips for high-quality output

• Zoom in before saving: the export captures the viewer at its current resolution, so a more zoomed-in view contains finer detail.
• Maximize the browser window to increase canvas size.
• Draw annotation regions or measurements before exporting to mark up the area of interest for a figure.
• Reduce opacity on background layers to make the featured layer stand out.
• For higher-resolution output, use Chrome's built-in screenshot: open DevTools (⌘ Option I on Mac, F12 on Windows), press ⌘ Shift P (Mac) or Ctrl Shift P (Windows), type "screenshot", and select Capture screenshot.