What does the histcounts function do in MATLAB / RunMat?

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 does the histcounts function behave in MATLAB / RunMat?

• 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 into N equally 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.
• NaN values are ignored; Inf and -Inf participate when the edges cover them.

histcounts Function GPU Execution Behaviour

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 of using the histcounts function in MATLAB / RunMat

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 (counts will vary; edges obey Sturges' rule):

numel(counts) = ceil(log2(500) + 1);   % 10 bins

Normalising 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 arrays

Expected 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.

See Also

linspace, sum, mean, rand

Source & Feedback

• The full source code lives at crates/runmat-runtime/src/builtins/stats/hist/histcounts.rs.
• Found a discrepancy? Please open an issue with a minimal reproduction.