{
"title": "subplot",
"category": "plotting",
"keywords": [
"subplot",
"subplot grid",
"multi-panel chart",
"matlab subplot",
"figure layout"
],
"summary": "Split a figure into subplot grids for multi-panel charts, side-by-side comparisons, and MATLAB `subplot` workflows.",
"requires_feature": null,
"tested": {
"unit": "builtins::plotting::subplot::tests"
},
"description": "`subplot(m, n, p)` selects an axes location inside an `m` by `n` figure grid and returns an axes handle for that slot. In RunMat, subplot selection is the backbone for axes-local plot state: legends, labels, log modes, view angles, and plot children all attach to the currently selected subplot unless an explicit handle is passed.",
"behaviors": [
"The returned value is an axes handle that can be passed explicitly to later plotting commands.",
"Subplot-local metadata stays isolated per axes: titles, legends, limits, log modes, and 3-D view state are all tracked independently.",
"Subsequent plotting commands operate on the selected subplot unless another axes handle is passed explicitly.",
"Indices are one-based in the MATLAB style. `subplot(2, 2, 3)` selects the third slot in row-major order."
],
"examples": [
{
"description": "Create a 2x2 subplot layout",
"input": "subplot(2, 2, 1);\nplot(0:0.1:1, (0:0.1:1).^2);\nsubplot(2, 2, 2);\nscatter(1:5, [5 4 3 2 1]);"
},
{
"description": "Capture and reuse an axes handle explicitly",
"input": "ax = subplot(1, 2, 2);\nplot(ax, 0:0.1:1, sin(0:0.1:1));\nget(ax, 'Type')",
"output": "ans =\n 'axes'"
},
{
"description": "Show that subplot-local state stays isolated",
"input": "subplot(1, 2, 1);\nsemilogx(logspace(0, 2, 50), logspace(0, 2, 50));\nsubplot(1, 2, 2);\nplot(1:5, 1:5);",
"output": "% Only the first subplot uses a logarithmic x-axis"
}
],
"faqs": [
{
"question": "How do I control the number of rows and columns in a subplot layout?",
"answer": "The first two arguments to `subplot(m, n, p)` set the grid dimensions: `m` rows and `n` columns. The third argument `p` selects which slot to activate, counted in row-major order starting at 1. `subplot(3, 1, 2)` gives you the middle row of a three-row single-column layout."
},
{
"question": "Can two subplots share the same x-axis range?",
"answer": "Set matching limits on both axes manually with `axis` or `set`. There's no automatic `linkaxes` yet, but explicit limits keep them in sync.\n\n```matlab\nsubplot(2, 1, 1); plot(0:10, rand(1, 11)); axis([0 10 0 1]);\nsubplot(2, 1, 2); plot(0:10, rand(1, 11)); axis([0 10 0 1]);\n```"
},
{
"question": "Can I make subplots of unequal sizes?",
"answer": "You can span multiple grid slots by passing a vector as the third argument. `subplot(2, 2, [1 2])` creates a subplot that spans the entire top row of a 2x2 grid, while the bottom row keeps two separate panels."
}
],
"links": [
{
"label": "plot",
"url": "./plot"
},
{
"label": "legend",
"url": "./legend"
},
{
"label": "get",
"url": "./get"
},
{
"label": "set",
"url": "./set"
},
{
"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/subplot.rs`",
"url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/plotting/ops/subplot.rs"
}
}