```-------------------------------------------------------------------------------
help for makematrix
-------------------------------------------------------------------------------

Make a matrix of results from other commands

Outline syntax:

makematrix [matrix_name] ,
from(results_list) [production_options] [list_options] :
["]command["] [varlist] ... [, options ]

A matrix name matrix_name may be specified. If so, a matrix with that
name will be produced and remain in memory.

command must be specified together with whatever elements from [varlist]
[if exp] [in range] [weight] [, options ] are appropriate.

Strictly, command is the first token following the colon :.  Hence bind
commands specified by two or more words in double quotes.  Thus if
command were run mydo.do, specify it as "run mydo.do".

Description

makematrix runs command repeatedly for a specified variable list
(optionally, two variable lists) to produce a matrix of results. As
usual, a matrix could be a vector. The matrix will be listed using matrix
list, unless the list option is specified, in which case it will be
listed using the list command.

There are various modes of operation, which are best appreciated by
studying the detailed examples discussed in the next section.

Remarks

First, some terminology. We call a Stata (statistical) command
essentially univariate if it requires only one variable; it may repeat
itself if supplied with two or more variables.  summarize is an
essentially univariate command; it does work for two or more variables,
by repeating its operation for those variables. We call such a command
essentially bivariate if it requires only two variables, and may repeat
itself otherwise.  correlate is an essentially bivariate command; it does
work for three or more variables, by repeating its operation for pairs of
those variables.  spearman is also an essentially bivariate command,
although it does not in fact accept more than two variables. Finally, we
call such a command essentially multivariate if it produces just one set
of results even if supplied with three or more variables.  regress is an
essentially multivariate command. From now on the word "essentially" is
not used, but should be understood.

The output of correlate given a varlist of two or more variables is a
matrix of correlations for every pair of variables in varlist. How could
we produce an equivalent directly for spearman? We need to find out that
spearman leaves a correlation behind in r(rho):

. makematrix, from(r(rho)) : spearman head trunk length displacement
weight

The result is displayed using matrix list and we will normally want to
tidy up the presentation, say by

. makematrix, from(r(rho)) format(%4.3f) : spearman head trunk length
displacement weight

However, let us leave these details of presentation on one side. In this
case, given a bivariate command, and a varlist, and a single result from
which to compile the matrix, makematrix takes each pair of variables from
varlist, runs a bivariate command for that pair, and puts a single result
in the cell defined by each pair of variables. So both rows and columns
are specified by varlist.

Alternatively, we might want different sets of variables on the rows and
the columns, perhaps specifying a submatrix of the full matrix.  The
option cols() can be used to specify variables to appear as columns. The
variables in the varlist of command will then appear as rows.  Say we did
a principal component analysis of five variables and followed with
calculation of scores:

. pca head trunk length displacement weight
. score score1-score5
. makematrix, from(r(rho)) cols(score?) : correlate head trunk length
displacement weight

Here the full correlation matrix of variables and scores, as would be
produced by correlate, is 10 X 10, and the submatrix produced by
makematrix is only 5 X 5.

We can show two or more scalar results from each command run.  This is
possible in various ways. A univariate command can be repeated, each time
yielding two or more scalars:

. makematrix, from(r(mean) r(sd) r(skewness)) : su head trunk length
displacement weight, detail

makematrix reasons in this way: The user wants three scalars, which I
will show in three columns. So I must run the command specified in turn
on each variable supplied, which I will show on the rows. So for each
variable in varlist, makematrix runs a univariate command, and puts two
or more scalars in the cells of each row.

A bivariate command can be repeated, each time yielding two or more
scalars:

. makematrix, from(r(rho) r(p)) lhs(rep78-foreign) : spearman mpg

makematrix reasons in this way: The user wants two scalars, which I will
show in two columns. So I must run the command specified in turn on the
variable supplied. The option lhs() is also specified, so that must be
used to supply the other variable. Whenever lhs() is specified, it
specifies the rows of the matrix.  That is, in this case, the rows show
the results of spearman rep78 mpg ...  spearman foreign mpg. Notice how
the variables specified in lhs() appear on the left-hand side of the
varlist which spearman runs.  (lhs() also names the left-hand side of the
matrix, but that is a happy accident.) This is also allowed:

. makematrix, from(r(rho) r(p)) rhs(rep78-foreign) : spearman mpg

In this case, the rows show the results of spearman mpg rep78 ...
spearman mpg foreign, and are exactly the same as in the previous
example. Again, whenever rhs() is specified, it specifies the rows of the
matrix.  Notice how the variables specified in rhs() appear on the
right-hand side of the varlist which spearman runs.  (By a small stretch,
you can also think of it as naming the right-hand side of the matrix,
given that we could repeat the row names on that side.) In other cases,
which is used may well matter:

. makematrix, from(e(r2) e(rmse) _b[_cons] _b[mpg]) lhs(rep78-foreign) :
regress mpg

. makematrix, from(e(r2) e(rmse) _b[_cons] _b) rhs(rep78-foreign) :
regress mpg

The first series of regressions predicts rep78 ... foreign in turn from
mpg. The second series predicts mpg from rep78 ...  foreign in turn. The
r-square results will be the same, but not the root mean square errors,
or the intercepts or slopes.  Note that _b by itself has the
interpretation of _b[row_variable].

In fact lhs() and rhs() can be used to produce a series of multivariate
results. Suppose we have weightsq = weight^2.

. makematrix, from(e(r2) e(rmse)) lhs(mpg-trunk length-foreign) :
regress weight weightsq

This series predicts mpg ... foreign in turn from weight and weightsq.
When either lhs() or rhs() is specified they define the varying rows,
while the varlist supplied is fixed for each run of command.

There is one more nuance to be explained. Say you want a table of sums
for a set of variables. You might try

. makematrix, from(r(sum)): su head trunk length displacement weight,
meanonly

However, makematrix cannot distinguish between this and a similar problem
with a bivariate command, so it will attempt to run summarize on all
distinct pairs of variables. This will succeed, except that what is left
behind in r(sum) will be the sum of the second of each pair of variables.
What you will prefer is a vector, and that is the option to specify:

. makematrix, from(r(sum)) vector: su head trunk length displacement
weight, meanonly

Options

from(results_list) is required. The results_list may in particular
contain names of e-class results containing scalars (such as e(rmse));
names of r-class results containing scalars (such as r(rho)); estimates
of intercepts, slopes or standard errors such as _b[_cons], _b[mpg] or
_se[mpg]; or names of globals (such as S_1).  Do not prefix global names
with \$. _b or _se by itself has the interpretation of _b[row_variable] or
_se[row_variable].  Expressions such as r(rho)^2 or log10(r(p)) are also
allowed.  However, note that no spaces must occur within any individual
expression and that the more complicated the expression you use, the more
likely it is that it will not be acceptable as a matrix column name.

production_options are

cols(column_varlist) specifies a list of variables to appear on the
columns of the matrix. (varlist then defines the rows only.}

lhs(lhs_varlist) specifies a list of variables to appear on the
left-hand side of the variable list supplied to command. These will
appear on the rows of the matrix. (The list of results in from() then
defines the columns of the matrix.)

rhs(rhs_varlist) specifies a list of variables to appear on the
right-hand side of the variable list supplied to command. These will
appear on the rows of the matrix. (The list of results in from() then
defines the columns of the matrix.)

vector specifies that the results are to be compiled as a single
vector. This option is necessary when, and only when, (1) there is a
single result in from(); (2) there is no cols(), lhs() or rhs(); (3)
command is a univariate command.  Without vector, makematrix would
otherwise attempt to treat command as a bivariate command and carry
out calculations for all pairs of variables.

Only one of cols(), lhs(), rhs() and vector may be specified.

listwise specifies that the results of cmd should be determined for
as many observations as possible.  Note that as a consequence the
number of observations used in each calculation may differ. By
default casewise deletion is used to ensure consistency in
observations selected.

list_options control the presentation of the matrix.

list specifies that the list command be used to present the matrix.

label specifies that an attempt be made to show variable labels
wherever variables specify the rows of the matrix. Unless the list
option is also specified, variable labels longer than 32 characters
will not be shown and periods which matrix list does not construe as
time series operators will be suppressed.

format(format) specifies the format to be used for columns with list.
As an extension of standard format options, multiple formats may be
specified, one for each column.  For example, format(%3.2f %4.3f
%5.4f) specifies that the columns of the matrix have the specified
formats.

dp(# [ # [ ... ] ]) is an alternative to format() and specifies the
number of decimal places to be shown with list. Note that, for
example, dp(2 3 4) is equivalent to format(%3.2f %4.3f %5.4f).

rightjustify specifies that row names are to be shown right-justified
with list. The default is to present them left-justified.

Other options may be specified that are options of list if the list
option is specified or of matrix list otherwise.

Examples

. sysuse auto, clear

. makematrix, from(r(rho)) : spearman head trunk length displacement
weight
. makematrix, from(r(rho)) format(%4.3f) : spearman head trunk length
displacement weight

. pca head trunk length displacement weight
. score score1-score5
. makematrix, from(r(rho)) cols(score?) : correlate head trunk length
displacement weight
. makematrix R, from(r(rho)) cols(score?) : correlate head trunk length
displacement weight
. matrix colnames R = "score 1" "score 2" "score 3" "score 4" "score 5"
. matrix li R, format(%4.3f)

. makematrix , from(r(rho) r(p)) label cols(price) : spearman mpg-foreign
. makematrix , from(r(rho) r(p)) list label format(%4.3f %6.5f) sep(0)
cols(price) : spearman mpg-foreign

. makematrix, from(r(mean) r(sd) r(skewness)) : su head trunk length
displacement weight, detail
. makematrix, from(r(mean) r(sd) r(skewness)) list format(%2.1f %2.1f
%4.3f) sep(0) : su head trunk length displacement weight, detail

. makematrix, from(r(rho) r(p)) lhs(rep78-foreign) : spearman mpg
. makematrix, from(r(rho) r(p)) rhs(rep78-foreign) : spearman mpg
. makematrix, from(e(r2) e(rmse) _b[_cons] _b[mpg]) lhs(rep78-foreign) :
regress mpg
. makematrix, from(e(r2) e(rmse) _b[_cons] _b[mpg]) lhs(rep78-foreign)
list dp(3 2 2 3) abb(9) sep(0) divider : regress mpg
. makematrix, from(e(r2) e(rmse) _b[_cons] _b) rhs(rep78-foreign) :
regress mpg
. makematrix, from(e(r2) e(rmse) _b[_cons] _b) rhs(rep78-foreign) list
dp(3 2 2 3) abb(9) sep(0) divider : regress mpg

. gen weightsq = weight^2
. makematrix, from(e(r2) e(rmse)) lhs(mpg-trunk length-foreign) : regress
weight weightsq
. makematrix, from(e(r2) e(rmse)) lhs(mpg-trunk length-foreign) list dp(3
2) sep(0) divider : regress weight weightsq

. makematrix, from(r(sum)) vector: su head trunk length displacement
weight, meanonly

Author

Nicholas J. Cox, Durham University, U.K.
n.j.cox@durham.ac.uk

Acknowledgments

pointed towards a bug. Hervé Stolowy pointed towards another bug, and
Alan Riley explained it. Lisa Gilmore alerted me to a problem with
handling double quotes.

Also see

On-line:  help for list, matrix list; statsby, tabstat

```