histc — Count values in legacy MATLAB histogram bins.
histc(x, binranges) counts values in legacy MATLAB histogram bins. Each bin includes its left endpoint and excludes its right endpoint, while the final bin counts values exactly equal to the last bin range value.
Syntax
bincounts = histc(x, binranges)
bincounts = histc(x, binranges, dim)
[bincounts, ind] = histc(x, binranges)
[bincounts, ind] = histc(x, binranges, dim)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
x | Any | Yes | — | Input values to sort into legacy bins. |
binranges | NumericArray | Yes | — | Monotonically nondecreasing bin endpoints. |
dim | NumericScalar | Yes | — | Dimension along which to operate. |
Returns
| Name | Type | Description |
|---|---|---|
bincounts | NumericArray | Legacy histogram bin counts. |
ind | NumericArray | One-based bin index for each input element, or zero when outside all bins. |
Returned values from histc depend on how many outputs the caller requests.
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:histc:InvalidArgument | Arguments are malformed, inconsistent, or unsupported. | histc: invalid argument |
RunMat:histc:Internal | Internal tensor conversion, GPU gather, or allocation fails. | histc: internal operation failed |
How histc works
- Vector inputs return counts with the same orientation as vector
binranges. - Matrix inputs operate down columns by default;
histc(x, binranges, dim)operates along the requested dimension. [bincounts, ind] = histc(...)returns one-based bin indices with the same shape asx; values outside the ranges or equal toNaNreceive index zero.- Empty
binrangesreturn empty count and index arrays. histcsupports at most two requested outputs.binrangesmust be monotonically nondecreasing and must not containNaN; repeated edges are allowed.- Complex inputs and complex bin ranges use their real parts, matching MATLAB's legacy behavior.
- Matrix
binrangesare interpreted column-by-column when the number of columns matches the number of operated slices.
Examples
Count ages in legacy bins
ages = [3 12 24 15 5 74 23 54 31 23 64 75];
binranges = [0 10 25 50 75];
[bincounts, ind] = histc(ages, binranges)Expected output:
bincounts = [2 5 1 3 1]
ind = [1 2 2 2 1 4 2 4 3 2 4 5]Operate along rows
x = [0 1 2; 2 3 4];
bincounts = histc(x, [0 2 4], 2)Expected output:
bincounts = [1 1 1; 0 1 1]Values outside the ranges
[bincounts, ind] = histc([-1 NaN 0.5 2 3], [0 1 2])Expected output:
bincounts = [1 0 1]
ind = [0 0 1 3 0]Using histc with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how histc changes the result.
Run a small histc example, explain the result, then change one input and compare the output.
FAQ
Should new code use histc?⌄
No. MATLAB marks histc as not recommended; use histcounts for new code. RunMat supports histc for backwards compatibility with existing scripts.
How does histc differ from histcounts?⌄
histc uses legacy bin ranges and includes a final equality-only bin at the last range value. histcounts returns modern edge-based bins and supports normalization and bin-selection options.
Does histc include out-of-range values?⌄
No. Values below the first range, above the last range, or equal to NaN do not contribute to counts and receive bin index zero.
Related Stats functions
Hist
Ml
bayesopt · classify · confusionmat · crossvalind · cvpartition · fitclinear · fitctree · fitlm · kmeans · knnsearch · lasso · lassoglm · linkage · lscov · mnrfit · optimizableVariable · pdist · pdist2 · perfcurve · predict · regress · ridge · squareform · test · training · tsne
Summary
binocdf · boxplot · cdf · cdfplot · chi2cdf · corr · corrcoef · corrcov · cov · cov2corr · dummyvar · ecdf · filloutliers · fitdist · geomean · grpstats · harmmean · icdf · isoutlier · kstest · kurtosis · lsline · mad · mode · nanmax · normalize · normcdf · norminv · normpdf · onehotdecode · onehotencode · pdf · prctile · quantile · refline · rmse · skewness · tabulate · tcdf · tiedrank · tinv · tpdf · ttest2 · wblinv
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how histc is executed, line by line, in Rust.
- View the source for histc 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.