Stata 15 help for twoway_mata


[G-2] twoway mata -- Twoway graphs of mata matrices


[graph] twoway plot [plot ...] [if] [in] [, twoway_options]

where the syntax of plot is

[(] plottype mata_matrix_name [column_names]..., options [)] [||]

plottype Description ------------------------------------------------------------------------- scatter scatterplot line line plot connected connected-line plot

area line plot with shading bar bar plot spike spike plot dropline dropline plot dot dot plot

rarea range plot with area shading rbar range plot with bars rspike range plot with spikes rcap range plot with capped spikes rcapsym range plot with spikes capped with symbols rscatter range plot with markers rline range plot with lines rconnected range plot with lines and markers -------------------------------------------------------------------------

plot may also be any syntax for plotting data from the current dataset as documented in graph twoway. Multiple Mata matrix plots and data plots may be overlayed in a single graph twoway command.

The leading graph is optional. If the first (or only) plot is scatter, you may omit twoway as well, and then the syntax is

scatter ... [, scatter_options] [ || plot [plot [...]]]

and the same applies to line. The other plottypes must be preceded by twoway.

Regardless of how the command is specified, twoway_options may be specified among the scatter_options, line_options, etc., and they will be treated just as if they were specified among the twoway_options of the graph twoway command.


twoway is a family of plots, all of which use numeric y and x scales. The data for these plots typically come from the current dataset as documented in graph twoway. Here we document graphing the columns of Mata matrices as though they were dataset variables by using the same twoway command.


Remarks assume familiarity with graph twoway and with the concepts of twoway plots as described there. Here we simply extend the standard twoway syntax to support plotting columns of Mata matrices as though they were variables in the dataset.

The advantage of this extended syntax over putting your Mata matrix into the dataset using putmata or st_store() involves both speed and space. The syntax documented here causes the data from the Mata matrices to be placed directly into the graphics system without first creating variables in your Stata dataset. This advantage will typically only matter when you have datasets with huge numbers of observations.

Aside from using Mata matrices as data, the syntax of twoway remains unchanged. Let's create two mata matrices to demonstrate.

. mata: amat = 1,2 \ 3,4 \ 4,5 \ 5,6 . mata: bmat = .9,1.1,2 \ 2.8,3.4,4 \ 3.7,4.5,5 \ 4.6,6,6

We graph a scatterplot of the first column of amat against its second column by typing

. twoway scatter matamatrix(amat)

The first column of amat will be the y variable and will by default be labeled "amat1". The second column will be the x variable and will by default be labeled "x". We can change both of these names by specifying a list of names after matamatrix():

. twoway scatter matamatrix(amat) yvarname xvarname

When the matrix has more than two columns, say, k columns, the columns 1 through k-1 are treated as y variables to be plotted, and column k is the x variable for each to be plotted against. This is identical to how twoway handles varlist specifications:

. twoway scatter y1 y2 x

Using our bmat, we type

. twoway scatter matamatrix(bmat)

to obtain two scatterplots, one for the first column of bmat and one for the second column.

We can rename those two plots by typing

. twoway scatter matamatrix(bmat) y1 y2

We can also rename the x variable by typing

. twoway scatter matamatrix(bmat) y1 y2 ourx

As with other twoway plots, we can overlay plots of Mata matrices:

. twoway scatter matamatrix(amat) || scatter matamatrix(bmat)

We can treat the first two columns of our bmat as a range plot:

. twoway scatter matamatrix(amat) || rcap matamatrix(bmat)

And we can intermix plots of Mata matrices with plots of Stata variables:

. sysuse auto . twoway scatter matamatrix(amat) || scatter gear_ratio rep78

This is a silly graph, but it shows the syntax.

What twoway does when your matrix has many columns depends on the plot type. scatter, line, and connected create plots for k-1 columns, where k is the number of columns in your matrix. All other plot types enforce that the matrix has the exact number of required columns -- two columns for area, bar, spike, dropline, and dot types; and three columns for rarea, rbar, rspike, rcap, rcapsym, rline, and rconnected plot types. If your Mata matrix has extra columns you do not want to graph, use standard mata column referencing to create a matrix with fewer columns:

mata: b = a[., 1..3]

creates b with the first 3 columns of a;

mata: b = a[., 5..6]

creates b with the 5th and 6th columns of a; and

mata: b = a[., (2,7,3)]

creates b with the 2nd and 7th and 3rd columns of a, with the 2nd column of a becoming the first column of b, the 7th column of a becoming the 2nd column of b, and the 3rd column of a becoming the 3rd column of b.


Create a mata matrix named mymat having three columns

mata: mymat = 1,1.1,2 \ 3,3.4,4 \ 4,4.5,5 \ 5,6,6

Create a scatterplot of the data in mymat, treating the first column as the y values for the first plot, the second column as the y values for the second plot, and the third column as the x values for both plots

twoway scatter matamatrix(mymat)

As above, naming the first two columns (plots) plot1 and plot2

twoway scatter matamatrix(mymat) plot1 plot2

Create a range spike plot of the data in mymat, treating the first column as the lower y values of the spikes, the second column as the upper y values of the spikes, and the third column as the x values for the spikes

twoway rspike matamatrix(mymat)

As above, adding a scatterplot of variables yvar and xvar from the current dataset

twoway rspike matamatrix(mymat) || scatter yvar xvar

© Copyright 1996–2018 StataCorp LLC   |   Terms of use   |   Privacy   |   Contact us   |   What's new   |   Site index