textscatter — Create a 2-D text scatter chart from x/y coordinates and text labels.
textscatter(x,y,str) creates a text scatter chart with labels from str at matching x/y coordinates. textscatter(xy,str) accepts an N-by-2 coordinate matrix. The returned handle is a textscatter chart object with MATLAB-style data and display properties.
Syntax
ts = textscatter(x, y, str)
ts = textscatter(xy, str)
ts = textscatter(ax, ...)
ts = textscatter(..., Name, Value)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
x | NumericArray | Yes | — | X coordinates. |
y | NumericArray | Yes | — | Y coordinates. |
str | Any | Yes | — | String vector or cell array of character vectors. |
xy | NumericArray | Yes | — | N-by-2 coordinate matrix. |
props | Any | Variadic | — | Name/value TextScatter properties. |
Returns
| Name | Type | Description |
|---|---|---|
ts | NumericScalar | Handle to the TextScatter chart object. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:textscatter:InvalidArgument | Coordinates, text labels, axes target, or TextScatter property values are invalid. | textscatter: invalid argument |
RunMat:textscatter:Internal | Internal plotting state update fails while creating or mutating TextScatter. | textscatter: internal operation failed |
How textscatter works
x,y, andstrmust have equal element counts.xymust be an N-by-2 matrix whose first and second columns provide x and y coordinates.strcan be a string scalar, string array, character row, character matrix, or cell array of text scalars.- The axes-target form
textscatter(ax,...)renders into the supplied axes handle. TextDensityPercentagecontrols how many labels are visible;0hides all text labels and100shows all labels and suppresses marker creation.MaxTextLengthtruncates long labels and adds...at the truncation point.MarkerColoracceptsauto,none, or an RGB color.ColorDataaccepts an RGB triplet or N-by-3 RGB matrix for text colors.getsupportsType,Parent,Children,TextData,XData,YData,ZData,TextDensityPercentage,MaxTextLength,MarkerColor,MarkerSize,ColorData,Colors,Visible,DisplayName, andTag; 2-D charts report emptyZData.setsupportsTextData,XData,YData,TextDensityPercentage,MaxTextLength,MarkerColor,MarkerSize,ColorData,Colors,Visible,Color,FontSize,FontWeight,FontAngle, andInterpreter.ZDatamutation is reserved fortextscatter3charts.- Categorical
ColorData, datasource properties, callbacks, app data, and interactive data-tip template objects are not implemented yet and raise explicit unsupported-property errors.
Examples
Create a 2-D text scatter chart
x = [1 2 3];
y = [4 5 6];
words = ["one" "two" "three"];
ts = textscatter(x, y, words);Use an N-by-2 coordinate matrix
xy = [1 4; 2 5; 3 6];
textscatter(xy, ["one" "two" "three"]);Limit label length and color each label
xy = [1 1; 2 2; 3 3];
colors = [1 0 0; 0 1 0; 0 0 1];
ts = textscatter(xy, ["alphabet" "betatron" "gamma"], 'MaxTextLength', 5, 'ColorData', colors);
get(ts, 'TextData')Using textscatter with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how textscatter changes the result.
Run a small textscatter example, explain the result, then change one input and compare the output.
FAQ
Does textscatter return individual text handles?⌄
No. RunMat returns a first-class textscatter chart handle. The chart owns the text annotations and marker plot internally, so chart data and display properties can be queried and updated through get and set.
How are markers handled?⌄
When TextDensityPercentage is below 100 and MarkerColor is not none, RunMat creates an internal scatter marker plot. At 100 percent density, markers are suppressed to match MATLAB behavior.
Can textscatter preserve gpuArray residency?⌄
Not currently. Text annotations require host coordinate and label materialization. Marker rendering reuses the existing scatter plot path once the chart has been constructed.
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 · cla · clf · colorcube · colororder · copyobj · daspect · datacursormode · dataTipTextRow · fcontour · figure · fill3 · findobj · fsurf · gobjects · groot · hgload · hgsave · hidden · histogram2 · hold · line · linkaxes · openfig · opengl · pan · parula · patch · plotmatrix · plotyy · polarhistogram · polarplot · polarscatter · print · quiver3 · ribbon · saveas · savefig · sphere · stackedplot · subtitle · suptitle · textscatter3 · triplot · waitbar · wordcloud · xline · xscale · xtickangle · xtickformat · xticklabels · xticks · yline · yscale · ytickangle · ytickformat · yticklabels · yticks · zoom
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how textscatter is executed, line by line, in Rust.
- View the source for textscatter 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.