matplotlib.pyplot.hexbin#

matplotlib.pyplot.hexbin(x,y,C=None,*,gridsize=100,bins=None,xscale='linear',yscale='linear',extent=None,cmap=None,norm=None,vmin=None,vmax=None,alpha=None,linewidths=None,edgecolors='face',reduce_C_function=<functionmean>,mincnt=None,marginals=False,colorizer=None,data=None,**kwargs)[source]#

Make a 2D hexagonal binning plot of pointsx,y.

IfC isNone, the value of the hexagon is determined by the numberof points in the hexagon. Otherwise,C specifies values at thecoordinate (x[i], y[i]). For each hexagon, these values are reducedusingreduce_C_function.

Parameters:

x, yarray-like

The data positions.x andy must be of the same length.

Carray-like, optional

If given, these values are accumulated in the bins. Otherwise,every point has a value of 1. Must be of the same length asxandy.

gridsizeint or (int, int), default: 100

If a single int, the number of hexagons in thex-direction.The number of hexagons in they-direction is chosen such thatthe hexagons are approximately regular.

Alternatively, if a tuple (nx,ny), the number of hexagonsin thex-direction and they-direction. In they-direction, counting is done along vertically alignedhexagons, not along the zig-zag chains of hexagons; see thefollowing illustration.

(Sourcecode,2x.png,png)

To get approximately regular hexagons, choose\(n_x = \sqrt{3}\,n_y\).

bins'log' or int or sequence, default: None

Discretization of the hexagon values.

• IfNone, no binning is applied; the color of each hexagondirectly corresponds to its count value.

• If 'log', use a logarithmic scale for the colormap.Internally,\(log_{10}(i+1)\) is used to determine thehexagon color. This is equivalent tonorm=LogNorm().

• If an integer, divide the counts in the specified numberof bins, and color the hexagons accordingly.

• If a sequence of values, the values of the lower bound ofthe bins to be used.

xscale{'linear', 'log'}, default: 'linear'

Use a linear or log10 scale on the horizontal axis.

yscale{'linear', 'log'}, default: 'linear'

Use a linear or log10 scale on the vertical axis.

mincntint >= 0, default:None

If notNone, only display cells with at leastmincntnumber of points in the cell.

marginalsbool, default:False

If marginals isTrue, plot the marginal density ascolormapped rectangles along the bottom of the x-axis andleft of the y-axis.

extent4-tuple of float, default:None

The limits of the bins (xmin, xmax, ymin, ymax).The default assigns the limits based ongridsize,x,y,xscale andyscale.

Ifxscale oryscale is set to 'log', the limits areexpected to be the exponent for a power of 10. E.g. forx-limits of 1 and 50 in 'linear' scale and y-limitsof 10 and 1000 in 'log' scale, enter (1, 50, 1, 3).

Returns:

PolyCollection

APolyCollection defining the hexagonal bins.

• PolyCollection.get_offsets contains a Mx2 array containingthe x, y positions of the M hexagon centers in data coordinates.

• PolyCollection.get_array contains the values of the Mhexagons.

Ifmarginals isTrue, horizontalbar and vertical bar (both PolyCollections) will be attachedto the return collection as attributeshbar andvbar.

Other Parameters:

cmapstr orColormap, default:rcParams["image.cmap"] (default:'viridis')

The Colormap instance or registered colormap name used to map scalar datato colors.

normstr orNormalize, optional

The normalization method used to scale scalar data to the [0, 1] rangebefore mapping to colors usingcmap. By default, a linear scaling isused, mapping the lowest value to 0 and the highest to 1.

If given, this can be one of the following:

• An instance ofNormalize or one of its subclasses(seeColormap normalization).

• A scale name, i.e. one of "linear", "log", "symlog", "logit", etc. For alist of available scales, callmatplotlib.scale.get_scale_names().In that case, a suitableNormalize subclass is dynamically generatedand instantiated.

vmin, vmaxfloat, optional

When using scalar data and no explicitnorm,vmin andvmax definethe data range that the colormap covers. By default, the colormap coversthe complete value range of the supplied data. It is an error to usevmin/vmax when anorm instance is given (but using astrnormname together withvmin/vmax is acceptable).

alphafloat between 0 and 1, optional

The alpha blending value, between 0 (transparent) and 1 (opaque).

linewidthsfloat, default:None

IfNone, defaults torcParams["patch.linewidth"] (default:1.0).

edgecolors{'face', 'none',None} or color, default: 'face'

The color of the hexagon edges. Possible values are:

• 'face': Draw the edges in the same color as the fill color.

• 'none': No edges are drawn. This can sometimes lead to unsightlyunpainted pixels between the hexagons.

• None: Draw outlines in the default color.

• An explicit color.

reduce_C_functioncallable, default:numpy.mean

The function to aggregateC within the bins. It is ignored ifC is not given. This must have the signature:

defreduce_C_function(C:array)->float

Commonly used functions are:

• numpy.mean: average of the points

• numpy.sum: integral of the point values

• numpy.amax: value taken from the largest point

By default will only reduce cells with at least 1 point because somereduction functions (such asnumpy.amax) will error/warn with emptyinput. Changingmincnt will adjust the cutoff, and if set to 0 willpass empty input to the reduction function.

colorizerColorizer or None, default: None

The Colorizer object used to map color to data. If None, a Colorizerobject is created from anorm andcmap.

dataindexable object, optional

If given, the following parameters also accept a strings, which isinterpreted asdata[s] ifs is a key indata:

x,y,C

**kwargsPolyCollection properties

All other keyword arguments are passed on toPolyCollection:

Property	Description
agg_filter	a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image
alpha	array-like or float or None
animated	bool
antialiased oraa orantialiaseds	bool or list of bools
array	array-like or None
capstyle	CapStyle or {'butt', 'projecting', 'round'}
clim	(vmin: float, vmax: float)
clip_box	BboxBase or None
clip_on	bool
clip_path	Patch or (Path, Transform) or None
cmap	Colormap or str or None
color	color or list of RGBA tuples
edgecolor orec oredgecolors	color or list ofcolor or 'face'
facecolor orfacecolors orfc	color or list ofcolor
figure	Figure orSubFigure
gid	str
hatch	{'/', '\', '|', '-', '+', 'x', 'o', 'O', '.', '*'}
hatch_linewidth	unknown
in_layout	bool
joinstyle	JoinStyle or {'miter', 'round', 'bevel'}
label	object
linestyle ordashes orlinestyles orls	str or tuple or list thereof
linewidth orlinewidths orlw	float or list of floats
mouseover	bool
norm	Normalize or str or None
offset_transform ortransOffset	Transform
offsets	(N, 2) or (2,) array-like
path_effects	list ofAbstractPathEffect
paths	list of array-like
picker	None or bool or float or callable
pickradius	float
rasterized	bool
sizes	numpy.ndarray or None
sketch_params	(scale: float, length: float, randomness: float)
snap	bool or None
transform	Transform
url	str
urls	list of str or None
verts	list of array-like
verts_and_codes	unknown
visible	bool
zorder	float

See also

hist2d

2D histogram rectangular bins

Notes

Note

This is thepyplot wrapper foraxes.Axes.hexbin.

Examples usingmatplotlib.pyplot.hexbin#

Hexagonal binned plot

Hexagonal binned plot