Skip to main content

Hexbin plot

A hexbin plot bins (x, y) scatter points into a regular hexagonal grid and colours each cell by the number of points in it — or by an aggregated third variable z. Hexagons tile the plane without gaps and sit equidistant from all six neighbours, so the density estimate is visually more uniform than a square grid's, and a colour bar is added in the right margin automatically.

SELECT kuva_render(to_json({
'title': 'Hexbin density',
'x_axis': {'name': 'x'},
'y_axis': {'name': 'y'},
'series': [{
'type': 'hexbin',
'x': list(x),
'y': list(y)
}]
})) AS chart
FROM read_csv_auto('{{DFK_BASE_URL}}data/hexbin.tsv');

x and y are two parallel lists — the same column pair you would hand a scatter plot, binned instead of drawn point by point.

Bin resolution​

n_bins is the number of hex columns across the x axis (default 20). Coarse bins make the overall shape obvious and lose the internal structure; fine bins reveal it and get noisier at the edges.

SELECT kuva_render(to_json({
'title': 'Coarse bins',
'x_axis': {'name': 'x'},
'y_axis': {'name': 'y'},
'series': [{
'type': 'hexbin',
'x': list(x),
'y': list(y),
'n_bins': 10
}]
})) AS chart
FROM read_csv_auto('{{DFK_BASE_URL}}data/hexbin.tsv');

bin_size sets an explicit hex circumradius in pixels instead, and overrides n_bins — useful when you want two charts to share a cell size rather than a column count.

Log colour scale​

When a few bins dominate the count, a linear scale saturates the colormap at the peak and hides everything else. log_color maps log₁₀(count + 1) instead, so the dense core and the sparse fringe stay readable at the same time; the colour bar keeps showing real counts.

SELECT kuva_render(to_json({
'title': 'Log colour scale',
'x_axis': {'name': 'x'},
'y_axis': {'name': 'y'},
'series': [{
'type': 'hexbin',
'x': list(x),
'y': list(y),
'log_color': true
}]
})) AS chart
FROM read_csv_auto('{{DFK_BASE_URL}}data/hexbin.tsv');

A third variable​

z replaces the count with an aggregate of a per-point measurement. Give z (one value per point) and a reduce:

reduceColour bar labelAggregates
"count"CountNumber of points in the bin (default)
"mean"MeanArithmetic mean of z
"sum"SumSum of the z values
"median"MedianMedian of the z values
"min"MinSmallest z value
"max"MaxLargest z value
SELECT kuva_render(to_json({
'title': 'Mean of a third variable',
'x_axis': {'name': 'x'},
'y_axis': {'name': 'y'},
'series': [{
'type': 'hexbin',
'x': list(x),
'y': list(y),
'z': list(z),
'reduce': 'mean',
'color_map': 'magma'
}]
})) AS chart
FROM read_csv_auto('{{DFK_BASE_URL}}data/hexbin.tsv');

Without z, every reduce mode falls back to the point count.

Normalised density​

normalize divides each bin's count by the total number of points, so the values are fractions in [0, 1] and the colour bar is relabelled Density. That is what makes two clouds of different sizes comparable on the same colour scale.

SELECT kuva_render(to_json({
'title': 'Fractional density',
'x_axis': {'name': 'x'},
'y_axis': {'name': 'y'},
'series': [{
'type': 'hexbin',
'x': list(x),
'y': list(y),
'normalize': true,
'colorbar_label': 'density'
}]
})) AS chart
FROM read_csv_auto('{{DFK_BASE_URL}}data/hexbin.tsv');

Min count filter​

min_count drops every bin with fewer than that many points, which trims the scattered periphery and leaves only the regions with real density.

SELECT kuva_render(to_json({
'title': 'Only dense bins',
'x_axis': {'name': 'x'},
'y_axis': {'name': 'y'},
'series': [{
'type': 'hexbin',
'x': list(x),
'y': list(y),
'n_bins': 15,
'min_count': 8
}]
})) AS chart
FROM read_csv_auto('{{DFK_BASE_URL}}data/hexbin.tsv');

Orientation and outlines​

Hexes are pointy-top by default (a vertex at the top); flat_top rotates them so an edge is on top. stroke and stroke_width draw a border around every hexagon, which separates neighbouring bins in the dense regions at the cost of a little more visual noise.

SELECT kuva_render(to_json({
'title': 'Flat-top hexes with outlines',
'x_axis': {'name': 'x'},
'y_axis': {'name': 'y'},
'series': [{
'type': 'hexbin',
'x': list(x),
'y': list(y),
'flat_top': true,
'stroke': '#333333',
'stroke_width': 0.8
}]
})) AS chart
FROM read_csv_auto('{{DFK_BASE_URL}}data/hexbin.tsv');

Clipping and colour range​

Two pairs of bounds do different jobs:

FieldEffect
x_range / y_rangeRestrict binning to a sub-region and fix the axis limits — points outside are silently dropped.
color_rangeClamp the colour scale to a fixed value interval; everything below takes the lowest colour, everything above the highest.

Clamping the colour scale is how you put two charts on the same scale, or zoom in on one density range.

SELECT kuva_render(to_json({
'title': 'Colour scale clamped to 2–8',
'x_axis': {'name': 'x'},
'y_axis': {'name': 'y'},
'series': [{
'type': 'hexbin',
'x': list(x),
'y': list(y),
'n_bins': 12,
'color_range': [2, 8]
}]
})) AS chart
FROM read_csv_auto('{{DFK_BASE_URL}}data/hexbin.tsv');

Colour maps and the colour bar​

color_map takes the same names the 2D histogram and heatmap use — see Colour maps for the full list; "viridis" is the default. colorbar: false hides the bar and reclaims the right margin.

Fields​

FieldTypeWhat it sets
x / ynumber[]Required. The point coordinates; two parallel lists of the same length.
znumber[]A third variable, one value per point (same length as x).
reducestringHow z is aggregated: "count" (default) · "mean" · "sum" · "median" · "min" · "max".
n_binsintegerHex columns across the x axis (default 20).
bin_sizenumberExplicit hex circumradius in pixels; overrides n_bins.
color_mapstringThe colormap.
log_colorbooleanTake log10 of the value before colouring.
min_countintegerDo not draw bins with fewer than this many points (default 1).
normalizebooleanDivide counts by the point total, giving fractional density.
colorbarbooleanDraw the colour bar (default on).
colorbar_labelstringOverride the colour bar's title.
strokestringHexagon outline colour.
stroke_widthnumberHexagon outline width in pixels (default 0.5).
flat_topbooleanFlat-top hexes instead of pointy-top.
x_range / y_range[number, number]Clip data and fix the axis extent.
color_range[number, number]Clamp the colour scale to this interval.

Notes​

  • x and y must be the same length, and neither may be empty.
  • z, when given, must match them too.
  • Hexagons are binned on the pixel canvas, not in data space — n_bins scales with the figure, which is why bin_size exists for comparisons across figures.
  • bin_size beats n_bins; color_range clamps the colour scale without touching the data.

See also​