Dot Plot

Core Feature

This feature is available in all Portrai Explorer deployments.

A Dot Plot summarizes the expression of many genes across many cell groups in a single compact grid. Rows are genes (or signature scores) and columns are the categories of a grouping feature — for example clusters, cell types, or samples. Each dot encodes two quantities at once: its size is the fraction of cells in that group that express the gene, and its color is the mean expression of the gene in that group. This makes it the standard way to read out a marker-gene panel across clusters at a glance.

This is the Portrai Explorer equivalent of Seurat's DotPlot() and scanpy's scanpy.pl.dotplot. As in those tools, dot size scales linearly with the percentage of expressing cells (Seurat's default radius mapping), and the color channel can show raw mean expression or a per-variable z-score across groups. Z-scored values are clipped to the range [-2.5, 2.5], matching Seurat's scale = TRUE / col.min/col.max convention so that a single outlier group cannot wash out the color scale.

Creating a Dot Plot

Dot Plots live in the Plot dashboard, a grid where multiple plots coexist as panels you can add, rename, duplicate, resize, drag, and delete. Each plot's configuration is persisted per project.

1. Open the Plot dashboard from the Activity Bar
2. Add a new plot and choose Dot as the plot type
3. The new panel appears in the dashboard; the sidebar lists all plots in the project
4. Select the Dot Plot panel to edit its settings in the sidebar

Until you choose a grouping column and at least one gene, the panel shows the hint "Select a Group By column and at least one gene to visualize".

See Plot Dashboard for managing panels.

Configuring the Grid

All data selection happens in the sidebar settings panel for the selected Dot Plot.

Group By (columns)

The Group By selector chooses the single categorical column whose categories become the X-axis columns of the grid.

1. Click the Group By selector
2. Pick a categorical feature (clusters, cell types, sample, condition, etc.)
3. Each category that contains cells becomes one column, in the feature's category order

Only categorical columns are listed here. Groups with no cells (after subsetting) are omitted.

Variables (genes / signatures)

The Variables selector chooses the Y-axis rows. You can mix two kinds of variable:

• Continuous columns — individual genes or other continuous metrics.
• Signature scores — a Signature added as a single combined row (computed with the default combination method).

To add variables:

1. Click Add Variable to open the picker
2. Search across per-collection tabs (including a Signatures tab) and check the variables you want
3. Click Done to apply the selection
4. Selected variables appear as removable chips below the selector — click a chip's ✕ to drop that row

From Signature

Use the From Signature button to expand a signature into its member genes as individual rows, rather than adding it as one combined score. This is the fast way to lay out a curated marker panel: pick the signature and every matched gene becomes its own row.

INFO

Rows are drawn in the order they were selected. To reorder, remove and re-add variables in the desired sequence.

Settings

Color

The Color selector controls what the dot color encodes:

Control	Description
Mean expression	Color = the raw mean expression of the gene within the group (default).
Z-score (per variable)	Color = the mean expression z-scored across groups, computed independently for each variable (row).

With Z-score (per variable), each row is centered and scaled on its own, so colors compare groups within a variable rather than across variables — useful when variables have very different expression magnitudes. Z-scored values are clipped to [-2.5, 2.5]. The color-bar label changes to Z-score accordingly; otherwise it reads Mean expr.

TIP

Z-score coloring makes it easy to see which group a variable is relatively highest in, even for lowly-expressed variables. Switch back to Mean expression when absolute levels matter.

Expressing if > (threshold)

The Expressing if > field sets the value above which a cell counts as expressing the gene. A cell contributes to a dot's size only when its value is strictly greater than this threshold. The dot size is then the fraction of valid cells in the group that pass it.

• Default: 0 (any nonzero value counts as expressing).
• Step: 0.1; any finite number is accepted.

Debounced

This control is debounced: the input updates instantly as you type, but the grid recompute only fires about 300 ms after you stop typing. The threshold drives a full pass over all cells × genes, so the delay keeps typing responsive on large datasets.

Show Grid

Control	Description
Show Grid	Toggles light guide lines between grid cells (on by default).

Reading the Plot

Layout

The plot is a true grid: columns are groups (with the Group By column name shown as the X-axis title) and rows are genes. Group labels run along the bottom; gene labels run down the left. Long labels are truncated to 16 characters with an ellipsis.

When columns get narrow (many groups), the bottom group labels automatically rotate to -45° and extra bottom margin is reserved so they don't collide with the axis title.

Dot size — % expressing

Dot radius scales linearly with the fraction of expressing cells (Seurat's default), capped so sparse grids don't produce oversized dots. A group where essentially no cells express a gene (~0%) draws no dot at all, leaving the cell empty.

Dot color — mean expression

Dot color maps the color channel (mean expression, or z-score) through the active continuous colorscale. The mapping spans the full extent of values across every dot in the grid.

Legends

Both legends are drawn in the right margin and are included in PNG export:

• Color bar — a vertical gradient labeled Mean expr or Z-score, annotated with the maximum value at the top and the minimum at the bottom.
• % Expressing — reference circles at 25%, 50%, 75%, and 100% showing how dot size maps to the expressing fraction.

Interacting with the Plot

Hover and tooltip

Hovering anywhere within a grid cell shows a tooltip for that gene × group intersection. A single delegated hit area maps the pointer to a cell with grid math, so the tooltip works even where the dot is tiny or absent (0% expressing).

The tooltip reports:

• Gene · Group — the row and column identity
• Mean expr — the raw mean expression of the gene in that group
• Expressing — the percentage of cells expressing, with the cell count (n =)

INFO

The tooltip always shows raw mean expression, even when the color channel is set to Z-score, so you can read absolute levels at the same time.

Export

Export the grid as an image from the plot panel's titlebar:

1. Click the Export button (download icon) in the panel titlebar, beside the ⋯ menu and ✕ close button
2. Click Capture PNG
3. The PNG downloads as {plot title} - {Group By column}.png, named after the plot title

The exported image includes all dots, axis labels and title, the color bar, and the % expressing size legend, rendered on a white background.

The Export popover also provides Capture SVG (vector output) and Export data as CSV — Download All Data, or Download Selected Data for the current visibility selection.

See Image Export and Plot Data CSV Export for more on exporting plots.

Use Cases

Marker-gene panel across clusters

The classic use: lay out canonical markers and read cell identity per cluster.

1. Set Group By to your cluster or cell-type column
2. Add the marker genes as Variables (or use From Signature to expand a marker signature)
3. Leave Color on Mean expression
4. Scan for dots that are both large (many cells express) and dark (high mean) — these mark the cluster

Comparing relative expression

When genes differ widely in magnitude:

1. Switch Color to Z-score (per variable)
2. Each row is scaled independently, so you can see which group a gene peaks in regardless of its absolute level

Detection rate vs. level

To separate "how many cells express" from "how strongly":

1. Compare a gene's dot size (detection rate) against its color (mean level) across groups
2. Adjust Expressing if > to require a higher value before a cell counts as expressing, sharpening the size contrast

Troubleshooting

Plot is empty

• Confirm a Group By column is selected and at least one Variable is added
• Variables that haven't finished loading are skipped until ready — allow a moment after selecting
• Check that active subsets or lasso selections aren't excluding all cells

Cells have no dots

• A dot is omitted when ~0% of the group's cells exceed the Expressing if > threshold
• Lower the threshold (default 0) if it is set too high for the data's scale

Colors look flat or saturated

• Switch between Mean expression and Z-score (per variable) — z-scoring (clipped to [-2.5, 2.5]) often reveals contrast that raw means hide
• The color extent spans all dots, so one very high group can compress the rest; z-score coloring mitigates this

Threshold changes feel delayed

• The Expressing if > field is debounced (~300 ms) by design; the grid recomputes shortly after you stop typing

Group labels are cut off or rotated

• With many groups, labels rotate to -45° and truncate at 16 characters automatically; widen the panel to give them more room

Related Topics

• Plot Dashboard - Manage plot panels in the grid
• Violin Plot - Per-group distribution view of the same variables
• Box Plot - Summary distribution by group
• Color Mapping - Configure the continuous colorscale used for dot color
• Signatures - Build gene-set scores used as rows
• Features - Categorical columns used for Group By
• Image Export - Export the grid as an image