__Title__

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

__Syntax__

[__gr__**aph**] __tw__**oway** *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

__sc__**atter** ... [**,** *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.

__Description__

**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__

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.

__Examples__

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**