Violin Plot

Core Feature

This feature is available in all Portrai Explorer deployments.

The Violin Plot shows the full distribution of a continuous variable — a gene's expression, a QC metric, or a signature score — split across the categories of a grouping feature. Each "violin" is a kernel-density estimate (KDE) of the values, mirrored around a center line, so you can see not just the median and spread but the shape of the distribution: bimodality, skew, and zero-inflation that a bar chart or simple box plot would hide.

This is the direct counterpart to Seurat's VlnPlot() and scanpy.pl.violin(). As in those tools, you pick one or more variables and a grouping (group.by / groupby), and Portrai Explorer draws one violin per group. When you select multiple variables, the plot becomes a stacked layout — one row per variable, groups aligned across rows — analogous to Seurat's stacked VlnPlot(stack = TRUE).

Creating a Violin Plot

Violin plots live in the Plot dashboard, where multiple plots coexist as panels in a resizable grid.

1. Open the Plot dashboard from the Activity Bar.
2. Add a new plot and choose Violin as the type.
3. The new panel appears in the grid with an empty workspace until you select variables and a Group By column.

Each plot is a panel you can rename, duplicate, delete, resize, and drag. The sidebar lists every plot in the project, and each plot's configuration is persisted per project, so violins you set up are restored when you reopen the project.

See Plot Dashboard for managing panels.

Selecting Variables

Variables are the continuous quantities whose distribution you want to inspect. Open the Variables section in the sidebar and use Add Variable.

• The popover lists variables grouped into tabs by collection, plus a Signatures tab.
• Only continuous columns are offered (gene expression, metrics, scores). Categorical columns belong in Group By instead.
• Use the search box to filter, and the sort button to reorder long lists.
• Check one or more items and click Done to apply. Selected variables appear as removable tags below the selector — click a tag's × to remove it.

Signatures as variables

A Signature can be selected directly as a variable. The Signature is scored across cells using its default combination method and treated as a single continuous variable.

Alternatively, From Signature expands a Signature into its individual member genes, adding each matched gene as its own variable. The badge next to each Signature shows how many of its variables are matched in the dataset (matched / total).

TIP

Selecting a single variable draws a standard grouped violin plot (single layout). Selecting two or more variables switches to the stacked layout, with one row per variable — ideal for comparing a marker panel across the same groups.

Group By

The Group By selector chooses the categorical feature that defines the violins (the X axis).

• Only categorical columns are listed (cell type, cluster, sample, condition, etc.).
• Each category becomes one violin (in single mode) or one violin per row (in stacked mode).
• Violin fill colors follow the same categorical color scale used elsewhere in the project — see Color Mapping.

A violin plot is empty until both a variable and a Group By column are selected.

Y Scale

The sidebar Y Scale selector controls how data values are mapped to the vertical axis. This is useful for expression data that spans several orders of magnitude or includes zeros.

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

Interior Display

Each violin can show summary statistics inside its density shape. Configure these under Interior Display in the sidebar.

Control	Description
Type	What to draw inside the violin: Box Plot, Quartiles, Points, or None
Show Median	Adds a horizontal median line
Show Mean	Adds a red diamond marker at the mean

Type options in detail:

• Box Plot — a classic box: whiskers from min to Q1 and Q3 to max, with a Q1–Q3 box.
• Quartiles — a thick spine from Q1 to Q3 with tick marks at Q1 and Q3.
• Points — individual data points drawn with horizontal jitter. For performance, large groups are subsampled to roughly 500 points per violin.
• None — only the smooth density outline, with no interior marks.

Default: Type = Points, Show Median = on, Show Mean = off.

Density & Appearance

Density-estimation and appearance controls live in the sidebar Settings inspector, in the Density Estimation and Appearance sections — together with Variables, Group By, Y Scale, Interior Display, and Statistical Testing. All of a violin's controls are in one place in the sidebar; the panel titlebar carries the Export button and a Reset label positions button (axis and title labels can be dragged to reposition them, and this button restores their default placement).

Density Estimation

The KDE controls how the smooth violin outline is computed from the raw values.

Control	Description
Auto Bandwidth	Use Silverman's rule to choose the smoothing bandwidth automatically (default on)
Bandwidth adjust	When Auto is off, a multiplier on the Silverman bandwidth (0.2–3.0, default 1.0; 1.0 = plain Silverman). Lower = noisier, higher = smoother
Kernel	KDE kernel function: Gaussian (default) or Epanechnikov

TIP

This bandwidth adjust multiplier is analogous to the adjust parameter in R's density() / geom_violin(). Increase it to smooth away sampling noise, decrease it to reveal fine structure such as bimodality.

Appearance

Control	Description
Violin Width	Maximum violin width (0.2–1.0, default 0.8)
Fill Opacity	Fill transparency of the violin body (0.1–1.0, default 0.7)
Density Norm	How violin widths are normalized: Width, Area, or Count
Show Grid	Toggle background grid lines (default on)
Independent Y Axis	In stacked mode, scale each variable's row to its own data range (default on, Seurat-like)
Y-Axis Density	Tick/grid density for stacked mode: Auto, Normal, Compact, or Minimal

Density Norm determines how violins are made comparable:

• Width (default) — every violin is scaled to the same maximum width, emphasizing shape over abundance.
• Area — violins are normalized so equal area represents equal density.
• Count — violin width scales with group size, so larger groups draw wider violins.

Y-Axis Density (stacked mode only) trades detail for compactness. Auto picks a mode by variable count: Normal for ≤3 variables, Compact for 4–9, and Minimal for 10 or more. Normal shows full ticks and grid lines; Compact shows only the maximum-value tick and no horizontal grid; Minimal removes ticks, the axis line, and horizontal grid entirely.

Statistical Testing

Violin plots can run pairwise statistical comparisons between groups and annotate the plot with significance results. Enable it under Statistical Testing in the sidebar.

WARNING

Cell-level pairwise tests treat each cell as an independent replicate (pseudoreplication) and are descriptive only. Rigorous differential expression should use pseudobulk aggregation per sample. Use these tests for exploration, not as a substitute for a proper DE workflow.

Settings

Control	Options	Description
Enable	on / off	Turn statistical testing on (default off)
Pairwise Test	Wilcoxon (default), t-test, Welch's t	The test applied to each pair of groups
Correction	BH (FDR) (default), Bonferroni, Holm, None	Multiple-comparison correction across all pairwise comparisons
Display	Symbol (default), P-value, Both	How results are shown on brackets and in the summary
Significant Only	on / off (default on)	Show only significant comparisons (in brackets and the summary panel)

The available tests are:

• Wilcoxon — the Wilcoxon rank-sum (Mann-Whitney U) test; a nonparametric comparison of distributions. This is the default and matches the test most commonly used in single-cell tools.
• t-test — Student's two-sample t-test (assumes equal variance).
• Welch's t — Welch's t-test (does not assume equal variance).

Multiple-comparison correction is applied across the set of pairwise comparisons:

• BH (FDR) — Benjamini-Hochberg false discovery rate (default).
• Bonferroni — conservative family-wise control.
• Holm — Holm step-down family-wise control.
• None — raw, uncorrected p-values.

Significance is evaluated at alpha = 0.05, and each comparison is summarized with a symbol (ns, *, **, ***, ****), an adjusted p-value, and the log2 fold change between group means.

Significance brackets (single mode)

In single-variable mode, significant comparisons are drawn as brackets spanning the two groups, stacked into levels so they don't overlap. Each bracket's label follows the Display setting (symbol, p-value, or both). With Significant Only enabled, only significant pairs are bracketed.

Statistical Summary panel (stacked mode)

When statistical testing is enabled in stacked mode (multiple variables), a Statistical Summary panel appears below the plot.

• A header shows overall progress and a total significant-vs-tested count.
• Each variable is a row, sorted with the most significant variables first, showing how many of its comparisons were significant. For variables with at least one significant comparison, the row also shows the minimum p-value and the maximum |log2FC|.
• Expand a variable to see a table of its pairwise comparisons (group1 vs group2), with adjusted p-value (p-adj, hover for the raw value), log2FC, and the significance symbol — respecting the Display and Significant Only settings.
• Variables that can't be tested (fewer than two groups) show an error badge.

The footer restates the active test, correction method, and alpha so results are self-documenting.

Subset Filtering

Violin plots respect the active Subset. Only currently visible cells contribute to each violin's density, statistics, and significance tests — so subsetting to a region or a lasso selection recomputes the violins for just that population. This lets you compare distributions within a focused subpopulation without leaving the plot.

Interacting with the Plot

Hover

Move the pointer over a violin to see a tooltip. Hit detection follows the actual density-curve outline, so the tooltip appears only when you're inside the violin shape. The tooltip shows:

• Variable name and group label
• Cell count (n)
• Min, max, median, and mean
• Q1 and Q3 quartiles
• When statistical testing is enabled, the pairwise comparisons involving that group

Export

Open the Export button (download icon) in the plot panel's titlebar to export the violin plot as an image or as raw data.

Capture as image

• Capture PNG — renders the plot to a raster PNG (white background) and downloads it.
• Capture SVG — exports the plot as a vector SVG (transparent background), suitable for editing in vector tools or producing high-resolution figures.

Image files are named after the plot title with the variable names appended ({plot title} - {variables}.png / .svg). Long variable lists are shortened to the first few names plus a +N more suffix.

The exported image includes the violin shapes, interior marks, axes, labels, grid, and significance brackets exactly as displayed.

Export data as CSV

• Download All Data — exports the underlying values for every violin as a CSV.
• Download Selected Data — exports only the currently selected data (available when a selection is active).

See Export Image for related export options.

Use Cases

Marker expression across cell types

1. Set Group By = cell type (or cluster).
2. Add one marker gene as the variable.
3. Inspect which cell types express the marker and whether expression is bimodal.

Comparing a marker panel (stacked)

1. Set Group By = cluster.
2. Add several marker genes, or use From Signature to expand a marker Signature.
3. The stacked layout shows one row per gene, groups aligned — a compact panel like Seurat's stacked VlnPlot.

Signature score by condition

1. Create a pathway Signature.
2. Add it as a variable and set Group By = condition.
3. Enable Statistical Testing (Wilcoxon + BH) to flag conditions with significantly different scores.

Quality control

1. Set a QC metric (n_counts, n_genes, percent mito) as the variable.
2. Group By sample or batch.
3. Spot samples with shifted distributions or unusual tails.

Troubleshooting

Plot is empty

• Confirm both at least one Variable and a Group By column are selected.
• Check the message in the workspace; it indicates whether data is loading or missing.
• Verify the active subset isn't excluding all cells.

Violins look too smooth or too noisy

• Turn off Auto Bandwidth and adjust the Bandwidth adjust multiplier (lower for more detail, higher for more smoothing).
• Try the Epanechnikov kernel for a slightly tighter outline.

Groups look the same width regardless of size

• That's the default Width normalization. Switch Density Norm to Count to make violin width reflect group size.

Stacked rows are cramped

• Increase the panel size, or set Y-Axis Density to Compact or Minimal to reduce per-row axis clutter.
• Toggle Independent Y Axis off to share one scale across rows when variables are on comparable scales.

Statistical results missing for a variable

• A variable needs at least two groups to be compared; otherwise it reports an error in the summary panel.
• If brackets or rows are hidden, check whether Significant Only is filtering out non-significant comparisons.

Related Topics

• Plot Dashboard - Manage plot panels in the grid
• Scatter Plot - Two-variable relationships
• Box Plot - Compact distribution summaries
• Color Mapping - Configure group colors
• Layer Settings - Appearance settings shared across plots
• Signatures - Create variables from gene sets
• Features - Variables and grouping columns
• Subset - Restrict which cells contribute
• Lasso Selection - Select populations directly
• Export Image - Export the plot as an image