Joint-distribution visualization
Explore the joint distribution of two numeric variables by showing how many observations fall into each x/y region.
Plotly · Class
go.Histogram2d
go.Histogram2d is a Plotly graph-object trace for visualizing paired x/y data as a two-dimensional binned heatmap. Bins can show point counts or aggregate supplied z values.
How it works
Histogram2d groups paired x and y values into two-dimensional bins and renders each bin as a heatmap tile. By default, each tile represents the count of points in that bin; providing z enables aggregation such as a sum.
Syntax
go.Histogram2d(arg=None, autobinx=None, autobiny=None, bingroup=None, histfunc=None, histnorm=None, x=None, xbins=None, y=None, ybins=None, z=None, **kwargs)Parameters
| Name | Type | Description |
|---|---|---|
x | array-like | Values used for the x coordinates of the input points. |
y | array-like | Values used for the y coordinates of the input points. |
z | array-like | Optional values aggregated within bins when an aggregation function such as sum is used. |
autobinx | boolean | Controls whether bin boundaries are automatically determined. |
autobiny | boolean | Controls automatic determination of y-axis bins. |
xbins | dict | Explicit x-axis bin settings such as start, end, and size. |
ybins | dict | Explicit y-axis bin settings such as start, end, and size. |
histnorm | enumeration | Normalizes the histogram values, for example to probability. |
Returns
A Plotly graph-object histogram2d trace.
Key points
- The trace produces a two-dimensional histogram commonly visualized as a density heatmap.
- Each point is assigned to a bin using its x and y coordinates.
- Bin values can use counting by default or aggregate supplied z values, including summation.
- Use the graph-object class directly when constructing a figure without Plotly Express.
- Use bingroup when multiple histograms need compatible bin settings.
Common mistakes
- Use xbins and ybins when the two axes require different bin boundaries or sizes.
Example: Basic 2D histogram
import numpy as np
import plotly.graph_objects as go
rng = np.random.default_rng(1)
x = rng.normal(size=500)
y = rng.normal(loc=1, size=500)
fig = go.Figure(go.Histogram2d(x=x, y=y))
fig.show()Creates and displays a 2D histogram from paired x and y samples.
When to use it
Binned z-value aggregation
Summarize a third value per spatial or coordinate bin by supplying z and an aggregation function.
Comparable multi-trace binning
Compare multiple two-dimensional histograms while keeping their bin definitions compatible.
Interview questions
QWhat does go.Histogram2d represent?
Histogram2d is the graph-object trace used to create a two-dimensional histogram. It groups points by x and y coordinates into bins and displays the resulting bin values as heatmap-like tiles.
Follow-up: How can binning be controlled independently? Set xbins and ybins with explicit start, end, and size values.
QHow are tile values calculated?
With only x and y, the trace counts points in each two-dimensional bin. If z is supplied, an aggregation function such as sum can compute the tile value from z values in that bin.
Follow-up: Which other aggregation choices are documented? The 2D histogram examples also describe count and sum; the reference trace supports additional histogram-function options.
QHow do you create and display one?
Construct the trace with go.Histogram2d(x=..., y=...) and place it in a go.Figure. Calling fig.show() displays the interactive chart.
Follow-up: How would you normalize the result? Pass a histnorm option to the trace, as shown in the 2D histogram examples.
Related
HistogramHistogram2dContourFigureplotly.graph_objects