{
"title": "pie",
"category": "plotting",
"keywords": [
"pie",
"pie chart",
"exploded pie chart",
"slice labels",
"matlab pie"
],
"summary": "Create pie charts for part-to-whole comparisons, exploded slices, and MATLAB `pie` workflows.",
"hero_image": "https://web.runmatstatic.com/builtin-image/runmat-matlab-plot-apie-budget.webp",
"requires_feature": null,
"tested": {
"unit": "builtins::plotting::pie::tests",
"integration": "runmat-plot/tests/renderer_tests.rs"
},
"description": "`pie` creates part-to-whole charts from numeric slice values. In RunMat it returns a pie handle, supports slice metadata and labels, and uses the shared plotting/replay/export stack so labels, explode state, and figure overlays stay consistent across interactive rendering and export paths.",
"behaviors": [
"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."
],
"examples": [
{
"description": "Create a basic pie chart",
"input": "pie([2 3 5]);"
},
{
"description": "Create an exploded pie chart",
"input": "values = [4 2 3 1];\nexplode = [1 0 1 0];\npie(values, explode);"
},
{
"description": "Use labels for slice names",
"input": "values = [5 3 2];\nlabels = {'compute', 'io', 'render'};\npie(values, labels);"
},
{
"description": "Budget allocation",
"input": "values = [35 25 20 12 8];\nlabels = {'Engineering', 'Marketing', 'Operations', 'R&D', 'Admin'};\nexplode = [1 0 0 0 0];\n\npie(values, explode);\ntitle('Annual Budget Allocation');\nlegend(labels);",
"image_webp": "https://web.runmatstatic.com/builtin-image/runmat-matlab-plot-apie-budget.webp"
}
],
"faqs": [
{
"question": "How do I explode specific slices out of the pie?",
"answer": "Pass an explode vector the same length as your values. A `1` pulls that slice outward; a `0` keeps it flush.\n\n```matlab\npie([4 2 3 1], [0 1 0 0]);\n```\n\nThis explodes only the second slice. You can explode multiple slices by setting more entries to `1`."
},
{
"question": "How do I add percentage labels to slices?",
"answer": "By default, `pie` displays percentage labels on each slice. To use custom labels instead, pass a cell array of strings as the second argument.\n\n```matlab\npie([5 3 2], {'compute 50%', 'io 30%', 'render 20%'});\n```\n\nIf you want no labels at all, pass empty strings for each slice."
},
{
"question": "When should I use a pie chart vs a bar chart?",
"answer": "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`."
}
],
"links": [
{
"label": "bar",
"url": "./bar"
},
{
"label": "histogram",
"url": "./histogram"
},
{
"label": "legend",
"url": "./legend"
},
{
"label": "Choosing the right plot type",
"url": "/docs/plotting/choosing-the-right-plot-type"
},
{
"label": "Styling plots and axes",
"url": "/docs/plotting/styling-plots-and-axes"
},
{
"label": "Plot replay and export",
"url": "/docs/plotting/plot-replay-and-export"
},
{
"label": "Complete plotting guide",
"url": "/blog/matlab-plotting-guide"
}
],
"source": {
"label": "`crates/runmat-runtime/src/builtins/plotting/ops/pie.rs`",
"url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/plotting/ops/pie.rs"
}
}