histcounts — Count observations in numeric arrays using configurable histogram bins.
histcounts tallies the number of elements that fall within each histogram bin. Bins can be specified explicitly, derived from a target bin width, or chosen by the default heuristics so that both simple and advanced workflows mirror MathWorks MATLAB semantics.
How histcounts works
histcounts(X)flattens numeric or logical inputs column-major and returns a row vector of counts spread across ten equal-width bins spanning the data range.histcounts(X, N)partitions the data intoNequally spaced bins.histcounts(X, edges)counts observations using the supplied bin edges.- Name/value pairs such as
'BinWidth','BinLimits','NumBins','BinEdges','BinMethod', and'Normalization'follow MATLAB's precedence rules and validation logic. - Values outside the bin limits are excluded. The last bin includes its upper edge while all other bins are half-open on the right.
NaNvalues are ignored;Infand-Infparticipate when the edges cover them.
How RunMat runs histcounts on the GPU
When the input arrives as a gpuArray, RunMat gathers the samples to host memory, executes the CPU reference implementation, and materialises the results as ordinary tensors. The builtin is registered as a sink, so fusion plans flush residency before histogramming and the outputs always live on the host today. The acceleration layer exposes a histcounts provider hook; once GPU kernels are implemented, existing code will pick up device-side execution automatically.
Examples
Counting values with custom bin counts
data = [1 2 2 4 5 7];
[counts, edges] = histcounts(data, 3)Expected output:
counts = [3 1 2];
edges = [1 3 5 7]Using explicit bin edges
edges = [0 1 2 3];
counts = histcounts([0.1 0.5 0.9 1.2 1.8 2.1], edges)Expected output:
counts = [3 2 1]Setting bin width and limits
[counts, edges] = histcounts([5 7 8 10 12], 'BinWidth', 2, 'BinLimits', [4 12])Expected output:
counts = [1 1 1 2];
edges = [4 6 8 10 12]Choosing an automatic binning method
[counts, edges] = histcounts(randn(1, 500), 'BinMethod', 'sturges')Expected output:
numel(counts) = ceil(log2(500) + 1); % 10 binsNormalising counts to probabilities
counts = histcounts([0.2 0.4 1.1 1.4 1.8 2.5], [0 1 2 3], 'Normalization', 'probability')Expected output:
counts = [0.3333 0.5000 0.1667]Building a cumulative distribution
counts = histcounts([1 2 2 3], [0 1 2 3], 'Normalization', 'cdf')Expected output:
counts = [0 0.25 1]Counting values stored on a GPU array
G = gpuArray([0.5 1.5 2.5]);
[counts, edges] = histcounts(G, [0 1 2 3]); % counts/edges return as CPU arraysExpected output:
counts = [1 1 1];
edges = [0 1 2 3]FAQ
Why does the last bin include its upper edge?⌄
To match MATLAB semantics each bin is [left, right) except for the final bin, which is [left, right]. This ensures the maximum finite value is always counted.
How are NaN values handled?⌄
They are ignored entirely and do not contribute to any bin count. Infinite values participate as long as the bin edges include them.
What happens when all observations are identical?⌄
RunMat mirrors MATLAB by collapsing the histogram to a single bin centred on the shared value unless you explicitly supply edges, limits, or a bin width.
Does histcounts support non-double inputs?⌄
Yes. Logical inputs are promoted to doubles, integer types are converted to double, and gpuArray inputs are gathered to host memory in this release.
Can I request both 'BinEdges' and 'BinWidth'?⌄
No. Bin specifications are mutually exclusive—choose one of 'BinEdges', 'BinWidth', or 'NumBins', optionally constrained by 'BinLimits'.
How do probability and PDF normalisations differ?⌄
'probability' scales counts so that they sum to one. 'pdf' divides by both bin width and the total count, matching MATLAB's probability-density definition.
Do outputs stay on the GPU when the input is a gpuArray?⌄
Until specialised provider hooks land, RunMat gathers GPU data to the CPU and returns host-resident outputs. Use gather only for clarity; the values are already in host memory.
Related Stats functions
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how histcounts works, line by line, in Rust.
- View histcounts.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.