------------------------------------------------------------------------------- help formakematrix-------------------------------------------------------------------------------

Make a matrix of results from other commandsOutline syntax:

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

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

commandmust be specified together with whatever elements from [varlist] [ifexp] [inrange] [weight] [,options] are appropriate.Strictly,

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

Description

makematrixrunscommandrepeatedly 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 usingmatrixlist, unless thelistoption is specified, in which case it will be listed using thelistcommand.There are various modes of operation, which are best appreciated by studying the detailed examples discussed in the next section.

RemarksFirst, 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.

summarizeis 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.correlateis an essentially bivariate command; it does work for three or more variables, by repeating its operation for pairs of those variables.spearmanis 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.regressis an essentially multivariate command. From now on the word "essentially" is not used, but should be understood.The output of

correlategiven avarlistof two or more variables is a matrix of correlations for every pair of variables invarlist. How could we produce an equivalent directly for spearman? We need to find out thatspearmanleaves a correlation behind inr(rho):

. makematrix, from(r(rho)) : spearman head trunk length displacementweightThe result is displayed using

matrix listand we will normally want to tidy up the presentation, say by

. makematrix, from(r(rho)) format(%4.3f) : spearman head trunk lengthdisplacement weightHowever, 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,makematrixtakes each pair of variables fromvarlist, 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 byvarlist.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 thevarlistofcommandwill 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 lengthdisplacement weightHere the full correlation matrix of variables and scores, as would be produced by

correlate, is 10 X 10, and the submatrix produced bymakematrixis 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)) : suhead trunk lengthdisplacement weight, detail

makematrixreasons 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 invarlist,makematrixruns 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

makematrixreasons 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 optionlhs()is also specified, so that must be used to supply the other variable. Wheneverlhs()is specified, it specifies the rows of the matrix. That is, in this case, the rows show the results ofspearman rep78 mpg...spearman foreign mpg. Notice how the variables specified inlhs()appear on theeft-landhide of thesvarlistwhichspearmanruns. (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 mpgIn 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, wheneverrhs()is specified, it specifies the rows of the matrix. Notice how the variables specified inrhs()appear on theight-randhide of thesvarlistwhichspearmanruns. (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 mpgThe first series of regressions predicts

rep78...foreignin turn frommpg. The second series predictsmpgfromrep78...foreignin turn. The r-square results will be the same, but not the root mean square errors, or the intercepts or slopes. Note that_bby itself has the interpretation of_b[row_variable].In fact

lhs()andrhs()can be used to produce a series of multivariate results. Suppose we haveweightsq = weight^2.

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

mpg...foreignin turn fromweightandweightsq. When eitherlhs()orrhs()is specified they define the varying rows, while thevarlistsupplied is fixed for each run ofcommand.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,meanonlyHowever,

makematrixcannot distinguish between this and a similar problem with a bivariate command, so it will attempt to runsummarizeon all distinct pairs of variables. This will succeed, except that what is left behind inr(sum)will be the sum of the second of each pair of variables. What you will prefer is avector, and that is the option to specify:

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

Options

from(results_list)is required. Theresults_listmay in particular contain names of e-class results containing scalars (such ase(rmse)); names of r-class results containing scalars (such asr(rho)); estimates of intercepts, slopes or standard errors such as_b[_cons],_b[mpg]or_se[mpg]; or names of globals (such asS_1). Do not prefix global names with$._bor_seby itself has the interpretation of_b[row_variable]or_se[row_variable]. Expressions such asr(rho)^2orlog10(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_optionsare

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

lhs(lhs_varlist)specifies a list of variables to appear on the left-hand side of the variable list supplied tocommand. These will appear on the rows of the matrix. (The list of results infrom()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 tocommand. These will appear on the rows of the matrix. (The list of results infrom()then defines the columns of the matrix.)

vectorspecifies 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 infrom(); (2) there is nocols(),lhs()orrhs(); (3)commandis a univariate command. Withoutvector,makematrixwould otherwise attempt to treatcommandas a bivariate command and carry out calculations for all pairs of variables.Only one of

cols(),lhs(),rhs()andvectormay be specified.

listwisespecifies that the results ofcmdshould 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_optionscontrol the presentation of the matrix.

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

labelspecifies that an attempt be made to show variable labels wherever variables specify the rows of the matrix. Unless thelistoption is also specified, variable labels longer than 32 characters will not be shown and periods whichmatrix listdoes not construe as time series operators will be suppressed.

format(format)specifies the format to be used for columns withlist. 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 toformat()and specifies the number of decimal places to be shown withlist. Note that, for example,dp(2 3 4)is equivalent toformat(%3.2f %4.3f %5.4f).

rightjustifyspecifies that row names are to be shown right-justified withlist. The default is to present them left-justified.Other options may be specified that are options of

listif thelistoption is specified or ofmatrix listotherwise.

Examples

. sysuse auto, clear

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

. pca head trunk length displacement weight. score score1-score5. makematrix, from(r(rho)) cols(score?) : correlate head trunk lengthdisplacement weight. makematrix R, from(r(rho)) cols(score?) : correlate head trunk lengthdisplacement 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 lengthdisplacement 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) listdp(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) : regressweight weightsq. makematrix, from(e(r2) e(rmse)) lhs(mpg-trunk length-foreign) list dp(32) sep(0) divider : regress weight weightsq

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

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

AcknowledgmentsKen Higbee made valuable comments on this help file. Eric Uslaner 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 seeOn-line: help for list, matrix list; statsby, tabstat