histogram — Create histogram chart objects in MATLAB and RunMat.
histogram creates object-style histograms using bin-edge semantics. Normalization options, bin controls, and returned handle properties follow MATLAB behavior.
Syntax
h = histogram(X)
h = histogram(X, bins)
h = histogram(X, Name, Value, ...)
h = histogram(X, bins, Name, Value, ...)
h = histogram(ax, X)
h = histogram(ax, X, bins)
h = histogram(ax, X, Name, Value, ...)
h = histogram(ax, X, bins, Name, Value, ...)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
X | Any | Yes | — | Input sample data. |
bins | Any | Yes | — | Bin count scalar or explicit edge vector. |
name_value | Any | Variadic | — | Name/value pairs for histogram options and styling. |
name_value | Any | Variadic | — | Additional name/value pairs for options and styling. |
ax | NumericScalar | Yes | — | Target axes handle. |
name_value | Any | Variadic | — | Name/value pairs for options and styling. |
Returns
| Name | Type | Description |
|---|---|---|
h | NumericScalar | Handle to the created histogram chart. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:histogram:InvalidArgument | Histogram input arrays, bins, or name/value options are malformed or incompatible. | histogram: invalid argument |
RunMat:histogram:Internal | Internal render preparation or histogram state registration fails. | histogram: internal operation failed |
How histogram works
histogram(data)creates a histogram object handle.- When you pass explicit bins through histogram-style arguments, they are treated as bin edges rather than bin centers.
- Normalization modes such as count, probability, percentage, density-style variants, and cumulative forms are part of the evaluation path.
- The returned histogram handle exposes properties like bin edges, counts, and normalization through
getand accepts updates throughsetwhere supported. - This is the preferred histogram API for new code; use
histonly when you intentionally want legacy center-based MATLAB semantics.
Examples
Create a histogram object from data
data = randn(1, 1000);
h = histogram(data);Expected output:
% h is a histogram object handleUse explicit bin edges and inspect the handle
data = randn(1, 500);
edges = -3:0.25:3;
h = histogram(data, 'BinEdges', edges);
get(h, 'BinEdges');Apply normalization through histogram semantics
data = randn(1, 500);
h = histogram(data, 'Normalization', 'probability');
get(h, 'Normalization')Expected output:
ans =
'probability'Overlaid distributions
a = 2 + 1.2*randn(1, 5000);
b = 4 + 0.8*randn(1, 5000);
h1 = histogram(a, 'BinEdges', -2:0.25:8, 'Normalization', 'probability');
set(h1, 'DisplayName', 'Process A');
hold on;
h2 = histogram(b, 'BinEdges', -2:0.25:8, 'Normalization', 'probability');
set(h2, 'DisplayName', 'Process B');
hold off;
title('Distribution Comparison');
xlabel('Measurement');
ylabel('Probability');
legend;
grid on;
Compare this result with other chart types in the MATLAB Plot Gallery.
Using histogram with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how histogram changes the result.
Run a small histogram example, explain the result, then change one input and compare the output.
FAQ
How do I set a specific number of bins?⌄
Pass the bin count as a second positional argument or use the 'NumBins' name-value pair.
data = randn(1, 1000);
histogram(data, 30); % 30 bins
histogram(data, 'NumBins', 50); % 50 bins
histogram(data, 'BinEdges', -3:0.1:3); % exact edgesExplicit BinEdges gives you full control over where each bin starts and ends.
How do I overlay two distributions on the same axes?⌄
Use hold on between histogram calls and set 'Normalization' to 'probability' so both distributions are on a comparable scale.
histogram(randn(1,1000), 'Normalization', 'probability');
hold on;
histogram(randn(1,1000) + 2, 'Normalization', 'probability');
legend('dist A', 'dist B');What's the difference between histogram and hist?⌄
histogram is the modern API: it uses bin-edge semantics, returns a handle object you can inspect with get/set, and supports normalization modes like 'probability' and 'pdf'. hist is the legacy API that interprets a second vector argument as bin centers. Use histogram for new code unless you specifically need center-based binning from a legacy workflow.
Related Plotting functions
2D Charts
area · bar · errorbar · heatmap · hist · loglog · pie · plot · scatter · semilogx · semilogy · stairs · stem
Other
addpoints · ancestor · animatedline · axes · barh · caxis · cla · clf · clim · colorcube · colororder · copyobj · daspect · datacursormode · dataTipTextRow · fcontour · figure · fill · fill3 · findobj · fsurf · gobjects · groot · hgload · hgsave · hidden · histogram2 · hold · line · linkaxes · openfig · opengl · pan · parula · patch · plotmatrix · plotyy · polarhistogram · polarplot · polarscatter · print · quiver3 · ribbon · saveas · savefig · sphere · stackedplot · subtitle · suptitle · text · textscatter · textscatter3 · triplot · waitbar · wordcloud · xlabel · xlim · xline · xscale · xtickangle · xtickformat · xticklabels · xticks · ylabel · ylim · yline · yscale · ytickangle · ytickformat · yticklabels · yticks · zlim · zoom
More plotting resources
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how histogram is executed, line by line, in Rust.
- View the source for histogram 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.