plotmatrix — Create a scatter plot matrix from matrix columns.
plotmatrix builds a grid of axes where each off-diagonal subplot compares one variable column against another. The one-input form also places histograms on the diagonal. Matrix rows are observations and columns are variables; vector inputs are treated as one variable.
Syntax
S = plotmatrix(X)
S = plotmatrix(X, LineSpec)
S = plotmatrix(X, Y)
S = plotmatrix(X, Y, LineSpec)
S = plotmatrix(ax, ...)
[S, AX] = plotmatrix(...)
[S, AX, BigAx] = plotmatrix(...)
[S, AX, BigAx, H, HAx] = plotmatrix(X)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
X | NumericArray | Yes | — | Matrix whose columns are variables and rows are observations. |
lineSpec | StyleSpec | No | — | Optional marker/color style applied to scatter plots. |
Y | NumericArray | Yes | — | Matrix whose columns are variables and rows are observations. |
Returns
| Name | Type | Description |
|---|---|---|
S | NumericArray | Matrix of scatter graphics handles for off-diagonal plots. |
AX | NumericArray | Matrix of axes handles used by the plot matrix. |
BigAx | NumericScalar | Compatibility axes handle for labels spanning the plot matrix. |
H | NumericArray | Vector of diagonal histogram handles for the one-input form. |
HAx | NumericArray | Vector of diagonal histogram axes handles for the one-input form. |
Returned values from plotmatrix depend on how many outputs the caller requests.
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:plotmatrix:InvalidArgument | Inputs are nonnumeric, observation counts differ, or style arguments are malformed. | plotmatrix: invalid argument |
RunMat:plotmatrix:Internal | Internal subplot, scatter, or histogram rendering fails. | plotmatrix: internal operation failed |
How plotmatrix works
plotmatrix(X)creates annbyngrid for thenvariables inX, with diagonal histograms and off-diagonal scatter plots.plotmatrix(X,LineSpec)applies the line specification to off-diagonal scatter plots while retaining diagonal histograms.plotmatrix(X,Y)creates annbymrectangular grid forncolumns inXandmcolumns inY; diagonal histogram outputs are empty for this form.plotmatrix(X,Y,lineSpec)applies the line specification to scatter plots in the matrix.plotmatrix(ax,...)uses the supplied axes as the compatibility big-axes target.[S,AX,BigAx,H,HAx] = plotmatrix(X)returns the scatter handle matrix, axes handle matrix, current big-axes handle, diagonal histogram handles, and diagonal histogram axes handles.- Inputs must be numeric and must have the same number of observations when both
XandYare supplied. - Diagonal histograms are created through the same
histogrambuiltin path as direct histogram calls.
Examples
Plot pairwise relationships between columns
X = [1 10; 2 20; 3 30; 4 40];
S = plotmatrix(X);Compare X columns against a separate response column
X = [1 10; 2 20; 3 30];
Y = [4; 5; 6];
[S,AX] = plotmatrix(X, Y, 'r+');Inspect diagonal histogram handles
X = [1 10; 2 20; 3 30];
[S,AX,BigAx,H,HAx] = plotmatrix(X);
numel(H)Expected output:
ans =
2Using plotmatrix with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how plotmatrix changes the result.
Run a small plotmatrix example, explain the result, then change one input and compare the output.
FAQ
Does plotmatrix preserve gpuArray residency?⌄
No. plotmatrix is a CPU-rendered plotting sink, matching MATLAB's documented gpuArray behavior for this function. Individual scatter/histogram rendering then follows the existing plotting paths.
What is BigAx in RunMat?⌄
RunMat returns a valid axes handle and leaves it as gca so scripts can pass it to labeling/property helpers. The current renderer does not model MATLAB's invisible spanning axes as a distinct object.
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 · caxis · cla · clf · clim · colorcube · colororder · copyobj · daspect · datacursormode · dataTipTextRow · fcontour · figure · fill · fill3 · findobj · fsurf · gobjects · groot · hgload · hgsave · hidden · histogram2 · hold · line · linkaxes · openfig · opengl · pan · parula · patch · plotyy · polarhistogram · polarplot · polarscatter · print · quiver3 · ribbon · saveas · savefig · sphere · stackedplot · subtitle · suptitle · text · textscatter · textscatter3 · triplot · waitbar · wordcloud · xlabel · xlim · xline · xscale · xtickangle · xtickformat · xticklabels · xticks · ylabel · ylim · yline · yscale · ytickangle · ytickformat · yticklabels · yticks · zlim · zoom
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how plotmatrix is executed, line by line, in Rust.
- View the source for plotmatrix 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.