histcounts — Count observations in histogram bins in MATLAB and RunMat.
histcounts tallies how many values fall in each histogram bin. Its optional third output gives one-based bin indices in the input shape, with zero for excluded values. 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)All supported histcounts forms
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, ...)
[N, edges, bin] = histcounts(X)
[N, edges, bin] = histcounts(X, bins)
[N, edges, bin] = histcounts(X, Name, Value, ...)
[N, edges, bin] = histcounts(X, bins, Name, Value, ...)Inputs
X- Type
Any- Required
- Yes
- Description
- Input data values.
bins- Type
Any- Required
- Yes
- Description
- Scalar NumBins or explicit edge vector.
name_value- Type
Any- Required
- Variadic
- Description
- Name/value pairs (BinEdges, NumBins, BinWidth, BinLimits, Normalization, BinMethod).
name_value- Type
Any- Required
- Variadic
- Description
- Additional name/value pairs.
Returns
N- Type
NumericArray- Description
- Histogram bin counts.
edges- Type
NumericArray- Description
- Bin edge vector.
bin- Type
NumericArray- Description
- One-based bin indices in the shape of X; zero for excluded observations.
Returned values from histcounts depend on how many outputs the caller requests.
Errors
RunMat:histcounts:InvalidArgument- When
- Arguments are malformed, inconsistent, or unsupported.
- Message
histcounts: invalid argument
RunMat:histcounts:BinMethodConflict- When
- BinMethod is combined with incompatible bin controls.
- Message
histcounts: BinMethod cannot be combined with BinEdges, NumBins, or BinWidth
RunMat:histcounts:BinWidthInvalid- When
- BinWidth is zero, negative, non-finite, or non-scalar.
- Message
histcounts: BinWidth must be a positive finite scalar
Behavior
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.
Classes and execution
Counts and edges are host double arrays. For explicit integer edges, fixed-width integer observations are compared exactly, including values beyond flintmax; generated and returned edges are double. Integer-aligned unit bins require distinct double boundaries; RunMat reports an edge-precision error when they cannot be represented.
Resident inputs are gathered through the owning provider before the CPU histogram runs. This materializing operation has no implemented provider reduction or fusion kernel. 64-bit integer gpuArray inputs are rejected before gathering.
Examples
Locate each observation's bin
data = [0 NaN 1 2 3];
[counts, edges, bin] = histcounts(data, [0 1 2 3])Expected output:
counts = [1 1 2];
edges = [0 1 2 3];
bin = [1 0 2 3 3]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');
numel(counts)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 observations retain their exact values for bin comparisons, 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?⌄
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
Hist
Summary
anova1 · binocdf · binscatter · boxplot · cdf · cdfplot · chi2cdf · corr · corrcoef · corrcov · cov · cov2corr · dummyvar · ecdf · filloutliers · fitdist · geomean · grpstats · harmmean · icdf · isoutlier · ksdensity · kstest · kurtosis · lsline · mad · mode · nanmax · normalize · normcdf · norminv · normpdf · onehotdecode · onehotencode · pca · pdf · prctile · qqplot · quantile · refline · rmse · scatterhist · skewness · tabulate · tcdf · tiedrank · tinv · tpdf · ttest · ttest2 · wblinv
Ml
bayesopt · classify · confusionmat · crossvalind · cvpartition · fitclinear · fitctree · fitlm · kmeans · knnsearch · lasso · lassoglm · linkage · lscov · mnrfit · nlparci · optimizableVariable · pdist · pdist2 · perfcurve · predict · regress · ridge · squareform · test · training · tsne
Source you can read
Every RunMat function's source is public. 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 a runtime that executes MATLAB-syntax code fast on any GPU. The runtime is free for individuals, including freelancers; students and faculty at an academic institution, for teaching or research there; contributors to an open-source project, for work on that project; organizations with 250 or fewer people and US$10M or less in annual revenue; and anyone, for non-production use. See runmat.com/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.