histcounts — Count observations in histogram bins in MATLAB and RunMat.
histcounts tallies how many values fall in each histogram bin. Explicit edges, bin-count/bin-width controls, and default bin selection follow MATLAB semantics.
Syntax
N = histcounts(X)
N = histcounts(X, bins)
N = histcounts(X, Name, Value, ...)
N = histcounts(X, bins, Name, Value, ...)
[N, edges] = histcounts(X)
[N, edges] = histcounts(X, bins)
[N, edges] = histcounts(X, Name, Value, ...)
[N, edges] = histcounts(X, bins, Name, Value, ...)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
X | Any | Yes | — | Input data values. |
bins | Any | Yes | — | Scalar NumBins or explicit edge vector. |
name_value | Any | Variadic | — | Name/value pairs (BinEdges, NumBins, BinWidth, BinLimits, Normalization, BinMethod). |
name_value | Any | Variadic | — | Additional name/value pairs. |
Returns
| Name | Type | Description |
|---|---|---|
N | NumericArray | Histogram bin counts. |
edges | NumericArray | Bin edge vector. |
Returned values from histcounts depend on how many outputs the caller requests.
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:histcounts:InvalidArgument | Arguments are malformed, inconsistent, or unsupported. | histcounts: invalid argument |
RunMat:histcounts:BinMethodConflict | BinMethod is combined with incompatible bin controls. | histcounts: BinMethod cannot be combined with BinEdges, NumBins, or BinWidth |
RunMat:histcounts:BinWidthInvalid | BinWidth is zero, negative, non-finite, or non-scalar. | histcounts: BinWidth must be a positive finite scalar |
RunMat:histcounts:Internal | Internal tensor conversion or allocation fails. | histcounts: internal operation failed |
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.
Does RunMat run 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]Using histcounts with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how histcounts changes the result.
Run a small histcounts example, explain the result, then change one input and compare the output.
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 is executed, line by line, in Rust.
- View the source for histcounts 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.