Ridgeline Plot Maker for Comparing Many Distributions

What is a ridgeline plot?

A ridgeline plot is a stack of density curves, one per group, drawn on a shared x-axis and offset vertically so that each curve slightly overlaps the one above it. The result looks like a mountain range, which is where the name comes from. Each ridge is a smoothed histogram of one group’s values, so the plot shows the shape of many distributions at once: where each peaks, how wide it is, whether it is skewed or has two peaks, and how the distributions shift from one group to the next. Ridgeline plots were long called joy plots, after the stacked line traces on the cover of Joy Division’s 1979 album Unknown Pleasures. In 2017 Claus Wilke, author of the R package that popularized them, retired that name because of the dark history behind the band’s name and renamed the package from ggjoy to ggridges; ridgeline plot is now the standard term.

How to read a ridgeline plot

• Read along the x-axis: a ridge further right has larger values. Comparing where the peaks and the median lines sit is the main point of the plot.
• Width shows spread. A narrow, tall ridge is a tightly clustered group; a low, wide ridge is a variable one.
• Two humps in one ridge mean the group mixes two subpopulations, such as expressing and non-expressing cells.
• There is no density axis. Heights are relative: every ridge is drawn on the same scale, with the tallest peak in the figure set to one row of height times the overlap.
• Ridge height is not group size. A small, tightly clustered group can have the tallest ridge, so read n from the labels.
• Smoothing spreads values a little past the real minimum and maximum, so a tail can cross a hard limit such as zero. Check the median and quartile numbers, not the tails.

How the density curves are computed

For each group the generator computes a Gaussian kernel density estimate on one shared grid of x values. The bandwidth (how much the curve is smoothed) is chosen with Silverman’s rule of thumb, the same rule as R’s bw.nrd0: 0.9 × min(SD, IQR / 1.34) × n^(−1/5). As in the R package ggridges, one joint bandwidth is used for every ridge, the mean of the per-group bandwidths, so differences in shape come from the data rather than from different amounts of smoothing. All ridges are scaled by the single tallest peak, and tails below 1% of that peak are trimmed so they do not run as flat lines across the axis. Medians, quartiles (type 7 interpolation, as in R and NumPy), means, SDs, and the location of each peak are computed from your raw values. Ask for "separate bandwidths" or "scale each ridge" to change those defaults.

When to use a ridgeline plot

• Many groups: ridgelines stay readable with 10, 20 or more groups, where side-by-side violins or box plots become thin slivers.
• Ordered groups: months, years, time points, doses, or ranked categories, where the eye follows the shift from ridge to ridge.
• Shape matters: skew, long tails, and two peaks are visible in a ridge but hidden in a box plot.
• For two to five groups with small samples, show the raw points instead, with a raincloud plot or a box plot with jittered points.
• For one distribution, a histogram is simpler and shows counts directly.

Ordering, overlap, and color

• Order: month and weekday names are put in calendar order and numeric labels in numeric order; other groups keep the order they first appear in your file. Write "order by median" (or "by mean, descending") to rank them instead.
• Overlap: 1.5 to 2 rows of overlap is typical. Ask for "overlap 1" for a calmer plot or "overlap 3" for a dramatic one; too much overlap hides the ridges behind.
• Color: one color for all ridges is often enough. Use a gradient along the x-axis when the value itself has meaning (temperature), or a sequential palette when the groups are ordered.
• Overlay: map a third column with two or three levels (control and treated, male and female) to draw semi-transparent overlapping densities inside each ridge.
• Annotation: median or quartile lines inside each ridge and rug marks for raw values help readers check the curves.

What data does a ridgeline plot need?

• Long format: one row per observation, with a group column and a numeric value column. Wide tables with one column per group should be reshaped first (for example with pivot_longer in R or melt in pandas).
• At least 5 values per group are required and 30 or more are recommended; a density curve from a handful of points mostly shows the bandwidth.
• Up to 20 groups are drawn. Extra groups are listed in a warning so nothing is dropped silently.
• An optional overlay column can hold up to 3 levels.
• Uploads are limited to 1,200 rows. For larger datasets, upload a random sample per group.