polarhistogram — Create histogram charts in polar coordinates.
polarhistogram(theta) bins angular samples in radians and renders each bin as a polar wedge whose radius is the bin count or normalized bin value. Theta values wrap periodically into the selected angular range. The returned handle reuses MATLAB-style histogram object properties such as BinEdges, BinCounts, Values, Data, NumBins, BinWidth, BinLimits, Normalization, DisplayStyle, FaceColor, FaceAlpha, EdgeColor, and DisplayName.
Syntax
h = polarhistogram(theta)
h = polarhistogram(theta, nbins)
h = polarhistogram(theta, edges)
h = polarhistogram(theta, Name, Value, ...)
h = polarhistogram(pax, ___)
h = polarhistogram('BinEdges', edges, 'BinCounts', counts)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
theta | Any | Yes | — | Angular sample data in radians. |
bins | Any | Yes | — | Bin count scalar or explicit edge vector in radians. |
args | Any | Variadic | — | Optional axes handle, bin specification, and name/value pairs. |
name_value | Any | Variadic | — | BinEdges/BinCounts pairs and optional style properties. |
Returns
| Name | Type | Description |
|---|---|---|
h | NumericScalar | Handle to the created polar histogram chart. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:polarhistogram:InvalidArgument | Input data, bin specification, axes targeting, or style arguments are invalid. | polarhistogram: invalid argument |
RunMat:polarhistogram:Internal | Internal polar histogram construction or rendering fails. | polarhistogram: internal operation failed |
How polarhistogram works
- All eight integer classes are accepted for angular data; native values gather authoritatively before the explicit floating binning and rendering boundary, while integer bin counts and table selectors remain structural.
polarhistogram(theta)creates a histogram object handle and marks the target axes as polar with equal x/y scaling. With no bin controls it uses six angular bins spanning[0, 2*pi].polarhistogram(theta, nbins)andpolarhistogram(theta, edges)use the same scalar bin-count and explicit edge-vector semantics ashistcounts.- Finite theta samples are wrapped into the chosen angular range before binning; non-finite samples are ignored by the histogram counts and exposed as
NaNin normalized storedData. - Name/value bin controls such as
BinEdges,NumBins,BinWidth,BinLimits,Normalization, andBinMethodare forwarded through the same binning implementation ashistogram. polarhistogram('BinEdges', edges, 'BinCounts', counts)creates a polar histogram from precomputed bin counts without sample data.DisplayStyleacceptsbarandstairs;stairsrenders the outer polar bin arcs without filled radial wedges.- Common bar styling arguments such as
FaceColor,EdgeColor,LineWidth,BarWidth,FaceAlpha, andDisplayNameare accepted. - The target axes form
polarhistogram(ax, ...)plots into an existing axes handle. - The returned handle has type
histogram;getexposes histogram state and supportedsetcalls updateNormalization,DisplayName,DisplayStyle,FaceColor,FaceAlpha, andEdgeColor.
Examples
Create a polar histogram
theta = 2*pi*rand(1, 1000);
h = polarhistogram(theta);Expected output:
% h is a histogram object handleUse explicit angular bin edges
theta = [0 0.2 1.0 2.0];
edges = 0:pi/4:2*pi;
h = polarhistogram(theta, edges);
get(h, 'BinEdges');Normalize and style the chart
theta = 2*pi*rand(1, 500);
h = polarhistogram(theta, 'NumBins', 16, 'Normalization', 'probability', 'FaceColor', 'red', 'DisplayName', 'angles');
get(h, 'Normalization')Expected output:
ans =
'probability'Plot precomputed polar bin counts with stairs display
edges = [0 pi 2*pi];
counts = [4 2];
h = polarhistogram('BinEdges', edges, 'BinCounts', counts, 'DisplayStyle', 'stairs');
get(h, 'BinCounts');Using polarhistogram with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how polarhistogram changes the result.
Run a small polarhistogram example, explain the result, then change one input and compare the output.
FAQ
Are theta values interpreted in degrees?⌄
No. Like MATLAB, polarhistogram interprets theta samples and explicit bin edges in radians.
Does polarhistogram return a special handle type?⌄
The returned object follows the histogram handle path, so get(h, 'Type') returns histogram and histogram properties such as BinEdges, BinCounts, Values, Data, NumBins, BinWidth, BinLimits, Normalization, DisplayStyle, and DisplayName are available.
What happens to angles outside 0 to 2*pi?⌄
Finite values are wrapped periodically into the selected angular range before binning. For example, 0, 2*pi, and -2*pi contribute to the same default angular bin.
Can polarhistogram plot GPU arrays?⌄
GPU-resident inputs are accepted through the underlying histogram evaluation path, but the current implementation gathers angular samples for binning before rendering polar wedge geometry. A direct provider binning fast path belongs to the queued GPU audit work.
Related Plotting functions
2D Charts
area · bar · errorbar · heatmap · hist · histogram · 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 · 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
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how polarhistogram is executed, line by line, in Rust.
- View the source for polarhistogram 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.