histcounts2 — Count paired observations in 2-D histogram bins in MATLAB and RunMat.
histcounts2(X, Y) bins paired observations into a rectangular two-dimensional histogram. Edge handling, bin controls, and output layout follow MATLAB semantics.
Syntax
N = histcounts2(X, Y)
N = histcounts2(X, Y, bins)
N = histcounts2(X, Y, binsX, binsY)
N = histcounts2(X, Y, Name, Value, ...)
[N, Xedges] = histcounts2(X, Y)
[N, Xedges] = histcounts2(X, Y, bins)All supported histcounts2 forms
N = histcounts2(X, Y)
N = histcounts2(X, Y, bins)
N = histcounts2(X, Y, binsX, binsY)
N = histcounts2(X, Y, Name, Value, ...)
[N, Xedges] = histcounts2(X, Y)
[N, Xedges] = histcounts2(X, Y, bins)
[N, Xedges, Yedges] = histcounts2(X, Y)
[N, Xedges, Yedges] = histcounts2(X, Y, binsX, binsY)
[N, Xedges, Yedges] = histcounts2(X, Y, Name, Value, ...)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
X | Any | Yes | — | X-axis input data. |
Y | Any | Yes | — | Y-axis input data. |
bins | Any | Yes | — | NumBins scalar/vector or positional edge specification. |
binsX | Any | Yes | — | X-axis NumBins scalar or edge vector. |
binsY | Any | Yes | — | Y-axis NumBins scalar or edge vector. |
name_value | Any | Variadic | — | Name/value pairs controlling binning and normalization. |
Returns
| Name | Type | Description |
|---|---|---|
N | NumericArray | 2-D histogram bin counts. |
Xedges | NumericArray | X-axis bin edges. |
Yedges | NumericArray | Y-axis bin edges. |
Returned values from histcounts2 depend on how many outputs the caller requests.
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:histcounts2:InvalidArgument | Arguments are malformed, inconsistent, or unsupported. | histcounts2: invalid argument |
RunMat:histcounts2:NumBinsInvalid | NumBins is zero, negative, non-finite, or non-integer. | histcounts2: NumBins must be a positive finite scalar |
RunMat:histcounts2:BinMethodConflict | BinMethod is combined with incompatible bin controls. | histcounts2: BinMethod cannot be combined with BinEdges, NumBins, or BinWidth |
RunMat:histcounts2:Internal | Internal tensor conversion or allocation fails. | histcounts2: internal operation failed |
How histcounts2 works
histcounts2(X, Y)flattens both inputs column-major, ensuring they contain the same number of elements, and fills anumel(Xedges) - 1bynumel(Yedges) - 1matrix of bin counts.- Bins are half-open on the right except for the last column and row, which include their upper edges so the maximum finite values are counted.
- Optional arguments let you specify bin counts, explicit edges, bin limits, bin widths, and automatic binning heuristics independently for the
XandYaxes. - Name/value pairs such as
'NumBins','XBinEdges','YBinEdges','XBinWidth','YBinWidth','BinMethod', and'Normalization'follow MATLAB precedence and validation rules. - Pairs containing
NaNin either coordinate are ignored. Infinite values participate when the chosen edges include them.
Does RunMat run histcounts2 on the GPU?
When either input is a gpuArray, RunMat gathers the samples back to host memory, performs the reference CPU implementation, and returns dense CPU tensors for the histogram and edges. The acceleration layer exposes a histcounts2 provider hook; once kernels land, the runtime will automatically keep residency on the GPU and skip gathering. The builtin is registered as a sink, so fusion plans flush GPU residency before histogramming and the current implementation always yields host-resident outputs.
GPU memory and residency
As with other RunMat histogram routines, you do not need to call gpuArray explicitly just to obtain GPU execution. Once providers implement the histcounts2 hook, the fusion planner will keep residency on the device automatically. Until then, the builtin gathers data to the host and returns CPU tensors even when inputs originate on the GPU, matching MATLAB semantics after an explicit gather.
Examples
Counting paired values with explicit edges
X = [0.5 1.5 2.5 3.5];
Y = [0.2 0.9 1.4 2.8];
[N, Xedges, Yedges] = histcounts2(X, Y, [0 1 2 3 4], [0 1 2 3])Expected output:
N = [1 0 0; 1 0 0; 0 1 0; 0 0 1];
Xedges = [0 1 2 3 4];
Yedges = [0 1 2 3]Specifying separate bin counts for each axis
X = [1 2 3 4];
Y = [1 2 3 4];
N = histcounts2(X, Y, 2, 4)Expected output:
size(N) = [2 4];
sum(N, "all") = 4Using different bin widths for X and Y
X = [1 1.5 2.4 3.7];
Y = [2 2.2 2.9 3.1];
[N, Xedges, Yedges] = histcounts2(X, Y, 'XBinWidth', 1, 'YBinWidth', 0.5)Expected output:
diff(Xedges) = [1 1 1];
diff(Yedges(1:3)) = [0.5 0.5];
sum(N, "all") = 4Normalizing a 2-D histogram to probabilities
X = [0.2 0.4 1.1 1.5];
Y = [0.1 0.8 1.2 1.9];
N = histcounts2(X, Y, [0 1 2], [0 1 2], 'Normalization', 'probability')Expected output:
N = [0.5 0.0; 0.0 0.5]Ignoring NaN values in paired data
X = [1 2 NaN 3];
Y = [2 2 2 NaN];
N = histcounts2(X, Y, [0 1 2 3], [0 1 2 3])Expected output:
sum(N, "all") = 2Histogramming gpuArray inputs without manual gather
Gx = gpuArray([0.5 1.5 2.5]);
Gy = gpuArray([1.0 1.1 2.9]);
[counts, Xedges, Yedges] = histcounts2(Gx, Gy, [0 1 2 3], [0 2 3])Expected output:
isa(counts, 'double') % counts are returned on the CPU
counts = [1 0; 1 0; 0 1]Using histcounts2 with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how histcounts2 changes the result.
Run a small histcounts2 example, explain the result, then change one input and compare the output.
FAQ
Do X and Y need the same size?⌄
Yes. histcounts2 requires both inputs to contain the same number of elements. RunMat mirrors MATLAB by raising an error when the sizes do not match.
How are the bin edges interpreted?⌄
All interior bins are [left, right), while the last row and column are [left, right], so the largest finite values are counted.
What happens to NaN, Inf, or -Inf values?⌄
Pairs containing NaN in either coordinate are ignored. Infinite values participate when the specified edges include them; otherwise, they are excluded just like MATLAB.
Can I mix explicit edges on one axis with automatic binning on the other?⌄
Yes. You can supply 'XBinEdges' while leaving the Y axis to be determined by 'NumBins', 'YBinWidth', or the default heuristics.
Which normalisation modes are supported?⌄
'count', 'probability', 'countdensity', 'pdf', 'cumcount', and 'cdf' are implemented. 'cdf' and 'cumcount' operate in column-major order so the result matches MATLAB's cumulative behaviour.
How do I request integer-aligned bins?⌄
Use 'BinMethod', 'integers' or 'XBinMethod'/'YBinMethod' with the value 'integers'. RunMat ensures the resulting edges align with integer boundaries, respecting any supplied bin limits.
What does histcounts2 do in MATLAB?⌄
histcounts2 bins paired observations into a two-dimensional histogram. It accepts two vectors X and Y of equal length and returns a matrix of bin counts plus the bin edges for each axis.
How is histcounts2 different from histcounts?⌄
histcounts bins data along a single dimension, while histcounts2 bins paired data along two dimensions simultaneously, producing a 2-D count matrix.
Can I use histcounts2 on GPU arrays in RunMat?⌄
Yes. RunMat supports histcounts2 on GPU arrays with f32 and f64 precision. GPU providers can attach a device kernel for full hardware acceleration.
What's the relationship between N, Xedges, and Yedges?⌄
The count matrix N has size (length(Xedges)-1) × (length(Yedges)-1): one row per X bin and one column per Y bin. Each bin covers the half-open interval [edge(k), edge(k+1)), except the final row and column, which include their upper edge so the largest finite values are counted.
How do I get a 2-D probability density from histcounts2?⌄
Pass 'Normalization', 'pdf', for example [N, Xedges, Yedges] = histcounts2(X, Y, 'Normalization', 'pdf'). Each bin value is divided by the bin area and by the total number of pairs, so sum(N .* diff(Xedges)' .* diff(Yedges), 'all') equals 1 when no samples fall outside the bin limits.
How do I use explicit bin edges with histcounts2?⌄
Supply two monotonically increasing edge vectors as the third and fourth arguments, for example Xedges = 0:0.1:1; Yedges = 0:0.1:1; N = histcounts2(X, Y, Xedges, Yedges). This gives you full control over bin placement and is the easiest way to reproduce a 2-D histogram across multiple datasets.
Related Stats functions
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how histcounts2 is executed, line by line, in Rust.
- View the source for histcounts2 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.