Bivariate distribution analysis
Explore the joint distribution of two numeric variables by showing where observations concentrate.
Plotly · Function
px.density_heatmap
px.density_heatmap creates an interactive 2D histogram, grouping x/y observations into bins and coloring each tile by count or an aggregation of z. Bin resolution and color mapping are configurable.
How it works
Pass tabular data and identify the two dimensions with x and y. Plotly groups points into rectangular bins and colors each bin by count by default; supplying z with histfunc changes the aggregation, while options such as nbinsx, nbinsy, and color_continuous_scale control presentation.
Syntax
px.density_heatmap(data_frame=None, x=None, y=None, z=None, histfunc=None, nbinsx=None, nbinsy=None, color_continuous_scale=None, **kwargs)Key points
- The chart represents a two-dimensional extension of a conventional histogram.
- Each observation is assigned to a rectangular bin according to its x and y values.
- Bin color can represent frequency, or an aggregation such as sum when a z variable is supplied.
- Adjust horizontal and vertical resolution independently with nbinsx and nbinsy.
- Use color_continuous_scale to choose how numeric bin values map to colors.
- The public Plotly Express entry point for this chart type is density_heatmap().
Common mistakes
- A z column alone is not enough to choose an aggregation explicitly; pair it with histfunc when the bin value should be summed, averaged, or otherwise aggregated.
Example: Binned tips distribution
import plotly.express as px
df = px.data.tips()
fig = px.density_heatmap(
df,
x="total_bill",
y="tip",
nbinsx=20,
nbinsy=20,
color_continuous_scale="Viridis",
)
fig.show()Creates an interactive 2D histogram from the built-in tips dataset, using explicit bin counts and a continuous color scale.
When to use it
Spatial aggregation over bins
Summarize a third numeric field within x/y regions using z and histfunc.
Resolution-controlled exploratory charts
Tune visual granularity for a dense dataset with separate horizontal and vertical bin counts.
Interview questions
QWhat does px.density_heatmap produce, and what is its default aggregate?
It creates a 2D histogram, also called a density heatmap. Points are grouped into bins by their x and y coordinates, and each tile is colored using a count by default.
Follow-up: How would you encode a value other than point frequency? Provide z and select the desired aggregation with histfunc.
QHow do you control bin resolution and colors?
Use nbinsx and nbinsy to control the number of bins along the two axes. Use color_continuous_scale to select the color mapping for the resulting values.
Follow-up: How could you show the same distribution beside the main chart? Add marginal_x or marginal_y with a supported marginal plot type.
QWhich data shapes can the function accept?
The function accepts long-form data and also supports wide-form and mixed-form inputs because it is one of Plotly Express's 2D-Cartesian functions. With a DataFrame, column names can be supplied as strings.
Follow-up: What should you verify when using wide-form input? Confirm that the inferred index and columns represent the intended axes and variables.
Related
px.density_contourpx.histogrammarginal_xmarginal_ynbinsxnbinsycolor_continuous_scalehistfunc