Quick Reference · stacked density ridgelines

joypy cheat sheet

One function, one job. joypy.joyplot(df) takes a DataFrame, estimates a density (KDE) for each numeric column — or each group via by= — and stacks them into overlapping ridgelines. It returns a plain Matplotlib (fig, axes), so everything you know about saving and styling still applies. Named after Joy Division's Unknown Pleasures cover.

import / setup data & grouping density (KDE / hist) overlap & range colour & fill labels & output gotcha ★ most common

Distilled & cross-checked against the joypy source (no formal docs exist): github.com/leotac/joypy (joyplot.py + README + Joyplot.ipynb) · python-charts.com · python-graph-gallery.com · blanchardjulien.com · Wikipedia: ridgeline plot

One call — DataFrame in, stacked ridgelines out

The minimal call, then the usual dressing-up

import joypyimport pandas as pdfrom matplotlib import cmiris = pd.read_csv("iris.csv")fig, axes = joypy.joyplot(iris)                       # one ridge per numeric columnfig, axes = joypy.joyplot(iris, by="Name", column="SepalLength",  # one ridge per group                          colormap=cm.viridis, overlap=2, fade=True)fig.savefig("joy.png", dpi=300, bbox_inches="tight")   # it's just Matplotlib

01Setup & Importonce per project

$ pip install joypy
Pulls in matplotlib, pandas, scipy, numpy.
import joypy★
The whole library — one function inside.
import pandas as pd
joypy is built around DataFrames.
from matplotlib import cm
For colormaps like cm.viridis, cm.magma.
import matplotlib.pyplot as plt
To save / show the returned figure.

02The One Functionthe entire API

fig, axes = joypy.joyplot(df)★
That's the whole thing — everything else is optional.
# returns (fig, axes)
A Matplotlib figure and a list of axes.
# one ridge per numeric column
Non-numeric columns are quietly skipped.
len(axes) == n + 1note
n rows + 1 global axis (axes[-1]).
# density via scipy gaussian_kde
Smooth curves out of the box.

03Data Input Modeswhat it accepts

joyplot(df)★
A DataFrame → one ridge per numeric column.
joyplot(series)
A single pandas Series.
joyplot({"a": arr1, "b": arr2})
A dict of arrays (keys become labels).
joyplot([arr1, arr2])
A plain list of arrays.
joyplot(df.groupby("g"))
A pandas GroupBy object.

04Grouping: by & columnrows vs values

joyplot(df, by="group")★
One ridge per group value.
joyplot(df, column="value")
Restrict to one variable.
joyplot(df, by="g", column="v")★
Group × one variable — the classic form.
joyplot(df, by="g", column=["v1","v2"])
Several densities overlaid per group.
# by = groups rows · column = picks values
Two independent axes of splitting.

05Density: KDE vs Histogramhow the curve is made

joyplot(df)★
Smooth KDE curves (the default).
joyplot(df, hist=True)★
Stepped histograms instead of KDE.
bins=20
Histogram bin count (default 10).
joyplot(df, hist=True, bins=30)
Finer histograms.
# KDE uses scipy.stats.gaussian_kde
Great for continuous data.

06Density Kind & Bandwidthfiner control

kind="kde"
Default smooth density.
kind="counts"
Raw histogram counts.
kind="normalized_counts"
Counts ÷ n.
kind="values"
Plot raw values — set x_range too.
bw_method=0.2
KDE smoothing bandwidth (passed to scipy).
normalize=True
Normalise each density (default).

07Overlap & Stackingthe signature knob

overlap=1★
How much rows overlap (default 1).
overlap=0
Rows fully separated — no overlap.
overlap=2
Heavy overlap — the dramatic look.
ylim="max"★
All rows share one y-scale (default).
ylim="own"
Each row scales to its own peak.
figsize=(8, 6)
Figure size in inches.

08Range & x-axiswhere curves live

range_style="all"
Every row shares the x-range (default).
range_style="own"
Each row uses its own data range.
range_style="group"
Range spans the whole group.
x_range=np.linspace(0, 100, 200)
Explicit x positions for the density.
tails=0.2
Extra padding beyond the data on each side.

09Colour & Colormapthe palette

colormap=cm.viridis★
Colour rows along a colormap.
colormap=cm.magma · cm.Blues
Any Matplotlib colormap object.
color="steelblue"
One flat colour for every row.
color=["r", "g", "b"]
An explicit per-row list.
fade=True★
Fade opacity down the stack.
# colormap wants an object, not a namenote
cm.viridis, not "viridis".

10Fill, Lines & Backgroundcurve styling

fill=True★
Fill under each curve (default).
fill=False
Outlines only — pure ridgelines.
linecolor="k"
Curve outline colour (auto black when filled).
background="black"
Figure background — the Unknown Pleasures look.
alpha=0.6 · linewidth=2
Passed straight through to Matplotlib.

11Labels & Titleannotate

labels=["A", "B", "C"]
Custom per-row labels.
ylabels=False
Hide the row labels entirely.
xlabels=True
Show the shared x tick labels (default).
title="Distributions by year"
Figure title.
xlabelsize=10 · ylabelsize=12
Tick / label font sizes.
xrot=45 · yrot=0
Rotate tick labels.

12Legend & Gridextras

legend=True
Show a legend (needs sub-labels).
loc="upper right"
Legend position.
grid=True
Turn on gridlines.
grid="y" · "x" · "both"
Grid on a specific axis.
# legend appears with by= + multiple columns
Sub-labels drive the legend entries.

13Output & the Axessave & tweak

fig, axes = joypy.joyplot(df)★
Capture both to save or post-edit.
fig.savefig("joy.png", dpi=300)★
Save the figure.
plt.savefig("joy.png", bbox_inches="tight")
Trim surrounding whitespace.
axes[-1]
The global axis — style the whole figure here.
axes[i].set_xlim(..)
Reach into any single ridge's axis.
plt.show()
Display interactively.

14Recipescopy & adapt

basic: joyplot(df)
One ridge per numeric column.
grouped: joyplot(df, by="g", column="v")
Compare a variable across groups.
over time: joyplot(df, by="month", column="temp")
Distribution shifts across a dimension.
histogram: joyplot(df, hist=True, bins=20)
Binned instead of smoothed.
unknown pleasures: colormap=cm.magma, background="k", overlap=2
The album-cover aesthetic.
airy: joyplot(df, fade=True, overlap=3, fill=False)
Faded, overlapping outlines.

Four ideas that explain the plot

What a joyplot actually is, the three ways to feed data in, how the one signature knob reshapes the stack, and the KDE-vs-histogram choice behind every curve. Based on the joypy source & example notebook.

anatomy of a joyplot

Each row is one distribution's density, drawn on its own axis and stacked so neighbours overlap — the ridgeline.

three ways to feed it

Ridges can come from columns, from groups, or from both at once — same function, different arguments.

overlap = the signature knob

One number sets how far each row rides up into the one above — from tidy separation to the classic dense stack.

KDE vs histogram

The same data, two estimators: a smooth kernel density (default) or discrete bars with hist=True.

Worth memorizing

returns (fig, axes)it's a Matplotlib wrapper — save/style as usual

len(axes) == n+1n rows plus a global axis at axes[-1]

KDE by defaultscipy gaussian_kde; pass hist=True for bars

numeric onlynon-numeric columns are silently skipped

by vs columnby= groups rows · column= selects values

overlap is the knob0 separated · 1 default · >1 denser stack

ylim="max" vs "own"shared scale across rows, or each self-scales

colormap needs an objectcm.viridis, not the string "viridis"

colormap vs colorcolormap= gradients rows · color= is flat / a list

fill forces linecolorfill=True sets linecolor="k" unless you override

range_style"all" · "own" · "group" control each row's x-range

no formal docsthe README notebook & joyplot.py source are the reference

joypy cheat sheet · synthesized from the joypy source of truth (github.com/leotac/joypy — joyplot.py, README & the Joyplot.ipynb example notebook), since the package ships no formal documentation.
joypy is a one-function Matplotlib + pandas + scipy wrapper: joypy.joyplot(data, by=, column=, hist=, overlap=, colormap=, …) → (fig, axes) · a joyplot is a.k.a. a ridgeline plot · the name comes from Joy Division's Unknown Pleasures.