Box Plot

Core Feature

This feature is available in all Portrai Explorer deployments.

The Box Plot summarizes the distribution of a continuous variable — a gene's expression, a QC metric, or a Signature score — across the categories of a grouping feature. Each box draws the classic five-number summary: the median line, an interquartile-range (IQR) box spanning Q1 to Q3, whiskers reaching out to the data, and individual outlier points beyond them. It is the direct analogue of ggplot2::geom_boxplot() and the box overlay inside Seurat's VlnPlot, giving you a compact, quantitative read on where a distribution sits and how spread out it is.

Box plots are the natural companion to the Violin Plot. A violin shows the full smoothed density (good for spotting bimodality and zero-inflation common in single-cell data); a box plot strips that down to robust order statistics, making it easier to compare medians and spreads across many groups at a glance. The two share the same variable/group model and the same statistical-testing machinery, so you can switch between them without reconfiguring.

Creating a Box Plot

Box plots live in the Plot Dashboard as panels within a grid. Each panel is independent and its configuration is persisted per project.

1. Open the Plot dashboard from the Activity Bar
2. Add a new plot and choose the Box type
3. The new panel opens with an empty workspace prompting you to select a Group By column and a Variable

You can add, rename, duplicate, delete, resize, and drag box-plot panels just like any other plot. Every plot you create is listed in the sidebar.

Configuring the Data

The sidebar settings panel drives a single selected box-plot instance. The first two controls define what the plot summarizes.

Group By

Choose one categorical column. Its categories become the slots along the category axis — one box (or one dodged cluster of boxes) per category that has at least one cell in the current view.

• Only categories that contain data are drawn; empty categories are dropped.
• The grouping respects your active Subset and lasso selections, so the boxes always reflect the cells you are currently looking at.

Variables

Choose one or more continuous variables on the value axis. The selector supports the same multi-select UX as the Dot and Violin plots:

• Search across features, browse per-collection tabs (including a Signatures tab), check items, and click Done.
• Add Variable adds individual continuous columns or Signature scores.
• From Signature expands a signature into its member genes, adding each matched gene as its own variable.
• Selected variables appear as removable chips; click a chip's ✕ to remove it.

How variables are drawn depends on the count:

Variables	Layout
Single	One box per group; boxes are colored by group (matching your category color scale)
Multiple	Boxes are dodged side-by-side within each group slot, colored by variable, with a legend in the right margin

TIP

Use a single variable to compare one gene across cell types. Use multiple variables to compare a small panel of related genes within each group — but keep the list short, since dodged boxes get thin when groups and variables multiply.

Settings

The remaining sidebar controls shape the box geometry and appearance.

Orientation

Control	Description
Vertical	Category axis along the bottom, value axis vertical (default)
Horizontal	Category axis on the left, value axis horizontal — useful when group labels are long

Value Scale

The value axis can be transformed to handle the wide dynamic range typical of expression data:

Scale	Best For
Linear	Most data (default)
Log	Wide-ranging positive values
Log2	Wide-ranging positive values (base 2)
Log1p	Data with zeros, single-cell RNA-seq
SymLog	Data with negative values or zeros
Sqrt	Moderate compression

Whisker

The whisker convention determines how far the lines extend and what counts as an outlier:

Mode	Behavior
Tukey (1.5·IQR)	Whiskers reach the furthest data point within [Q1 − 1.5·IQR, Q3 + 1.5·IQR]; points outside the fence are drawn as outliers (default)
Min–Max	Whiskers reach the actual data minimum and maximum; no outliers are produced

This mirrors the coef = 1.5 default in ggplot2::geom_boxplot().

INFO

The whisker endpoints are the real data values inside the fence — not the fence boundaries themselves — so a whisker never extends past an actual observation.

Appearance toggles

Control	Description
Show Outliers	Draw points beyond the Tukey whiskers (on by default; has no effect in Min–Max mode)
Show Mean	Overlay a diamond marker at the group mean (off by default)
Show Grid	Draw value-axis grid lines across the plot (on by default)

How the Box Statistics Are Computed

For each (variable, group) pair, Portrai Explorer collects the finite values of the variable for all cells in that group (within the current view) and computes:

• Median, Q1, Q3 — quartiles via linear interpolation on the (n − 1)·p rank (the type-7 method, matching R's quantile() default and NumPy's default).
• IQR — Q3 − Q1, drawn as the box body.
• Whiskers — per the selected whisker mode (Tukey 1.5·IQR fence or data min/max).
• Mean — the arithmetic mean (shown only when Show Mean is enabled).
• n — the number of finite values contributing to the box.

Non-finite values (NaN/Inf) are skipped, and a degenerate, near-constant distribution still renders a (collapsed) box with a working tooltip.

Box vs. Violin

Prefer a Box Plot when you want a clean, quantitative comparison of medians and spreads across many groups, or when distributions are roughly unimodal. Prefer a Violin Plot when shape matters — to reveal bimodality, zero-inflation, or skew that a box would hide.

Outlier capping

In dense single-cell data a single group can have thousands of outliers. To keep rendering responsive, Portrai Explorer caps rendered outliers at 1,000 per box. When a box has more, the kept points are an evenly spaced subsample across the sorted outlier range, so they stay representative rather than biased by scan order.

The capping is purely a display optimization:

• The value axis is always sized to the true (pre-cap) outlier extent, so no real outlier is clipped off the plot.
• The tooltip reports both the rendered count and the full count (for example, "showing 1000 of 4218 outliers").

Statistical Testing

Box plots reuse the Violin plot's statistical-testing engine. When enabled, it runs pairwise comparisons between groups using a GPU-accelerated worker and annotates the plot with significance.

Enable testing under Statistical Testing → Enable in the sidebar, then configure:

Control	Options	Default
Pairwise Test	Wilcoxon rank-sum, t-test, Welch's t	Wilcoxon
Correction	BH (FDR), Bonferroni, Holm, None	BH (FDR)
Display	Symbol (*, **, …), P-value, or Both	Symbol
Significant Only	Show only comparisons that pass the α = 0.05 threshold	On

How results are surfaced depends on the number of variables:

• Single variable — significance brackets are drawn directly on the plot, connecting compared groups. Bracket text follows the Display setting; significant brackets are darker. In vertical orientation brackets stack above the plot; in horizontal orientation they sit to the right.
• Multiple variables — a Statistical Summary Panel opens in a resizable split below the plot, listing per-variable pairwise results (brackets are single-variable only).

Pseudoreplication

Cell-level pairwise tests treat each cell as an independent replicate. Because cells within a sample are correlated, these p-values are descriptive only and tend to be anti-conservative. For rigorous differential expression, aggregate to pseudobulk per sample and test across samples.

Interacting with the Plot

Hover Tooltip

Hover anywhere over a box's column to see its summary. The hit area spans the full sub-slot, so the tooltip works even when a box is tiny. The tooltip reports:

• Group (and variable, in multi-variable mode)
• median
• Q1 and Q3
• whisker low and high values
• mean and n (cell count)
• Outlier counts when capped ("showing X of Y outliers")

Export

Export the box plot as an image from the Export button (download icon) in the plot panel's titlebar — beside the ⋯ menu and ✕ close button.

1. Click Export in the panel titlebar
2. Click Capture PNG
3. The image downloads as {plot title} - {variables}.png (for example Box Plot 1 - CD3E, CD4.png). Long variable lists are shortened to the first few names plus a +N more suffix.

The exported PNG renders the SVG to a canvas on a white background and includes the boxes, axes, tick labels, axis titles, the variable legend (multi-variable mode), and any significance brackets. CSS theme colors are resolved to concrete values and the on-screen UI font is preserved.

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.

Use Cases

Compare a marker gene across cell types

1. Set Group By = cell type / cluster
2. Add the marker gene as the single Variable
3. Enable Statistical Testing to bracket the significant pairwise differences
4. Read off which clusters have the highest median expression

QC metrics by sample

1. Set Group By = sample
2. Add n_counts (and/or n_genes) as variables
3. Use Horizontal orientation if sample names are long
4. Scan the medians and outliers for samples that deviate from the rest

Compare a small gene panel within each group

1. Set Group By = cell type
2. Add a handful of related genes as variables (or use From Signature to expand a pathway)
3. Boxes dodge within each group, colored per variable with a legend
4. Open the summary panel to review per-variable significance

Troubleshooting

Plot is empty

• Confirm both a Group By column and at least one Variable are selected
• Check that the current Subset or selection isn't excluding every cell
• Allow time for columns and signature scores to finish loading

A box looks like a flat line

• The distribution is (near) constant for that group, so Q1, median, and Q3 collapse together — this is expected. The hover tooltip still reports the values.

No outliers appear

• Show Outliers must be on, and the Whisker mode must be Tukey — Min–Max mode produces no outliers by design.

Whiskers look clipped or boxes are squashed

• Try a different Value Scale (e.g. Log1p for single-cell expression with many zeros) to spread out the value axis.

Significance brackets don't show

• Brackets render only with a single variable; with multiple variables, results appear in the summary panel instead.
• With Significant Only enabled, non-significant comparisons are hidden — disable it to see all pairs.
• At least two groups must contain data.

Related Topics

• Plot Dashboard - Manage box-plot panels in the grid
• Violin Plot - Full-density companion view
• Bar Plot - Single summary value per group
• Dot Plot - Expression and fraction across groups
• Signatures - Create variables from gene sets
• Features - Browse grouping columns and variables
• Subset - Control which cells feed the boxes
• Image Export - Export plot panels as images