RunMat
  • Pricing
RunMat
GitHub
GitHub
Sign inTry in browser
DesktopRuntimePhysicsCADAdministrationAgent

Get RunMat updates

New releases, guides and examples.

Product+
  • Runtime
  • GPU
  • Parallel
  • Compile
  • Interop and MEX
  • Simulation
  • MCAD
  • ECAD
  • Enterprise
  • AI integrations
  • Pricing
  • Download
Math+
  • Signal processing
  • Linear algebra
  • Statistics
  • Curve fitting
  • Differential equations
  • Control systems
  • Optimization
  • Finance
  • Data and tables
  • Plotting
Physics+
  • Simulation overview
  • Structural
  • Thermal
  • Electromagnetic
  • Joule heating
  • Thermal stress
  • Acoustics
  • Fluid flow
  • Conjugate heat transfer
  • Fluid–structure
  • What is FEA
Industries+
  • Aerospace
  • Automotive and transportation
  • Defense
  • Electronics and semiconductors
  • Energy
  • Industrial machinery
  • Life sciences
  • Quantitative finance
Learn+
  • Guides
  • Docs
  • Function reference
  • Language reference
  • Migration guide
  • Changelog
  • MATLAB Online
  • MATLAB AI agent
  • For students
Compare+
  • RunMat vs MATLAB
  • RunMat vs Ansys
  • RunMat vs SOLIDWORKS
  • RunMat vs Altium
  • RunMat vs Cadence
  • RunMat vs COMSOL
  • RunMat vs Python
  • RunMat vs Julia
  • RunMat vs Physics AI
  • RunMat vs Octave
  • Benchmarks
  • MATLAB alternatives
  • All comparisons
Company+
  • About
  • Blog
  • Contact
  • Source code↗
  • License
  • Privacy
  • Terms

Product

  • Runtime
  • GPU
  • Parallel
  • Compile
  • Interop and MEX
  • Simulation
  • MCAD
  • ECAD
  • Enterprise
  • AI integrations
  • Pricing
  • Download

Math

  • Signal processing
  • Linear algebra
  • Statistics
  • Curve fitting
  • Differential equations
  • Control systems
  • Optimization
  • Finance
  • Data and tables
  • Plotting

Physics

  • Simulation overview
  • Structural
  • Thermal
  • Electromagnetic
  • Joule heating
  • Thermal stress
  • Acoustics
  • Fluid flow
  • Conjugate heat transfer
  • Fluid–structure
  • What is FEA

Industries

  • Aerospace
  • Automotive and transportation
  • Defense
  • Electronics and semiconductors
  • Energy
  • Industrial machinery
  • Life sciences
  • Quantitative finance

Learn

  • Guides
  • Docs
  • Function reference
  • Language reference
  • Migration guide
  • Changelog
  • MATLAB Online
  • MATLAB AI agent
  • For students

Compare

  • RunMat vs MATLAB
  • RunMat vs Ansys
  • RunMat vs SOLIDWORKS
  • RunMat vs Altium
  • RunMat vs Cadence
  • RunMat vs COMSOL
  • RunMat vs Python
  • RunMat vs Julia
  • RunMat vs Physics AI
  • RunMat vs Octave
  • Benchmarks
  • MATLAB alternatives
  • All comparisons

Company

  • About
  • Blog
  • Contact
  • Source code↗
  • License
  • Privacy
  • Terms
GitHubXLinkedIn

© Dystr, Inc. · RunMat v0.7.1, Nov 17, 2026

RunMat® is a registered trademark of Dystr, Inc. MATLAB® is a registered trademark of The MathWorks, Inc. RunMat is not affiliated with, endorsed by, or sponsored by The MathWorks, Inc.

/
See all docs
Builtin Reference
    • histc
    • histcounts
    • histcounts2

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.
NameTypeRequiredDefaultDescription
XAnyYes—Input data values.
binsAnyYes—Scalar NumBins or explicit edge vector.
name_valueAnyVariadic—Name/value pairs (BinEdges, NumBins, BinWidth, BinLimits, Normalization, BinMethod).
name_valueAnyVariadic—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.
NameTypeDescription
NNumericArrayHistogram bin counts.
edgesNumericArrayBin edge vector.
binNumericArrayOne-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
IdentifierWhenMessage
RunMat:histcounts:InvalidArgumentArguments are malformed, inconsistent, or unsupported.histcounts: invalid argument
RunMat:histcounts:BinMethodConflictBinMethod is combined with incompatible bin controls.histcounts: BinMethod cannot be combined with BinEdges, NumBins, or BinWidth
RunMat:histcounts:BinWidthInvalidBinWidth is zero, negative, non-finite, or non-scalar.histcounts: BinWidth must be a positive finite scalar
RunMat:histcounts:EdgePrecisionInteger-aligned unit bin boundaries cannot be represented distinctly by the double edge output.histcounts: integer-aligned bin boundaries cannot be represented distinctly as double
RunMat:histcounts:InternalInternal tensor conversion or allocation fails.histcounts: internal operation failed

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

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

histc · histcounts2

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

Random

binornd · bootstrp · datasample · dividerand · exprnd · gamrnd · gpurng · lhsdesign · mvnrnd · normrnd · random · randsample · rng · trnd · unidrnd · unifrnd · wblrnd

Options

statget · statset

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.

Getting started · Benchmarks · Pricing

Download RunMat

Download RunMat for full performance, or use RunMat in your browser for zero setup.

Download RunMatOpen Sandbox
On this page
  • Syntax
  • Inputs
  • Returns
  • Errors
  • Behavior
  • Classes and execution
  • Examples
  • Locate each observation's bin
  • Counting values with custom bin counts
  • Using explicit bin edges
  • Setting bin width and limits
  • Choosing an automatic binning method
  • Normalising counts to probabilities
  • Building a cumulative distribution
  • Counting values stored on a GPU array
  • Using histcounts with coding agents
  • FAQ
  • Related Stats functions
  • Hist
  • Summary
  • Ml
  • Random
  • Options
  • Source you can read
  • About RunMat