pie — Create pie charts in MATLAB and RunMat.
pie creates part-to-whole charts from numeric slice values. Handle behavior, explode controls, and labeling follow MATLAB semantics.
Syntax
h = pie(X)
h = pie(X, explode)
h = pie(X, labels)
h = pie(X, explode, labels)
h = pie(ax, ...)Inputs
X- Type
NumericArray- Required
- Yes
- Description
- Slice values.
explode- Type
NumericArray- Required
- Yes
- Description
- Slice explode mask (nonzero elements explode).
labels- Type
Any- Required
- Yes
- Description
- Label list or label format string.
ax- Type
NumericScalar- Required
- Yes
- Description
- Target axes handle.
data- Type
Any- Required
- Variadic
- Description
- Pie data arguments.
Returns
h- Type
NumericScalar- Description
- Handle to the pie chart.
Errors
RunMat:pie:InvalidArgument- When
- Pie values, explode vectors, or labels are malformed or incompatible.
- Message
pie: invalid argument
RunMat:pie:Internal- When
- Internal render preparation fails.
- Message
pie: internal operation failed
RunMat:plotting:TooManyOutputs- When
- More than one output is requested from a coordinate chart constructor.
- Message
plotting: too many output arguments
Behavior
Typed-integer slice values are a RunMat-mode extension and cross an exactness-checked floating renderer boundary; typed explode controls are interpreted structurally.
Slice values determine the relative angular extent of each wedge.
Explode-style workflows and slice labels are part of the pie rendering path.
The returned value is a pie-handle object participating in the same broader plotting handle model used across the plotting stack.
Pie labels and overlay semantics survive replay/export because they are part of the shared event/scene path.
Pie charts are especially useful as the part-to-whole complement to bar and histogram-style quantitative plots.
Runtime contract and boundaries
Catalog default bindings retain the actual RuntimeContext and original rooted BuiltinArguments across parsing, provider readback, delegated calls and completion. Value-selected axes, properties and output counts remain Runtime decisions. Constructor results are host double graphics handles, not numerical GPU arrays; hist instead returns double counts/centres, plotyy up to three distinct handle outputs, and plotmatrix up to five.
Rendering is a fusion boundary and requires the installed graphics host/device. A direct compatible renderer route is not an elementwise or reduction provider kernel. Resident buffers retain their owning provider and existing export/error/completion protocol; an export, readback, allocation, cancellation or emission failure is an error, not permission to replay an attempted operation. Source data and renderer caches have distinct lifetimes. No new distributed chart implementation is declared.
The existing canonical CoordinateWork allocation policy refuses Managed calls before unowned chart scratch, metadata, readback or scene mutation. It checks captured cancellation generation and policy before publication and on completion; ingress failures are Never replay. This is an explicit missing finite owner, not an allocation estimate, algorithm completion or L25 closure. Provider-private allocations, renderer lifetime accounting, synchronous long geometry/copy cooperation, measured throughput and physical presentation remain independent qualification gates.
Native Single/Double/integer source ownership is distinguished from explicit binary64/f32 graphics conversion. The renderer does not promise exact wide-integer pixel positions. Logical, complex, sparse, scalar, vector, matrix, empty and higher-rank forms follow the identity-specific parser rather than a universal implicit cast. Sparse/complex rejection is not an integer not-applicable audit. Full MATLAB properties, browser/native parity and empty-shape conformance are not inferred from migration or historical test references.
Supported representations and remaining forms
Accepted forms are nonnegative finite slice values with optional explode vector and labels/format, plus an optional full leading axes target. Slice integer data uses its existing exactness-checked RunMat extension before floating geometry. Explode controls are finite same-length numeric values interpreted by nonzero, not arbitrary plot labels; an attempted provider readback failure now propagates rather than being swallowed as a failed label probe.
Labels accept cell text, string arrays, text scalars or format strings; explicit labels must match slice count. Shared PieChart owns relative slice geometry, labels and default percentage presentation. The current public pie getter exposes Type/Parent/Children/DisplayName, not per-slice vertices or explode arrays: doc Figure witnesses do not pretend otherwise, and retained numerical/geometry Runtime fixtures are a distinct gate. Full MATLAB patch-array outputs and properties are not implemented by this scalar pie-handle owner.
Examples
Create a basic pie chart
pie([2 3 5]);Create an exploded pie chart
values = [4 2 3 1];
explode = [1 0 1 0];
pie(values, explode);Use labels for slice names
values = [5 3 2];
labels = {'compute', 'io', 'render'};
pie(values, labels);Budget allocation
values = [35 25 20 12 8];
labels = {'Engineering', 'Marketing', 'Operations', 'R&D', 'Admin'};
explode = [1 0 0 0 0];
pie(values, explode);
title('Annual Budget Allocation');
legend(labels);Rendered pie example
values = [35 25 20 12 8];
labels = {'Engineering', 'Marketing', 'Operations', 'R&D', 'Admin'};
explode = [1 0 0 0 0];
pie(values, explode);
title('Annual Budget Allocation');
legend(labels);
Compare this result with other chart types in the plot examples.
Using pie with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how pie changes the result.
Run a small pie example, explain the result, then change one input and compare the output.
FAQ
How do I explode specific slices out of the pie?⌄
Pass an explode vector the same length as your values. A 1 pulls that slice outward; a 0 keeps it flush.
pie([4 2 3 1], [0 1 0 0]);This explodes only the second slice. You can explode multiple slices by setting more entries to 1.
How do I add percentage labels to slices?⌄
By default, pie displays percentage labels on each slice. To use custom labels instead, pass a cell array of strings as the second argument.
pie([5 3 2], {'compute 50%', 'io 30%', 'render 20%'});If you want no labels at all, pass empty strings for each slice.
When should I use a pie chart vs a bar chart?⌄
Pie charts work well when you have a small number of slices (2–5) and the point is to show each slice's share of a whole. Once you go beyond ~6 slices or need to compare absolute values across categories, bar is almost always clearer—humans are better at comparing lengths than angles. If two slices are close in size and the difference matters, use bar.
Related Plotting functions
2D Charts
area · bar · errorbar · heatmap · hist · histogram · loglog · plot · scatter · semilogx · semilogy · stairs · stem
Other
addpoints · ancestor · animatedline · autumn · axes · barh · bone · caxis · cla · clf · clim · colorcube · colororder · cool · copper · copyobj · cylinder · daspect · datacursormode · dataTipTextRow · drawnow · fcontour · figure · fill · fill3 · findobj · fsurf · gobjects · gray · groot · hgload · hgsave · hidden · histogram2 · hold · hot · inferno · isgraphics · ishandle · jet · line · lines · linkaxes · magma · openfig · opengl · pan · parula · patch · pink · plasma · plotmatrix · plotyy · polarhistogram · polarplot · polarscatter · print · quiver3 · ribbon · saveas · savefig · sphere · spring · stackedplot · subtitle · summer · suptitle · text · textscatter · textscatter3 · triplot · turbo · viridis · waitbar · winter · wordcloud · xlabel · xlim · xline · xscale · xtickangle · xtickformat · xticklabels · xticks · ylabel · ylim · yline · yscale · ytickangle · ytickformat · yticklabels · yticks · zlim · zoom
More plotting resources
Source you can read
Every RunMat function's source is public. Read exactly how pie is executed, line by line, in Rust.
- View the source for pie 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.