Matrix language

Stata is programmable, meaning that you can add new commands to Stata’s repertoire. Stata also includes matrix capabilities, which can be used in Stata programs or interactively.

First, let’s define the word matrix because Stata's definition includes a few details that go beyond the mathematics. To Stata, a matrix is a named entity containing an r x c rectangular array of double-precision numbers, which is bordered by a row and column of names:

    . matrix list A

    A[3,2]
             price    mpg
      Honda   4499     28
      Buick   7827     15
    Renault   3895     26

In this case, we have a 3 x 2 matrix named A containing elements 4499, 28, 7827, 15, 3895, and 26. Row 1, column 2 (written A[1,2] in Stata) contains 28. The two columns are named price and mpg, and the three rows are named Honda, Buick, and Renault.

The names are operated on along with the numbers. For instance

    . matrix B = A'*A
	
    . matrix list B
    
    symmetric B[2,2]
              price       mpg
    price  96673955
      mpg    344647      1685

We defined B = A'A. Note that the row and column names of B are the same. Multiplication is defined for any a x b and b x c matrices, the result being a x c. Thus, the row and column names of the result are the row names of the first matrix and the column names of the second. We formed A'A, using the transposition of A for the first matrix—which also interchanged the names—and so obtained the names shown. The names are correct in the sense that the (1,1) element is the sum of squares of price, and for instance, the (1,2) element is the sum of the interaction of price and mpg across the observations.

Researchers have long realized that matrix notation simplifies the description of complex calculations. What they may not have realized is that corresponding to each mathematical definition of a matrix operator is a definition of the operator's effect on the names that can be used to carry the names forward through long and complex matrix calculations.

What is done with the names? Because in statistical contexts matrices are often used to obtain estimates, Stata’s output routines exploit the information to label the output. Moreover, in a long matrix calculation, if the names do not come out right, you can be certain that you made a mistake.

Operators and functions

The standard list of matrix operators is provided, including

• addition
• subtraction
• multiplication
• Kronecker product
• transposition
• ability to join matrices by row or column

Matrix functions include

• inversion (both symmetric and nonsymmetric)
• Cholesky decomposition
• sweep
• diagonalization and extraction
• singular-value decomposition
• symmetric-matrix eigenvalue and eigenvector extraction

A function for converting a covariance matrix into a correlation matrix is also provided. Functions for easily creating of identity and zero matrices are also provided.

Matrix functions returning scalars include

• trace
• determinant
• functions returning the number of rows and columns of a matrix

Subscripting and element-by-element definition is allowed. Subscripting allows you to easily extract submatrices.

Stata also provides a command that, given the coefficient vector and corresponding covariance matrix from estimation, produces output that looks exactly like standard estimation output. Standard errors are obtained from the covariance matrix, and significance tests and confidence intervals are automatically constructed. User-programmed estimation results can be posted to Stata’s internal areas so that they are indistinguishable from internally generated results. You can redisplay estimation results, obtain predicted values, and perform tests based on the estimated variance–covariance matrix of the estimators without any programming or even knowledge of the underlying matrix formulas.

Example

Almost every matrix-programming language has made the following claim: “You can obtain regression estimates as easily as typing (X'X)^(-1)X'y !”

This claim leaves a lot unsaid. First, how, exactly, do you create X? You don't want to know. Second, the resulting output almost always looks something like

    (1.7465592,-49.512221,1946.0687)

Where are the standard errors? The t statistics? The confidence intervals? You can calculate them. And you can see them in the same inelegant format.

However, this is a good test of the language. Exactly how difficult is it to perform regression in the language? Stata has a linear regression command, of course, but for the test, let us pretend that it did not. First, the formulas:

	           -1
	 b  =  (X'X)  X'y

	        2     -1
    var(b)  =  s (X'X)

         2
        s   =  (y'y - b'X'y)/(n-k)

	 n  =  number of observations
	 k  =  number of independent variables

The corresponding Stata code, with output, is

    . matrix accum YXX = price weight mpg          /* define (y X)'(y X)     */
    . local  n  = r(N)                             /* define number of obs   */
    . matrix XX = YXX[2...,2...]                   /* extract X'X            */
    . matrix Xy = YXX[2...,1]                      /* extract X'y            */
    . matrix b  = (syminv(XX)*Xy)'                 /* b as row vector        */
    . matrix bXy = b*Xy                            /* define b'X'y           */
    . scalar s2 = (YXX[1,1] - bXy[1,1])/(`n'-rowsof(XX)) /* s2 (a scalar)    */
    . matrix V  = s2 * syminv(XX)                  /* variance matrix        */
    . local df  = `n' - rowsof(XX)                 /* obtain d.f. for t      */
    . ereturn post b V
    . ereturn display
    
    ------------------------------------------------------------------------------
                 |      Coef.   Std. Err.      t    P>|t|     [95% Conf. Interval]
    -------------+----------------------------------------------------------------
	  weight |   1.746559   .6413538     2.72   0.006     .4895288    3.003589
	     mpg |  -49.51222   86.15604    -0.57   0.566     -218.375    119.3505 
	   _cons |   1946.069    3597.05     0.54   0.588    -5104.019    8996.156
    ------------------------------------------------------------------------------

The model to be fitted is defined in the first line, and after that, we just worked through the formulas (all of them). The solution above is completely general—it will even handle missing values in the data. The result is properly labeled output, produced automatically, because Stata carried the names from the first line though the calculation automatically.

See New in Stata 11 for more about what was added in Stata Release 11.