histcounts2 — Count paired observations into two-dimensional histogram bins.

histcounts2(X, Y) bins paired observations from X and Y into a rectangular two-dimensional histogram. Each bin counts the number of pairs whose X component lies in a horizontal interval and whose Y component lies in a vertical interval, mirroring MathWorks MATLAB behaviour.

Syntax

[N, Xedges, Yedges] = histcounts2(X, Y)
[N, Xedges, Yedges] = histcounts2(X, Y, nbins)
[N, Xedges, Yedges] = histcounts2(X, Y, Xedges, Yedges)
[N, Xedges, Yedges] = histcounts2(___, Name, Value)
[N, Xedges, Yedges, binX, binY] = histcounts2(___)

• X and Y are numeric vectors (or arrays flattened column-major) of equal length holding paired observations.
• nbins is either a scalar bin count applied to both axes or a two-element vector [nX nY] giving separate counts for the X and Y axes.
• Xedges and Yedges are monotonically increasing edge vectors. Bin k covers [edge(k), edge(k+1)); the final bin also includes its right edge so maximum values are counted.
• Name/value options include 'Normalization' ('count', 'probability', 'pdf', 'countdensity', 'cumcount', 'cdf'), 'BinMethod', 'BinWidth', 'NumBins', 'XBinLimits', and 'YBinLimits'.
• With five outputs, binX and binY are integer indices the same size as the flattened inputs, giving the X- and Y-bin that each pair falls into (0 when an observation is excluded).

How histcounts2 works

• histcounts2(X, Y) flattens both inputs column-major, ensuring they contain the same number of elements, and fills a numel(Xedges) - 1 by numel(Yedges) - 1 matrix 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 X and Y axes.
• Name/value pairs such as 'NumBins', 'XBinEdges', 'YBinEdges', 'XBinWidth', 'YBinWidth', 'BinMethod', and 'Normalization' follow MATLAB precedence and validation rules.
• Pairs containing NaN in either coordinate are ignored. Infinite values participate when the chosen edges include them.

How RunMat runs 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") = 4

Using 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") = 4

Normalizing 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") = 2

Histogramming 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]

FAQ

Related Stats functions

Open-source implementation

Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how histcounts2 works, line by line, in Rust.

• View histcounts2.rs on GitHub
• Learn how the 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 — faster, on any GPU, with no license required.

• Simulations that took hours now take minutes. RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed.
• Start running code in seconds. Open the browser sandbox or download a single binary. No license server, no IT ticket, no setup.
• A full development environment. GPU-accelerated 2D and 3D plotting, automatic versioning on every save, and a browser IDE you can share with a link.

Getting started · Benchmarks · Pricing