Heatmaps in Python
A python heatmap (also written as heat map, and sometimes called a heatmap
chart or heatmap plot) maps a 2D grid of values onto a color scale so patterns,
clusters, and gradients read at a glance. With xy you build an interactive
heatmap in Python from a NumPy matrix: pan, zoom, and hover work by default, and
the grid stays crisp as you navigate.
Jump to creating a heatmap, choosing a colormap, or adding a colorbar.
Create a Heatmap
Pass a 2D array of values to heatmap, with optional x and y coordinates
for the grid edges. This is the minimal Python heatmap:
Diverging Colormap with a Fixed Domain
A signed field reads best with a diverging colormap, an explicit
domain=(min, max) pinned symmetrically around zero, and an xy.colorbar() so
the scale is visible:
Correlation-Matrix Heatmap
A small labeled grid turns a heatmap into a correlation matrix: pass cell
coordinates for x and y, relabel the ticks with feature names, fix
domain=(-1, 1), and add a colorbar with explicit ticks:
Colormaps and Value Domain
The colormap controls how values map to color — sequential maps like
"viridis" suit magnitudes, while a diverging map reads better around a
midpoint. Set domain to fix the value range the colors span, so separate
heatmaps stay comparable instead of each rescaling to its own min and max.
Add a Colorbar Scale
A heatmap is only readable with a legend for its colors. Add an
to draw a visible scale that
ties each color back to a value. Use opacity to blend the grid over other
marks when you overlay a heatmap on additional context.
Heatmap Options
Add to show the value-to-color
scale. Pass column names with data= instead of arrays when your data is a
table.
Related Charts
- Hexbin plots — bin scattered points into a colored hexagonal grid.
- Contour plots — draw iso-value lines over a field.
- Colorbar component — add a visible color scale to any heatmap.
API Reference
xy.heatmap_chart
A heatmap chart composing `heatmap` marks and axis/legend children.
Props
| Prop | Type | Description |
|---|---|---|
*children | Component | Marks, axes, annotations, and chart chrome. |
title | Optional[str] | Title shown above the plot. |
width | int | str | Chart width in pixels or a CSS size such as ``"100%"``. |
height | int | str | Chart height in pixels or a CSS size such as ``"100%"``. |
padding | Union[float, Sequence[float], None] | Plot margins, as one value or a sequence of side values. Use zero for an edge-to-edge sparkline. |
data | TableLike | Chart-level data used by marks that omit their own ``data``. |
class_name | Optional[str] | CSS class applied to the chart container. |
class_names | Optional[dict[str, str]] | CSS classes keyed by stable chart DOM slot. |
style | Optional[dict[str, StyleValue]] | Inline style overrides for the chart container. |
styles | Optional[dict[str, dict[str, StyleValue]]] | Inline style mappings keyed by stable chart DOM slot. |
on_hover | Optional[Callable[[dict], None]] | Callback receiving hover event payloads. |
on_click | Optional[Callable[[dict], None]] | Callback receiving picked-mark click payloads. |
on_brush | Optional[Callable[[dict], None]] | Callback receiving brush event payloads. |
on_select | Optional[Callable[[Selection], None]] | Callback receiving data-space selections. |
on_view_change | Optional[Callable[[dict], None]] | Callback receiving viewport change payloads. |
hover | Optional[bool] | Whether pointer movement emits hover events. |
click | Optional[bool] | Whether picked marks emit click events. |
select | Optional[bool] | Whether shift-drag box selection is enabled. |
brush | Optional[bool] | Whether brush selection is enabled. |
crosshair | Optional[bool] | Whether plot-aligned hover guides are shown. |
navigation | Optional[bool] | Whether browser pan and zoom navigation is enabled. |
pan | Optional[bool] | Whether plain-drag panning is enabled. |
pan_axes | Optional[tuple[str, ...]] | Declared axis IDs translated by pan gestures. |
zoom | Optional[bool] | Whether viewport zoom is enabled. |
default_drag_action | Optional[DefaultDragAction] | Initial action performed by a plain plot drag. |
zoom_axes | Optional[tuple[str, ...]] | Declared axis IDs changed by zoom gestures and controls. |
zoom_limits | Optional[ZoomLimits] | Minimum and maximum magnification globally or by axis. |
wheel_zoom | Optional[bool] | Whether wheel and trackpad zoom is available. |
box_zoom | Optional[bool] | Whether box zoom is available as a drag action. |
zoom_buttons | Optional[bool] | Whether modebar Zoom In/Out commands are available. |
double_click_reset | Optional[bool] | Whether double-click restores ``reset_axes``. |
reset_axes | Optional[tuple[str, ...]] | Declared axis IDs restored by reset. |
link_group | Optional[str] | Identifier used to synchronize charts in the browser. |
link_axes | Optional[tuple[str, ...]] | Axes synchronized within the link group. |
FAQ
How do I make a heatmap in Python?
Pass a 2D array to xy.heatmap(z, x=x, y=y) inside xy.heatmap_chart(...) and
render it. The rendered heatmap graph pans, zooms, and hovers without extra
configuration.
How do I change the heatmap colors?
Set colormap on heatmap, for example colormap="viridis". Sequential maps
suit magnitudes; diverging maps read better around a midpoint.
How do I add a color scale legend to a heatmap?
Add to the chart to draw a visible scale tying each color back to a value.
How do I keep two heatmaps on the same color scale?
Set the same domain=(min, max) on both so the colors span an identical value
range instead of each rescaling to its own data.