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

Returns

Returned values from histcounts depend on how many outputs the caller requests.

Errors

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

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

Using histcounts with coding agents

Open a RunMat example with live inputs, then ask the agent to explain how histcounts changes the result.

FAQ

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.

Getting started · Benchmarks · Pricing