{
"title": "scatter",
"category": "plotting",
"keywords": [
"scatter",
"scatter plot",
"2-D scatter",
"marker plot",
"matlab scatter",
"point cloud visualization"
],
"summary": "Create 2-D scatter plots for point clouds, size/color encoding, and MATLAB `scatter` workflows.",
"gpu_support": {
"elementwise": false,
"reduction": false,
"precisions": [
"single",
"double"
],
"broadcasting": "none",
"notes": "`scatter` is a rendering sink. GPU-resident inputs can stay on device when the shared plotting path can consume exported point buffers directly."
},
"fusion": {
"elementwise": false,
"reduction": false,
"max_inputs": 2,
"constants": "inline"
},
"requires_feature": null,
"tested": {
"unit": "builtins::plotting::scatter::tests",
"integration": "runmat-plot/tests/renderer_tests.rs"
},
"description": "`scatter` creates 2-D marker plots from paired x and y coordinates. In RunMat it returns a scatter handle, participates in the shared plotting property system, and supports the MATLAB `scatter(x, y, s, c, 'filled')` style of workflows for marker size, marker color, and display-name driven chart composition.",
"behaviors": [
"`scatter(x, y)` requires the same element count in both inputs.",
"The returned value is a scatter-handle object that can be inspected and updated through `get` and `set`.",
"Marker size, marker face color, marker edge color, and display name all flow through the shared plotting handle model.",
"Scatter plots integrate naturally with `subplot` and `legend`, so series labels and axes-local state stay scoped to the active axes.",
"GPU-resident point buffers can be rendered directly on the happy path; unsupported combinations fall back to host materialization while preserving the same visible result."
],
"examples": [
{
"description": "Create a basic 2-D scatter plot",
"input": "t = linspace(0, 2*pi, 100);\nscatter(cos(t), sin(t));"
},
{
"description": "Use marker sizing and color-style workflows",
"input": "x = linspace(0, 1, 25);\ny = x.^2;\nh = scatter(x, y);\nset(h, 'SizeData', 12, 'MarkerFaceColor', 'r', 'Marker', 'o');"
},
{
"description": "Drive the legend from scatter object display names",
"input": "x = 1:10;\nh1 = scatter(x, x);\nset(h1, 'DisplayName', 'linear');\nhold on;\nh2 = scatter(x, x.^2);\nset(h2, 'DisplayName', 'quadratic');\nlegend;"
}
],
"faqs": [
{
"question": "How do I color scatter points by a third variable?",
"answer": "Set the `CData` property on the scatter handle to a vector the same length as x and y. The values map into the current colormap.\n\n```matlab\nx = randn(1, 100);\ny = randn(1, 100);\nz = x.^2 + y.^2;\nh = scatter(x, y);\nset(h, 'CData', z);\ncolorbar;\n```\n\nEach point gets a color proportional to its `z` value. Call `colorbar` to show the mapping."
},
{
"question": "What's the difference between scatter and plot?",
"answer": "`scatter` draws unconnected markers and supports per-point size (`SizeData`) and per-point color (`CData`). `plot` connects points with lines and applies uniform styling to the whole series. Use `scatter` when the individual point properties carry meaning; use `plot` when the connection between points is what matters."
},
{
"question": "How do I control marker size in scatter?",
"answer": "Pass a scalar or vector to `SizeData` via the handle. A scalar sets uniform size; a vector sets per-point sizes.\n\n```matlab\nh = scatter(x, y);\nset(h, 'SizeData', 40); % uniform size\nset(h, 'SizeData', abs(y) * 50); % size proportional to |y|\n```\n\nThe size unit is points squared, matching MATLAB conventions."
}
],
"links": [
{
"label": "plot",
"url": "./plot"
},
{
"label": "scatter3",
"url": "./scatter3"
},
{
"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/scatter.rs`",
"url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/plotting/ops/scatter.rs"
},
"gpu_residency": "`scatter` preserves GPU residency when the plotting path can consume exported point buffers directly. If the active marker/style combination cannot use the direct path, RunMat gathers once and renders the same plot semantics on the fallback path.",
"gpu_behavior": [
"The direct path keeps point buffers on the device and avoids an unnecessary host round-trip for supported scatter workflows.",
"Marker styling and legend/display-name behavior stay consistent across GPU and host fallback rendering."
]
}