TissuePlex User Manual

Setup and operation guide

TissuePlex is a web-based viewer for spatial transcriptomics data. It layers cell positions, gene expression, cell-to-cell signaling, and custom analysis results on top of a tissue morphology image when one is available, running in a browser on your local machine.

No programming experience is required. This guide covers installation, data setup, and every control in the interface.

Prefer to see it first? The worked examples are seven short, screenshot-led tours on the demo datasets.

Six platforms are supported — Xenium, Visium, Visium HD, MERSCOPE, CosMx and seqFISH — and TissuePlex works out which one it is looking at from the files in the folder. The examples below use Xenium; everything transfers, and the platform-specific differences are called out where they matter.

By the end of this guide you will have: TissuePlex installed and running, your dataset loaded, cell-cell communication edges from NICHESv2 visible, and custom analysis results available as cell color overlays.

What You'll Need

A Mac or Windows computer

TissuePlex runs in the browser. No special graphics card is needed.

Your platform's output folder

Whatever your instrument or pipeline produced, unmodified. For Xenium that is the folder containing experiment.xenium, morphology.ome.tif and transcripts.parquet; for the Visium platforms it is the contents of Space Ranger's outs/. See the platform table in step 5. The image is optional: a dataset without its morphology or DAPI still shows its cells, transcripts and edges, on a plain frame.

An internet connection

Required for the initial download steps only. After setup, TissuePlex runs on your local machine.

About 30–45 minutes

For initial setup. Subsequent launches take seconds.


Part I

Getting TissuePlex Running

Install two programs (Git and Docker), download TissuePlex, and run it for the first time. These are one-time steps; after setup, launching TissuePlex takes a single command.

1

Install Git

Git downloads and manages software repositories. It lets you pull TissuePlex updates with a single command.

On a Mac

Open Terminal (Applications → Utilities, or ⌘ Space and type "Terminal") and run:

git --version

If you see git version 2.x.x, Git is already installed; skip to Step 2. If a pop-up offers to install "Command Line Developer Tools" or "Xcode Command Line Tools", click Install and follow the prompts.

On Windows

Go to git-scm.com, download the Windows installer, and run it. Accept the default settings. When it finishes, you will have a program called Git Bash. Use Git Bash wherever this guide says "Terminal".

Tip: Verify the install by running git --version in Terminal or Git Bash. A version number should appear.
2

Install Docker Desktop

Docker runs TissuePlex in an isolated container that bundles all required software (Python, databases, web server). Install Docker once; no other dependencies are needed on your machine.

Go to docker.com/products/docker-desktop and download Docker Desktop for your operating system. Install it as you would any other application.

Important: After installing, open Docker Desktop and wait for it to finish starting. The Docker whale icon in your menu bar (Mac) or system tray (Windows) will stop animating when it is ready. TissuePlex requires Docker Desktop to be running.

Recommended: increase Docker's memory limit

Mac: in Docker Desktop, go to Settings (gear icon) → Resources. If your machine has 16 GB of RAM or more, set the memory limit to at least 8 GB, then click Apply & Restart.

Windows: Docker Desktop runs on WSL 2, which must be enabled (the installer offers to do this; it also needs virtualization turned on in your PC's firmware). There is no memory slider under Resources. To raise the limit, create a text file called .wslconfig in your user folder (C:\Users\yourname) containing:

[wsl2]
memory=8GB

then quit and restart Docker Desktop.

Tip: Docker Desktop must be running each time you use TissuePlex. Consider adding it to your login items (Mac: System Settings → General → Login Items) so it starts automatically.
3

Download TissuePlex

Open Terminal (Mac) or Git Bash (Windows). Navigate to the folder where you want to keep TissuePlex, for example:

cd ~/Documents

Then clone the repository:

git clone https://github.com/RaredonLab/TissuePlex.git
cd TissuePlex

This creates a TissuePlex folder and downloads all the code into it. The second command moves your terminal into that folder.

Tip: To update TissuePlex later, navigate back to this folder (cd ~/Documents/TissuePlex), run git pull, then docker compose up --build. The version badge at the foot of the right-hand panel turns red when the browser is showing an older build than the backend is running — a sign to hard-refresh the page or rebuild as described below.
Windows users: After a git pull, Docker Desktop sometimes reuses a stale build cache and serves an outdated version of the app, resulting in a black screen with an error about a wrong MIME type in the browser console. If this happens, force a clean rebuild:
docker compose build --no-cache
docker compose up
4

First Launch

TissuePlex comes with four small demo datasets, one per platform family, so you can verify the installation before loading your own data:

  • mouse_ileum_tiny — Xenium, 36 cells, with example cell-metadata/ and edge-metadata/ folders and two extra edge sets to switch between;
  • visium_hd_tiny — a real 10x Genomics Visium HD mouse-brain subset (CC BY 4.0);
  • visium_tiny — a synthetic classic Visium slide, 252 spots;
  • seqfish_synthetic — a synthetic seqFISH (Spatial Genomics) region.

Larger real datasets for Xenium (human breast, two fields of view), MERSCOPE, CosMx and classic Visium (mouse kidney) are not included in the download because of their size; python3 sample_data/fetch_samples.py downloads them into sample_data/ once you have Python installed. The demo gene and mechanism lists used later in this guide are in sample_data/example_lists/.

With Docker Desktop running, run the following from inside the TissuePlex folder:

docker compose up --build

The first run downloads and builds all container images, which takes 5–15 minutes depending on internet speed. A large amount of build output will scroll by. When you see a line like Uvicorn running on http://0.0.0.0:8000, TissuePlex is ready. Leave this terminal window open while you use it; you can close and reopen the browser tab at any time.

Open Chrome or Firefox and go to:

http://localhost:3000

The TissuePlex viewer should load with the first demo dataset, and the Dataset dropdown at the top of the right-hand panel lists the other three. The canvas starts dark with the cell outlines drawn: the Morphology, Transcripts and Edges layers are off by default — tick their checkboxes to turn them on.

Note: The first time a dataset is opened, TissuePlex builds a tile pyramid from the morphology image, which takes 10–30 seconds. If the canvas looks blank, wait and refresh.

Stopping TissuePlex

Press Ctrl + C in the terminal to stop the process, then run:

docker compose down
Tip: On subsequent launches, docker compose up (without --build) is faster. Add --build after a git pull to rebuild with the latest changes.
5

Load Your Dataset

TissuePlex reads from a parent folder containing one or more dataset subfolders. The expected layout:

/Users/yourname/xenium-data/ <- this is your DATA_PATH my-experiment-2024/ <- your dataset folder experiment.xenium <- Xenium platform sentinel morphology.ome.tif transcripts.parquet cells.parquet ...

Set DATA_PATH to the parent folder. Multiple dataset folders are supported; TissuePlex lists them all in the interface.

Mac or Linux

DATA_PATH="/Users/yourname/xenium-data" docker compose up --build

Windows (Git Bash)

DATA_PATH="C:/Users/yourname/xenium-data" docker compose up --build

If you use PowerShell instead of Git Bash, set the variable first:

$env:DATA_PATH="C:\Users\yourname\xenium-data"; docker compose up --build
Important: The path must be absolute (starting from the filesystem root) and must not contain a colon other than a Windows drive letter — a network mount path such as /Volumes/server:share/… will not work. On Windows in Git Bash, use forward slashes (/).

TissuePlex detects the platform from the files present in each subfolder:

PlatformRequired file in the dataset folderUnit
Xenium (10x Genomics)experiment.xeniumcell
Visium HD (10x Genomics)binned_outputs/square_*um/bin
Visium (10x Genomics)spatial/scalefactors_json.json plus a tissue_positions filespot
MERSCOPE (Vizgen)cell_by_gene.csv or cell_metadata.csvcell
CosMx (Nanostring)a file ending in _tx_file.csvcell
seqFISH (Spatial Genomics)a file matching *_CellCoordinates*.csvcell

Folders without a matching sentinel file are silently skipped.

Point at the right folder. For the 10x array platforms, the dataset folder is the contents of Space Ranger's outs/ directory — the folder that directly contains spatial/ — not its parent.

The interface adapts to whichever platform is loaded. Panels are relabeled to match the unit — a Visium dataset says Spot Segments, Spot Color, Spot Filter and Spot Info where a Xenium one says Cell, and Visium HD says Bin. (In split-screen mode with two different unit types, the label becomes the neutral unit.) Layers a platform cannot serve are hidden entirely: the two Visium platforms measure counts per spot or bin rather than per molecule, so the Transcripts layer does not appear for them.


Part II

Enriching Your Data

TissuePlex can display enriched data alongside the standard platform output: cell-cell communication edges from the NICHESv2 R pipeline, and custom cell metadata such as clustering labels or pseudotime scores. Both are optional; the core viewer works without them.

6

The NICHESv2 Edge Layer

TissuePlex can render cell-cell communication as a spatial graph overlaid on the tissue. Each line represents a pair of neighboring cells; lines are colored and filtered by ligand-receptor mechanisms (LRMs): the molecular signals passing from one cell to another.

This data comes from NICHESv2, a Raredon Lab R pipeline that scores every spatially neighboring cell pair for every ligand-receptor interaction in the dataset.

The output TissuePlex reads is a single file, edges.parquet, placed in the dataset folder alongside experiment.xenium. When it is present, the LRM Mechanisms checklist appears inside the Edge Data section and lines are drawn on the tissue. When it is absent, the Edge Data controls are still shown but draw nothing, and all other features work as normal.

Note: Running NICHESv2 requires R and a few packages, and can take some time for large datasets. The two steps below cover the installation and the one command that produces the file.
7

Install R and RStudio

R is a programming language widely used in biology and statistics. RStudio is a graphical interface for writing and running R code.

Install R

Go to cran.r-project.org and download the latest version of R for your operating system.

Install RStudio

Go to posit.co/download/rstudio-desktop and download the free RStudio Desktop version. Install it after R.

Install required R packages

Open RStudio. In the Console panel, paste the following and press Enter:

install.packages(c("arrow", "Matrix", "jsonlite", "remotes", "BiocManager"))
BiocManager::install("rhdf5")
remotes::install_github("RaredonLab/NICHESv2", ref = "dev")

Installation may take several minutes. The last line installs NICHESv2 from its dev branch; that matters, because the export_to_TissuePlex() function that writes the edge file exists only there.

Tip: R, RStudio, and installed packages persist between sessions.
8

Run NICHESv2 and Export Edge Data

The TissuePlex download includes a ready-made script for each platform in its r/ folder. Each one reads the dataset, runs NICHESv2 to score every neighboring cell pair, and writes edges.parquet into the dataset folder. You run it from Terminal (or Git Bash), not from inside RStudio. For a Xenium dataset:

cd ~/Documents/TissuePlex
Rscript r/niches_xenium.R /path/to/your/xenium-dataset --species human --rad 30
  • --species is human, mouse, rat or pig; it selects the ligand-receptor database.
  • --rad is the neighborhood radius in microns: two cells closer than this are scored as a communicating pair.
  • The other scripts work the same way: niches_visium.R, niches_visium_hd.R, niches_merscope.R, niches_cosmx.R and niches_seqfish.R. The r/README.md file in that folder describes each one.

The resulting structure:

my-experiment-2024/ experiment.xenium morphology.ome.tif transcripts.parquet cells.parquet edges.parquet <- newly created by NICHESv2
Several edge sets on one tissue. Add --out /path/to/your/xenium-dataset/edges/radius50.parquet to write the result into an edges/ subfolder instead. Every file in that folder becomes a choice in the Edge source dropdown, so you can compare two radii or two scoring settings on the same cells without copying the dataset.
Important: This step can take a long time for large datasets. If the script stops with a message about scorable pairs, the gene panel has no complete ligand-receptor pair for that species; that is a property of the panel, not an error in your data.

Verify the result

Restart TissuePlex and open the dataset. The LRM Mechanisms checklist should appear inside the Edge Data section, and ticking the Edges layer should draw lines on the tissue. If not, confirm that edges.parquet is directly inside the dataset folder at the same level as experiment.xenium.

9

Add Custom Cell Metadata

TissuePlex can color cells by any metadata you generate: clustering labels, cell type annotations, pseudotime scores, or gene module scores. Place a CSV in a subfolder named cell-metadata inside the dataset directory. Every column is automatically available in the color-by dropdown.

A typical R workflow

library(Seurat)

# Load your Xenium data
xenium_obj <- LoadXenium("/path/to/your/xenium-dataset")

# --- Run your analysis here ---
# For example, cluster the cells:
xenium_obj <- NormalizeData(xenium_obj)
xenium_obj <- FindVariableFeatures(xenium_obj)
xenium_obj <- ScaleData(xenium_obj)
xenium_obj <- RunPCA(xenium_obj)
xenium_obj <- FindNeighbors(xenium_obj)
xenium_obj <- FindClusters(xenium_obj, resolution = 0.5)

# Extract the columns you want to export
metadata_to_export <- xenium_obj@meta.data[, c("seurat_clusters")]
# Add as many columns as you like; they all appear in TissuePlex.

# Create the cell-metadata folder if it does not already exist
dir.create(
  file.path("/path/to/your/xenium-dataset", "cell-metadata"),
  showWarnings = FALSE
)

# Save the file (cell barcodes become the row names automatically)
write.csv(
  metadata_to_export,
  file.path("/path/to/your/xenium-dataset", "cell-metadata", "my_clusters.csv")
)
Note: Row names must match the cell barcodes in the Xenium output. Loading data via LoadXenium() ensures the barcodes in xenium_obj@meta.data are already correct. Ask a lab member for guidance on clustering parameters appropriate for your dataset.

Resulting folder structure:

my-experiment-2024/ experiment.xenium morphology.ome.tif transcripts.parquet cells.parquet edges.parquet cell-metadata/ <- create this folder in R or manually my_clusters.csv <- your exported metadata

After adding the file, restart TissuePlex. Metadata columns appear automatically in the Cell Color section: tick Color cells, choose Cell metadata from the mode dropdown, then pick the column. They also appear in the Cell Filter dropdown.

Tip: Multiple CSV files are supported in cell-metadata/. TissuePlex merges them on the barcode key; each file can contain different columns.

The same idea for cell pairs: edge-metadata/

To annotate edges rather than cells — a curation call, a confidence score, a review flag — put a CSV in a folder named edge-metadata next to edges.parquet. Its key column is the edge name, SendingCell|ReceivingCell; R's write.csv() with that as the row names works unchanged. The columns appear in the edge color and edge filter dropdowns, and show as an Annotations block when you click an edge. The xenium_human_breast_2fov demo dataset ships both folders, and worked example 3 walks through them.


Part III

Using TissuePlex

This section covers every control in the TissuePlex interface.

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, framing and saving images, rotating the view, and (on the left-hand panel only) switching split-screen mode on and off.
  • Info Panels. The Cell Info panel is docked at the bottom of the Layer Panel and reads Click a cell to inspect until you do. The Edge Info panel floats over the bottom-right of the viewer when you click an edge.

Dataset & Image Picker

At the top of the Layer Panel are up to three dropdowns:

  • Dataset: lists all datasets found in your DATA_PATH folder.
  • Image: appears only when the dataset has more than one image. It lists every TIFF or PNG in the dataset folder and one level below it — for Xenium, the morphology_focus/ channels alongside the main morphology.ome.tif.
  • Edge source: appears only when the dataset has more than one edge file (see Step 8).

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 a strip at the bottom-left of each panel instead, because the two panels can show different datasets and an image or edge file only means something relative to one of them.

Status Badges

A Computing… badge appears at the bottom-right of the viewer while data for the current view is loading. A red ⚠ … failed badge means a request to the backend failed (see Troubleshooting). At the foot of the Layer Panel, a small TissuePlex v… badge shows the version; it turns red if the page in your browser is older than the backend, which happens after an update until you hard-refresh or rebuild.

Changing a panel's dataset clears the settings that name a column, gene or mechanism — metadata filters, the color-by field, the gene selection, the mechanism checklist. It has to: those names come from the dataset you just left. Sliders, palettes and layer visibility are kept. While the panels are linked, this clears both; unlinked, only the panel you changed.

Tip: TissuePlex works best in Google Chrome or Firefox. Switch to Chrome if you see visual glitches in Safari.

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. It starts off, so a freshly opened dataset shows its cells on a dark background; tick the box to see the tissue. Reducing opacity can help other data layers stand out more clearly.

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 (100% by default).
  • The outline slider adjusts the opacity of the border line (0% by default, so outlines are invisible until you raise it).

The sample slider controls what fraction of cell boundaries are loaded. It starts in auto mode (green tag), which aims for about 5,000 cells at any zoom; dragging it switches to a fixed fraction, and the ↺ button returns it to auto. The counter beside the layer name shows how many cells are drawn out of how many are in view, and turns green at 100%.

Tip: Outlines at full opacity with fill at 5–10% gives a clean view of cell shape while keeping the morphology image visible — the opposite of the defaults, which favor solid fills for color overlays.

Cell Color

The Cell Color section, just below Cell Segments, colors each cell by a data value. Tick Color cells, then choose a mode from the dropdown beside it.

Off (default)

With Color cells unticked, cells are 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 Transcript Species section (see Transcripts). On Visium and Visium HD, which have no transcript layer, every gene in the panel is summed.
  • 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 range in use. By default it is auto: the lowest and highest value currently drawn, so the legend's endpoints are exactly the colors' endpoints, and it follows you as you pan or change the selection. When a few extreme values own most of the palette, switch auto to robust 5–95%: the window becomes the 5th to 95th percentile of what is drawn, the tails saturate, and the legend says so. Drag the lo or hi slider to fix a window instead, useful when a few outliers compress the variation across everything else; the legend then says clamped, the window stays put until you click reset range, and a figure legend should quote it.
  • 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 column dropdown (— select column —) to pick the column.
  • Continuous columns (pseudotime, module scores, etc.) use a gradient palette with the same lo / hi range sliders.
  • Categorical columns (cluster labels, cell type names, etc.) are assigned distinct colors automatically, one per category, with a legend. Click any swatch in the legend to change that category's color; import palette / export palette save and load the whole set as a CSV, and reset restores the automatic colors.

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 range 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.
Why the subset stays dense. The filter is applied on the server, before sampling. If it were applied afterwards you would see a sample of a subset — narrowing to a cluster holding 5% of cells while the sampler is at 10% would draw about 0.5% of the tissue. Filtering first means the subset renders at full density, and the shown/total counter beside Cell Segments updates to describe the subset.

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 signaling and nothing else.

These are independent of the Cell Filter above. Narrowing the cells you draw does not narrow the edges, and vice versa. An edge may therefore terminate on a cell that is not currently drawn — that is intended, so the graph structure can be read on its own terms.

Below the two dropdowns, a third dropdown filters on columns of the edge table itself, including annotations from an edge-metadata/ folder — a curation call, a confidence score, a review flag. It works like the cell filter: checkboxes for a categorical column, min / max boxes for a continuous one, and clear filter to remove it.

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. sample — 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 Edges 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. The layer is off by default; tick its checkbox to draw it. Hover over a dot to see its gene name (and, on Xenium, its Q-Score). The dot slider sets the largest radius a dot is drawn at, in screen pixels (3 by default); zoomed out, dots are smaller than that, so the slider matters when you are close enough to see single cells.

Note: Transcripts draw at every zoom level. When zoomed out, a random sample is shown (the sample slider, 10% by default, at most 200,000 dots). The sample is spread evenly across the view, and the same dots stay put as you pan. The counter next to the layer name shows how many are drawn out of how many are in view.

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.

Transcript Species — the gene filter

By default, transcripts from all detected genes are shown, each in its own color. The Transcript Species section restricts 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; ▲ closes it again.
  • Type in the filter genes… box to search, and check or uncheck any gene.
  • The swatch beside each gene is its dot color. Click it to choose another; reset appears once any color has been changed and restores the automatic colors.
  • 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.
Note: Keep list files outside the dataset folder. A CSV placed in the dataset folder itself is read as cell metadata (see Add Custom Cell Metadata). The demo lists for mouse_ileum_tiny are in sample_data/example_lists/.

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.

Tip: The gene selection is shared with the "Gene set" cell coloring mode. Select marker genes, tick Color cells and choose "Gene set", and both the per-cell expression overlay and individual transcript locations will reflect that selection simultaneously.

Edge Data

The Edge Data section holds everything to do with cell-cell connectivity. Its 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 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.
Tip: Start at 10%, then increase in specific regions of interest to see more detail.

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. It is on by default at 5% opacity, which is deliberately faint; raise it to see the graph on its own.

The tissue graph is the complete set of neighbor pairs in view. No filter ever removes any of its lines — it is shown or hidden, nothing else. Only the sample slider changes how many are drawn, and that applies equally to the Edges on top, so the two always align.

Use opacity, not the sample, to make it recede behind the edge data. Lowering the sample removes lines from a layer whose whole purpose is to show the complete structure.

Edges

The Edges row, below Tissue Graph in the Edge Data section, is the quantitative counterpart to the Tissue Graph. Each line represents a directed signal from a sending cell to a receiving cell, with appearance determined by the active ligand-receptor mechanisms (LRMs). The layer is off by default; tick its checkbox to draw it. Its opacity slider starts at 25%.

When two cells communicate in both directions (A → B and B → A), the two lines can be offset from each other to keep bidirectional signals visually distinct.

Style Controls

Directional

The Directional checkbox, on by default, treats A → B and B → A as two separate lines. They sit on top of each other until you raise offset (below), which starts at 0.

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: adjusts arrowhead size (1.00× by default).
  • 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 signaling — a cell signaling 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 sending, receiving and edge-table filters, and the sample slider. (Like all edges, they ignore the Cell Filter.)
  • 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.
Seeing nothing? The Edges layer must be on for rings to appear — Autocrine lives inside it. Also check the sample slider: at the default 10% only a tenth of edges, rings included, are drawn.

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. 0 by default; raise it to see the two directions as parallel lines.

Edge Color

The edge color dropdown has three modes:

  • LRM Set (selected mechanisms) — the default: 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.
  • Default (uniform): all edges in a single neutral color.
  • Metadata column: color edges by a column of the edge file or of an edge-metadata/ folder, 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, written as Ligand → Receptor. 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 filter mechanisms… 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.
Example: To isolate TGF-β signaling, click none to hide all LRMs, search for "Tgfb", then re-enable only those mechanisms.

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 fills in the info panels with details about that object. A click on empty canvas clears both selections.

Clicking on a Cell

Click inside a cell to fill the Cell Info panel at the bottom of the Layer Panel. It shows the cell's barcode, position, transcript and total counts, cell and nucleus area, its expression of the selected genes, and — when cells are colored by a metadata column — that column's value, highlighted. Other metadata columns are not listed here; use the color-by or filter dropdowns to see them.

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 neighbors in amber, 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 neighbors broken down by whichever metadata column you are coloring cells by (the panel says so if cells are not currently colored by one);
  • mechanisms — the strongest LRMs across its edges.

The circle is a convenience, not the answer. Connectivity is not evenly spread — a cell at the edge of a tissue has neighbors on one side only — so the circle usually contains cells it is not connected to. The amber marks are the neighborhood; the circle only shows how far it reaches.

The summary is computed on the full data, so it is unaffected by the sample slider, by the sending and receiving filters, or by how far you are zoomed in. It describes the tissue, not the current view. Clicking another cell replaces it; hide highlight removes it.

Clicking on an Edge or Tissue Graph Line

Click on any line in the Tissue Graph or Edges layer (or an autocrine ring) to open the floating Edge Info panel. It shows the sending and receiving cell barcodes, every mechanism scored on that edge with its score and share of the total, and — if the dataset has an edge-metadata/ folder — an Annotations block with that edge's values.

Tip: When edges and cells overlap, a normal click selects the cell. Hold Shift to prioritize edges instead. A plain click on empty space deselects.

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 left-hand panel's annotation toolbar to enter split-screen mode.
  • Click □ Single in the same place to return to a single panel.
  • In split mode each panel gets its own dataset, image and edge-source pickers in a strip at its bottom-left, since those only mean something relative to one dataset. The Layer Panel's header reads Comparing 2 panels — pick each dataset in its header.

Choosing Which Panel You Are Editing

The Layer Panel 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 — reading settings linked — edits apply to both panels or editing panel N only — 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.

Switching the checkbox back on re-syncs both panels to the tab you are currently on. That is deliberate: a control labeled "linked" over two visibly different panels would not be telling you the truth. Pick the tab whose look you want to keep before you re-link.

Copying Settings From One Panel to the Other

While the panels are unlinked, a copy panel 1 → panel 2 button (or copy panel 2 → panel 1, depending on the tab you are on) 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.

Match works in microns, not pixels, so the same physical distance spans the same width on screen in both panels — exactly as a scale bar would. This matters when the panels hold different platforms: 20% of a 6.5 mm Visium capture area and 20% of a 55 µm seqFISH region differ by more than fifty-fold.

Color Scales Across Panels

The shared colour scale across panels checkbox in the Cell Color section, on by default, makes both panels map color, cells and edges alike, through one window: the union of the windows each panel would have chosen on its own (full or robust, per the legend's auto mode). The legend then reads shared, and a clamp you set by hand still wins. 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 (a double-click with fewer than three vertices cancels the polygon). Each region gets its own color and remains visible on top of all data layers; its name and cell count appear in the Layer Panel's Regions list rather than on the canvas.
  • ⟷ 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.

⬡ Region and ▭ Rectangle do different things. A region selects cells, and its output is a CSV of barcodes. A rectangle frames an image, and its output is a PNG. Drawing a region does not affect what an export contains, and vice versa.

The Clear button, which appears once there is something to clear, 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.

Rotating the View

The toolbar's ⟲ and ⟳ buttons rotate the panel by 90° either way, and the box between them takes any angle from 0 to 359°. Both the image and every data layer rotate together, so a tissue can be set upright for a figure. A × button appears beside the angle whenever it is not zero and resets it. Each panel rotates independently.

In split-screen mode, regions and measurements belong to the panel they were drawn in and appear only there. They are stored in that dataset's coordinates, so a region drawn on one tissue would land somewhere meaningless if it were drawn on the other. Exported cell lists and measured distances likewise resolve against the panel that produced them.

Exporting Cells Within a Region

Each drawn region appears in the Layer Panel's Regions list with its cell count. The CSV button saves the barcodes of all enclosed cells as [dataset]_region_[n].csv, for downstream analysis in R; the × beside it removes that region.

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…. The Export figure dialog opens.
  3. Set width (px) and DPI (metadata), or click one of the preset buttons (3.5in @500, 7in @500, 7in @600), then click Export PNG. The dialog shows the resulting output size in pixels and inches as you type, warns above 8,000 px, and confirms with Saved W × H px. The file is named tissueplex_[dataset]_[timestamp].png.

Resolution is pixels, not DPI. A PNG contains pixels; DPI only means something once you fix a print width. So decide the width in inches your figure will be printed at, multiply by the DPI you need, and use that as the pixel width:

  • Single column, 3.5 in at 500 DPI → 1750 px
  • Double column, 7 in at 500 DPI → 3500 px
  • Double column, 7 in at 600 DPI → 4200 px

Buttons for these three are in the dialog. The DPI you enter is also written into the PNG's metadata, which is what journal submission systems read when they check a figure's resolution.

Options

  • background — black (as shown) by default, matching the viewer; also transparent and white. 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 ⬡ Region polygons and ⟷ Measure lines into the figure. "Annotations" here means only those drawn shapes, not cell metadata or clusters; with nothing drawn, the box changes nothing.
  • clear ▭ — removes the framing rectangle from inside the dialog.

The morphology image is not included in Export…. It is a photograph, so unlike the data layers it cannot be redrawn at a higher resolution than it was acquired at, and including it would cap the whole figure at the source image's detail. Use Save PNG if you need the tissue image in the picture, or export the data layers on a transparent background and composite them over the morphology yourself.

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 in the Edge Data section 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 fixed in output pixels. A line is the same number of pixels wide whatever size you export at, so the larger the export, the thinner the lines look relative to the tissue, and two panels exported at different widths will have mismatched line weights. Export every panel of one figure at the same pixel width. To make edges clearer, raise the Edges opacity, lower the sample slider, or switch the Tissue Graph off; those have a far larger effect than the width slider.
  • If you rotate after drawing the rectangle, the export keeps the orientation the rectangle was drawn at. Redraw it to use the new angle.

Help

Troubleshooting

ProblemWhat to do
Dark canvas with cell outlines but no tissue image The Morphology layer is off by default; tick its checkbox. If the image still does not appear, TissuePlex may be building the tile pyramid: wait 15–30 seconds and refresh the page.
Blank or gray canvas that never loads, even after a refresh The cached tile pyramid may be corrupt (for example after the computer slept mid-build). Stop TissuePlex, run docker compose down -v to clear the cache, then start it again; the pyramid is rebuilt on the next open.
Black screen after updating (especially on Windows) Docker reused a stale build cache. Force a clean rebuild:
docker compose build --no-cache && docker compose up
My dataset doesn't appear in the dropdown Check that DATA_PATH points to the parent folder and that the dataset folder contains the platform sentinel file (e.g. experiment.xenium). A fresh download lists only the four built-in demo datasets; the larger ones need python3 sample_data/fetch_samples.py first (Step 4).
No lines appear and there is no LRM Mechanisms list edges.parquet is missing or in the wrong place. It must be directly inside the dataset folder, alongside experiment.xenium. If the list is there but no lines are, tick the Edges checkbox — the layer is off by default.
My metadata columns don't appear in the Cell Color column dropdown Check that the CSV is in a folder named exactly cell-metadata inside the dataset folder, with barcodes as the first column. R's default write.csv() writes barcodes there automatically.
Transcripts are not showing The Transcripts layer is off by default; tick its checkbox. On Xenium, transcripts with a Q-Score below 20 are hidden unless you tick show low-quality (Q < 20) in gray. And check the Transcript Species section: with no gene selected, nothing is drawn — click all.
TissuePlex is running slowly or edges lag Reduce the sample slider to 5% or lower. Also check that Docker Desktop has at least 8 GB of memory allocated (Settings → Resources on a Mac; .wslconfig on Windows, see Step 2).
A red ⚠ … failed: HTTP … — logged badge appears at the bottom of the canvas, or the viewer just stops updating A data request to the backend failed; the layer it was for is left empty rather than crashing the viewer. The badge disappears after a few seconds. Every such failure, every slow request and every backend crash is written to a log file that survives restarts:
docker compose exec backend tail -n 300 /cache/logs/tissueplex.log
If the badge keeps reappearing, restart with docker compose restart backend and send the log to whoever maintains your deployment. Opening a very large edge file for the first time is slow for a minute or two while an index is built in the background; that is normal and happens once.
My dataset has no DAPI / morphology image, or the badge says the image could not be opened Both are handled. Without an image the cells, transcripts and edges are drawn on a plain dark frame sized from the data, and there is no Morphology row. If an image exists but cannot be read, the viewer reports it (badge and log file) and draws the data on the same frame, so nothing else is lost. The log line names the file; re-exporting it as a standard OME-TIFF, or removing it, resolves the badge.
Error: port 3000 is already in use Another application is using that port. Stop the other application, or edit docker-compose.yml and change the host port (e.g. 3001:80), then restart.
Something else is wrong Ask a lab member, or open an issue at github.com/RaredonLab/TissuePlex/issues.