histogram2 — Create two-dimensional histogram chart objects in MATLAB and RunMat.
histogram2(X,Y) bins paired observations with MATLAB-compatible histcounts2 semantics and creates a handle-backed 2-D histogram chart. RunMat renders the chart as a colormapped surface: DisplayStyle "bar3" uses bin counts as surface height, while "tile" renders a flattened heatmap-style view.
Syntax
h = histogram2(X, Y)
h = histogram2(X, Y, bins)
h = histogram2(X, Y, binsX, binsY)
h = histogram2(X, Y, Name, Value, ...)
h = histogram2(ax, X, Y)
h = histogram2(ax, X, Y, bins)All supported histogram2 forms
h = histogram2(X, Y)
h = histogram2(X, Y, bins)
h = histogram2(X, Y, binsX, binsY)
h = histogram2(X, Y, Name, Value, ...)
h = histogram2(ax, X, Y)
h = histogram2(ax, X, Y, bins)
h = histogram2(ax, X, Y, binsX, binsY)
h = histogram2(ax, X, Y, Name, Value, ...)
histogram2(X, Y)
histogram2(X, Y, bins)
histogram2(ax, X, Y)
histogram2(ax, X, Y, Name, Value, ...)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
X | Any | Yes | — | X-axis input samples. |
Y | Any | Yes | — | Y-axis input samples. |
bins | Any | Yes | — | Scalar/two-element bin count or edge specification. |
binsX | Any | Yes | — | X-axis bin count scalar or edge vector. |
binsY | Any | Yes | — | Y-axis bin count scalar or edge vector. |
nameValuePairs | Any | Variadic | — | Binning and chart name/value options. |
ax | AxesHandle | Yes | — | Target axes handle. |
Returns
| Name | Type | Description |
|---|---|---|
h | NumericScalar | Handle to the created histogram2 chart. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:histogram2:InvalidArgument | Input arrays, bin controls, or chart options are malformed. | histogram2: invalid argument |
RunMat:histogram2:Internal | RunMat cannot compute bins, register state, or render the chart. | histogram2: internal error |
How histogram2 works
histogram2(X,Y)requiresXandYto contain the same number of elements and ignores pairs containingNaN.- Positional bin arguments and name/value bin controls are forwarded through the same implementation as
histcounts2, includingNumBins, explicitXBinEdges/YBinEdges,BinWidth,BinLimits,BinMethod, axis-specific bin controls, and normalization modes. - Returned handles have type
histogram2and exposeValues,BinCounts,XBinEdges,YBinEdges,NumBins,Normalization,DisplayStyle,ShowEmptyBins,FaceAlpha, andDisplayNamethroughget. setsupports updatingNormalization,DisplayStyle,ShowEmptyBins,FaceAlpha, andDisplayName, rebuilding the rendered surface and handle state.- Common styling name/value pairs
FaceColor,EdgeColor,EdgeAlpha, andLineStyleare accepted for MATLAB script compatibility, but RunMat currently maps the chart through a colormapped surface backend rather than per-bin bar primitives.
Examples
Create a 2-D histogram with two bins per axis
h = histogram2([0; 0.2; 0.8; 1], [0; 0.1; 0.9; 1], [2 2]);
get(h, 'Values')Expected output:
ans =
2 0
0 2Use probability normalization and tile display
h = histogram2(x, y, 'NumBins', [20 10], 'Normalization', 'probability', 'DisplayStyle', 'tile');
get(h, 'Normalization')Expected output:
ans =
'probability'Inspect and update chart properties
h = histogram2(x, y, 'XBinEdges', 0:0.1:1, 'YBinEdges', -1:0.2:1);
set(h, 'DisplayStyle', 'tile', 'ShowEmptyBins', 'off');
get(h, 'NumBins')Expected output:
ans = [10 10]Using histogram2 with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how histogram2 changes the result.
Run a small histogram2 example, explain the result, then change one input and compare the output.
FAQ
How is histogram2 related to histcounts2?⌄
histogram2 uses the same binning and normalization logic as histcounts2, then wraps the resulting count matrix in a plotting object.
Which display styles are supported?⌄
'bar3' and 'tile' are supported. bar3 is rendered as a raised colormapped count surface; tile is rendered as a flattened colormapped surface with image-mode camera behavior.
Can histogram2 plot GPU arrays?⌄
Yes, but today it follows the underlying histcounts2 gather-immediate path and renders from the materialized bin grid. Future provider kernels can accelerate the binning stage without changing the plotting API.
Related Plotting functions
2D Charts
area · bar · errorbar · heatmap · hist · histogram · loglog · pie · plot · scatter · semilogx · semilogy · stairs · stem
Other
addpoints · ancestor · animatedline · axes · barh · caxis · cla · clf · clim · colorcube · colororder · copyobj · daspect · datacursormode · dataTipTextRow · fcontour · figure · fill · fill3 · findobj · fsurf · gobjects · groot · hgload · hgsave · hidden · hold · line · linkaxes · openfig · opengl · pan · parula · patch · plotmatrix · plotyy · polarhistogram · polarplot · polarscatter · print · quiver3 · ribbon · saveas · savefig · sphere · stackedplot · subtitle · suptitle · text · textscatter · textscatter3 · triplot · waitbar · wordcloud · xlabel · xlim · xline · xscale · xtickangle · xtickformat · xticklabels · xticks · ylabel · ylim · yline · yscale · ytickangle · ytickformat · yticklabels · yticks · zlim · zoom
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how histogram2 is executed, line by line, in Rust.
- View the source for histogram2 in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.