Universitat Pompeu Fabra Dr.

Kurt Schmidheiny Coding with Mata in Stata 2

Topics in Applied Economics I October 1, 2008

7 Coding Stata commands using Mata 31

7.1 An example . . . . . . . . . . . . . . . . . . . . . . . . . 31
Coding with Mata in Stata 8 Important Functions and Operators 33
First draft, errors likely, feedback welcome.

1 Introduction 3

2 Where to get help 3

3 Using Mata in Stata 4

3.1 Command line use . . . . . . . . . . . . . . . . . . . . . 4
3.2 Use in .do files . . . . . . . . . . . . . . . . . . . . . . . . 4
3.3 Use in .ado files . . . . . . . . . . . . . . . . . . . . . . . 4

4 Matrix Algebra with Mata 5

4.1 Creating matrices, vectors and scalars . . . . . . . . . . . 5
4.2 Accessing data from Stata . . . . . . . . . . . . . . . . . 8
4.3 Managing the Mata workspace . . . . . . . . . . . . . . . 10
4.4 Basic matrix manipulations . . . . . . . . . . . . . . . . 11
4.5 Basic matrix operators . . . . . . . . . . . . . . . . . . . 17
4.6 Matrix multiplication . . . . . . . . . . . . . . . . . . . . 18
4.7 Building special matrices . . . . . . . . . . . . . . . . . . 22
4.8 Inverse and linear equations system . . . . . . . . . . . . 24

5 Controlling the flow 25

5.1 Loops . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
5.2 Conditional statements . . . . . . . . . . . . . . . . . . . 26

6 Coding Mata functions 27

6.1 Defining functions . . . . . . . . . . . . . . . . . . . . . . 27
6.2 Declarations . . . . . . . . . . . . . . . . . . . . . . . . . 28
6.3 Passing arguments . . . . . . . . . . . . . . . . . . . . . 28
6.4 Returning values . . . . . . . . . . . . . . . . . . . . . . 29
6.5 .mo and .mlib files . . . . . . . . . . . . . . . . . . . . . 30
3 Topics in Applied Economics I Coding with Mata in Stata 4

1 Introduction 3 Using Mata in Stata

Mata is a matrix algebra language which is available in Stata since version 3.1 Command line use
9.
Mata is directly accessed from the Stata command window. Type the
Stata and mata commands are set in Courier. Options in [brackets]
stata command
are optional.
mata

and all subsequent commands will be interpreted as Mata commands.

2 Where to get help Type
end
The two Stata manuals Mata Matrix Programming provide systematic
information about MATA commands. It also discusses the implemented to return to the normal Stata command prompt.
numerical methods. Note: All matrix and function definitions are kept in the Mata workspace
The online help in Stata describes the use of all Mata commands with when you end mata and accessible when you re-enter mata.
its options. However, it does not explain the numerical properties as in
the Reference manual. We can start the online query in the Command 3.2 Use in .do files
window by
help mata command Mata commands can also be used in do files. A sequence of Mata
commands is preceded by the Stata command mata and terminated by
For example, help for the cholesky decomposition is asked for by
end. There can be several such sequences which access the same Mata
help mata cholesky() workspace.
If you don’t know the exact expression for the command, you can search
for Mata commands in the Stata documentation by issuing the command 3.3 Use in .ado files
search mata word
See section 7 for use of Mata to produce new Stata commands.
Search commands are answered in the result window. Alternatively, you
can display the result in the Viewer window by issuing the command
view search mata word

You can also use the Stata online help in the menu bar: Help/Search....
5 Topics in Applied Economics I Coding with Mata in Stata 6

4 Matrix Algebra with Mata 4.1.2 Building a matrix out of submatrices

4.1 Creating matrices, vectors and scalars You can build matrices out of several submatrices. Suppose you have
submatrices A to D.
4.1.1 Building a matrix A=(1, 2 \ 3, 4)
B=(5, 6, 7 \ 8, 9, 10)
In order to build a matrix you have two options. You can declare the C=(3, 4 \ 5, 6)
D=(1, 2, 3 \ 4, 5, 6)
whole matrix separating columns by a comma and rows by a backslash.
For example a 2x2 matrix A B
The matrix E = is built using the column join operation “,”
A=(1, 2 \ 3, 4) C D
and the row-join operator “\”:
Or you can first declare an empty matrix with e.g. 2 rows and 3 columns
E = (A, B \ C, D)
B = J(2, 3, .)
or
and then fill element by element
E = A, B \ C, D
B[1,1] = 5
B[1,2] = 6 which results in
B[1,3] = 7
1 2 3 4 5
B[2,1] = 8
+--------------------------+
B[2,2] = 9
1 | 1 2 5 6 7 |
B[2,3] = 10
2 | 3 4 8 9 10 |
You can give a matrix whatever name you want except for reserved words 3 | 3 4 1 2 3 |
4 | 5 6 4 5 6 |
(see help m2 reswords). Names consist of any combination of letters, +--------------------------+
numbers and underscores “ ” but cannot start with a number. Mata is
sensitive with respect to the upper and lower case.
4.1.3 Creating a string matrix
If a variable has previously been assigned a value, the new value overrides
value and dimensions of the predecessor. Mata can also deal with string matrices which are matrices with string
You can display the value of variable B by simply typing its name elements. To create a string matrix, we enclose its elements in quotation
marks.
B
1 2 3 S=("Thijs", "Kurt" \ "Ghazala", "Gabrielle")
+----------------+
1 | 5 6 7 | which results in
2 | 8 9 10 |
+----------------+
7 Topics in Applied Economics I Coding with Mata in Stata 8

S 4.1.5 Creating a scalar

1 2
+-------------------------+ A scalar is given by a 1 × 1 matrix. For example
1 | Thijs Kurt |
2 | Ghazala Gabrielle | a = 2
+-------------------------+
Note: standard Stata matrix commands distinguish between scalars and
1 × 1 matrices.
4.1.4 Creating a vector

A vector is simply a 1 × n or m × 1 matrix. A column vector is created 4.2 Accessing data from Stata
as
Consider the example dataset auto.dta which you can download from the
f = (1, 2, 3)
Stata (not Mata) command prompt.
A column vector is created either by webuse auto.dta
f = (1 \ 2 \ 3)

or by adding a apostrophe (transposition of a matrix) to the row vector 4.2.1 Creating a copy of data
f = (1, 2, 3)’
st data(colvector, rowvector ) copies observations of numeric vari-
You can declare a column vector with a series of number, e.g. from 3 to ables from the Stata dataset into a Mata matrix. For example,
5 as
X = st_data(.,("mpg", "rep78", "weight"))
g = (3::5)
g creates a new matrix X with all observations in rows and the variables
1 mpg, rep78, and weight in columns. A subsample of observations, e.g.
+-----+ observations 1 to 5 and 7 to 9, is created by
1 | 3 |
2 | 4 | X = st_data((1::5\7::9),("mpg", "rep78", "weight"))
3 | 5 | X
+-----+ 1 2 3
+----------------------+
and the corresponding row vector as 1 | 22 3 2930 |
g = (3..5) 2 | 17 3 3350 |
g 3 | 22 . 2640 |
1 2 3 4 | 20 3 3250 |
+-------------+ 5 | 15 4 4080 |
1 | 3 4 5 | 6 | 26 . 2230 |
+-------------+ 7 | 20 3 3280 |
8 | 16 3 3880 |
9 Topics in Applied Economics I Coding with Mata in Stata 10

Alternatively, variables can be accessed by the number of the respective creates Y as rows 1 - 5 and 7 - 9 of columns 3,4, and 7 of matrix X.
column st subview(Y, X, matrix, matrix ) allows to choose sequences of ob-
X = st_data((1::5\7::9),(3, 4, 7)) servations and variables by providing a r x 2 matrix as 3rd argument and
st data(matrix, rowvector ) allows to choose sequences of observa- a 2 x c matrix as 4th argument. For example
tions by providing a r x 2 matrix as first argument. For example st_subview(Y, X, (1, 5\7, 9), (3,7\4,7))
X = st_data((1,5\7,9),("mpg", "weight", "rep78")) creates Y as rows 1 - 5 and 7 - 9 of columns 3 - 4, and 7 - 7 of matrix V.
picks observations 1 to 5 and 7 to 9. See help m5 st_subview() for the various rules to pick the submatrices.

Rows with missing values are omitted if a third argument, set to zero, is A memory efficient way to access data for use in e.g. linear regressions is
provided M = X = y = .
st_view(M, ., ("price", "mpg", "weight", "rep78"), 0)
X = st_data((1::5\7::9),("mpg", "weight", "rep78"), 0) st_subview(y, M, ., 1)
st_subview(X, M, ., (2\.))
Observations can also be selected based on a Stata dummy variable, e.g.
touse
X = st_data(.,("mpg", "weight", "rep78"), "touse") 4.2.3 Copy vs. view

Both st_data and st_view fill in matrix X with the same data. st_data()
4.2.2 Creating a view on the data is generally faster than st_view but uses less memory. st_view also al-
lows (or risks) changing the value of the underlying data. For example,
st view(X, colvector, rowvector ) creates a matrix X that is a view
X[2,1] = 123
onto the current Stata dataset. For example
X = . after st_data(), changes the value in the matrix X, but the Stata dataset
st_view(X, ., ("mpg", "weight", "rep78")) remains unchanged; after st_view(), it would cause the value of mpg in
the second observation to change to 123.
creates a new matrix X which is a view on all observations of the vari-
ables mpg, weight, and rep78. Again the 3rd argument indicates whether Note: There are two functions st_sdata() and st_sview() for use with
missing values or particular observations are to be used: string variables.
st_view(X, ., ("mpg", "weight", "rep78"), 0)
st_view(X, ., ("mpg", "weight", "rep78"), "touse") 4.3 Managing the Mata workspace
st subview(Y, X, colvector, rowvector ) creates a new view matrix
Y from an existing view matrix X. For example To see all existing variables in the Mata workspace, issue the command

st_view(X, ., .) mata describe

st_subview(Y, X, (1::5\7::9), (3,4,7))
11 Topics in Applied Economics I Coding with Mata in Stata 12

The command E
1 2 3 4 5
mata clear +--------------------------+
1 | 1 2 5 6 7 |
deletes all variables from the Mata workspace without disturbing Stata.
2 | 3 4 8 9 10 |
Specific matrices can be deleted by 3 | 3 4 1 2 3 |
4 | 5 6 4 5 6 |
+--------------------------+
mata drop namelist
Scalars from individual elements are extracted by using subscripts in
For example, matrix A and vector f are deleted with square brackets e.g.
mata drop A f E[2, 3]
8

4.4 Basic matrix manipulations A row vector from a row of a matrix is extracted by e.g.
E[2,.]
4.4.1 Transposition of a Matrix 1 2 3 4 5
+--------------------------+
The transpose of a matrix is created with an apostrophe 1 | 3 4 8 9 10 |
+--------------------------+
B
1 2 3 and a column vector from a column of a matrix by e.g.
+----------------+
1 | 5 6 7 | E[.,3]
2 | 8 9 10 | 1
+----------------+ +-----+
1 | 5 |
B’ 2 | 8 |
1 2 3 | 1 |
+-----------+ 4 | 4 |
1 | 5 8 | +-----+
2 | 6 9 |
A contiguous submatrix e.g. consisting of rows 2 to 4 and columns 2
3 | 7 10 |
+-----------+ to 5 is extracted by range subscripts which mark the top-left and the
bottom-right element of the submatrix

4.4.2 Using partions of matrices E[|2, 2\ 3, 4|]

1 2 3
+-------------+
One of the most basic operation is to extract partitions of a matrix. 1 | 4 8 9 |
Consider matrix E 2 | 4 1 2 |
+-------------+
13 Topics in Applied Economics I Coding with Mata in Stata 14

or alternatively be specifying a contiguous range of rows and columns 4.4.3 Making vectors from matrices and reverse
E[(2::3), (2..4)]
1 2 3 The Mata function vec() transforms a matrix into a column vector with
+-------------+ one column stacked onto the next
1 | 4 8 9 |
2 | 4 1 2 | B
+-------------+ 1 2 3
+----------------+
Note: the first alternative is performed faster than the latter. 1 | 5 6 7 |
2 | 8 9 10 |
A submatrix consisting of individual rows and columns e.g. rows 1 and +----------------+
4 and columns 3, 5 and 2 can be formed as
b = vec(B)
E[(1\ 4), (3, 5, 2)] b
1 2 3 1
+-------------+ +------+
1 | 5 7 2 | 1 | 5 |
2 | 4 6 6 | 2 | 8 |
+-------------+ 3 | 6 |
4 | 9 |
More generally, the two arguments can be predefined vectors. For exam- 5 | 7 |
ple, 6 | 10 |
+------+
r = (1\ 4)
c = (3, 5, 2) The Mata functions rowshape or colshape reverse this vectorization
E[r,c]
1 2 3 rowshape(b, 3)’
+-------------+ 1 2 3
1 | 5 7 2 | +----------------+
2 | 4 6 6 | 1 | 5 6 7 |
+-------------+ 2 | 8 9 10 |
+----------------+
Note: Stata considers it good style to specify the first subscript vector
as column vector and the second subscript vector as row vector. Though colshape(b, 2)’
1 2 3
this is not necessary. +----------------+
More partitioning rules can be found under help m2 subscripts. 1 | 5 6 7 |
2 | 8 9 10 |
+----------------+
15 Topics in Applied Economics I Coding with Mata in Stata 16

4.4.4 Extracting the diagonal and creating diagonal matrices lowertriangle(A)

1 2 3
diagonal(A) extracts the diagonal of A and returns it in a column vector: +-------------+
1 | 1 0 0 |
A = (1,2,3\4,5,6\7,8,9) 2 | 4 5 0 |
A 3 | 7 8 9 |
1 2 3 +-------------+
+-------------+
1 | 1 2 3 | uppertriangle(A)
2 | 4 5 6 | 1 2 3
3 | 7 8 9 | +-------------+
+-------------+ 1 | 1 2 3 |
2 | 0 5 6 |
b = diagonal(A) 3 | 0 0 9 |
b +-------------+
1
+-----+
1 | 1 | 4.4.6 Sorting a matrix
2 | 5 |
3 | 9 | sort(X, idx) returns X with rows in ascending or descending order of
+-----+
the columns specified by idx. For instance, sort(X, 1) sorts X on its
diag(b), creates a square matrix with the elements of vector b on its first column:
diagonal.
X = (2, 3, 1\ 2, 2, 2\ 1, 1, 3)
diag(b) X
[symmetric] 1 2 3
1 2 3 +-------------+
+-------------+ 1 | 2 3 1 |
1 | 1 | 2 | 2 2 2 |
2 | 0 5 | 3 | 1 1 3 |
3 | 0 0 9 | +-------------+
+-------------+
sort(X,1)
1 2 3
4.4.5 Extracting the triangular matrix +-------------+
1 | 1 1 3 |
2 | 2 3 1 |
lowertriangle(A) returns the lower triangle of A. uppertriangleA) 3 | 2 2 2 |
returns the upper triangle of A: +-------------+

sort(X, (1,2)) sorts X on its first and second columns (meaning rows
with equal values in their first column are ordered on their second col-
17 Topics in Applied Economics I Coding with Mata in Stata 18

umn): F=b*a
F
sort(X,(1,2)) 1 2 3 4 5
1 2 3 +--------------------------+
+-------------+ 1 | 6 12 18 24 30 |
1 | 1 1 3 | 2 | 7 14 21 28 35 |
2 | 2 2 2 | 3 | 8 16 24 32 40 |
3 | 2 3 1 | 4 | 9 18 27 36 45 |
+-------------+ 5 | 10 20 30 40 50 |
+--------------------------+
See help mata sort() for functions to randomly permutate matrices.
If the matrices involved in the operation are of incompatible sizes, Mata
will return an error message:
4.5 Basic matrix operators
F*d
Mata provides the following basic operators matrix operations: *: 3200 conformability error
<istmt>: - function returned error
+ Addition (of matrix or scalar) r(3200);
- Subtraction (of matrix or scalar)
* Multiplication (with matrix or scalar)
4.6 Matrix multiplication
/ Divison (by scalar)
^ Power (of scalar) The mata function
cross(X, Z)
E.g., consider the vectors a and b and the scalar c:
a = (1..5) is an alternative way to calculate X  Z. cross() has the following advan-
b = (6::10) tages over the standard matrix-notation approach:
c = 3

The vector d and the matrix F are given by: • cross() omits the rows in X and Z that contain missing values,
which amounts to dropping observations with missing values.
d=a+c*a
d • cross() uses less memory, especially when used with views.
1 2 3 4 5
+--------------------------+
• cross() makes calculations in special cases more efficiently. For in-
1 | 4 8 12 16 20 | stance, if you code cross(X, X), calculation is made for a symmetric
+--------------------------+ matrix result.

In the four-argument version, cross(X, xc, Z, zc), X is augmented on

the right with a column of ones if xc is different from 0 and Z is similarly
augmented if zc is different from 0. For example,
19 Topics in Applied Economics I Coding with Mata in Stata 20

cross(X, 1, Z, 0) scalar. == returns false if the variables have different dimensions. For
adds a constant vector to X and nothing to Z. example,
G = (1, 2 \ 3, 4)
cross(X, w, Z) returns X  diag(w)Z. cross(X, xc, w, Z, zc) is aug- H = (1, 5 \ 6, 4)
mented as in the four-argument case. cross(X, 0, 1, Z, 0) is equiv- G == T
alent to cross(X,Z). 0
G[1,2] == 2
1
4.6.1 Element-by-element operators G == 1
0
G != 1
To indicate an element-by-element operation, precede a standard opera- 1
tor with a colon “:”. Mata colon operators are:
Mata relational operators
:* Multiplication (with matrix of same dimensions)
<, > Less, greater than
:/ Division (by matrix of same dimensions)
<=, >= Less, greater than or equal to
:^ Power (of matrix of same dimensions)

can only be used with variables of identical dimensions and returns always
For example,
a scalar. It evaluates the relation for all elements and returns true if it
x = (1, 2, 3) holds for all elements. For example
y = (4, 5, 6)
x:*y G < H
1 2 3 0
+----------------+ G <= H
1 | 4 10 18 | 1
+----------------+
Mata colon relational operators
Note: Element-by-element addition and subtraction is equal to the ma-
:== Equal to
trix operation.
:!= Not equal to
:<, :> Less, greater than
4.6.2 Relational and logical operators :<=, :>= Less, greater than or equal to

Mata equivalence operators can be used with scalars, vectors and matrices and returns the dimension
== Equal to of the highest dimension variable. For example,
!= Not equal to

can be used with scalars, vectors and matrices and returns always a
21 Topics in Applied Economics I Coding with Mata in Stata 22

G :== H H :>= 0 :& H :<= 4

[symmetric] [symmetric]
1 2 1 2
+---------+ +---------+
1 | 1 | 1 | 1 |
2 | 0 1 | 2 | 0 1 |
+---------+ +---------+
G :<= 2
1 2
+---------+ 4.7 Building special matrices
1 | 1 1 |
2 | 0 0 |
+---------+
4.7.1 Creating a matrix of constants
G :== (1\4)
[symmetric] The mata function J() returns a matrix of constant. For example,
1 2
+---------+ J(2, 3, 0)
1 | 1 | 1 2 3
2 | 0 1 | +-------------+
+---------+ 1 | 0 0 0 |
2 | 0 0 0 |
Logical “and” and “or” +-------------+

&, && logical and J(2, 3, 1)

|,|| logical or 1 2 3
+-------------+
1 | 1 1 1 |
can only be used with scalars. For example, 2 | 1 1 1 |
a = 5 +-------------+
a > 0 & a <= 10
1
G <= H & a > 0 4.7.2 Creating a identity matrix
1
The mata function I() returns a matrix of constant. For example,
Colon logical “and” and “or”
I(3)
:& logical and [symmetric]
:| logical or 1 2 3
+-------------+
1 | 1 |
can be used with scalars, vectors and matrices. For example,
2 | 0 1 |
3 | 0 0 1 |
+-------------+
23 Topics in Applied Economics I Coding with Mata in Stata 24

4.7.3 Creating a unit vector 4.8 Inverse and linear equations system

The function e(i, n) returns a vector with all n elements equal to zero Mata offers several functions to calculate the inverse of a matrix:
except for the ith, which is set to one. luinv(A) inverse of full rank, square matrix A
e(2, 5) cholinv(A) inverse of positive definite, symmetric matrix A
1 2 3 4 5 invsym(A) generalized inverse of positive-definite, symmetric matrix A
+---------------------+
1 | 0 1 0 0 0 |
+---------------------+ Mata offers several functions to solve the linear equation system AX = B:
lusolve(A,B) A is full rank, square matrix
4.7.4 Creating a random matrix cholinv(A) A is positive definite, symmetric matrix

The uniform() function generates a matrix of random numbers whose Note: it is always numerically more accurate to solve AX = B directly
elements are uniformly distributed in the interval (0,1). For example, than to calculate X = A−1 B. Type help m4 solvers for more func-
uniform(2, 3) tions.
1 2 3
+-------------------------------------------+ An example: estimate a linear regression using the dataset auto.dta:
1 | .1369840784 .643220668 .5578016951 | webuse auto.dta
2 | .6047949435 .684175977 .1086679425 | mata
+-------------------------------------------+ y = st_data(.,"price")
uniformseed(newseed) sets the seed: a string previously obtained from X = st_data(.,("mpg", "weight"))
X = X, J(rows(X),1,1)
uniformseed() may be specified for the argument, or an integer number b = invsym(X’*X)*X’*y
may be specified. uniformseed() has the same effect as Stata’s set seed
There is a better version that saves memory, addresses missing values,
command.
elegantly adds a constant and efficiently solves for the parameter vector
Mata has no built-in function to draw from the normal distribution. In-
M = X = y = .
dependent draws from standard normal can be generated by applying the st_view(M, ., ("price", "mpg", "weight"), 0)
inverse cumulative normal distribution to uniform draws. For example, st_subview(y, M, ., 1)
st_subview(X, M, ., (2\.))
invnormal(uniform(2,3)) XX = cross(X,1,X,1)
1 2 3 Xy = cross(X,1,y,0)
+----------------------------------------------+ b = cholsolve(XX,Xy)
1 | .3014337824 -1.545904789 .1389086436 |
2 | 1.133267712 -.6583710099 -1.700496348 |
+----------------------------------------------+
25 Topics in Applied Economics I Coding with Mata in Stata 26

5 Controlling the flow The do-loop

do {
5.1 Loops stmt
} while (exp)
The while-loop executes stmt one or more times, until expr is zero. For example
while (expr) { n = 5
stmt i = 1
} do {
printf("i=%g\n", i)
executes stmt zero or more times as long as expr is not equal to zero.
i++
For example } while (i<=n)
printf("done\n")
n = 5
i = 1 break exits the innermost for, while, or do loop.
while (i<=n) {
printf("i=%g\n", i) continue restarts the innermost for, while, or do loop.
i++
}
printf("done\n") 5.2 Conditional statements
The for-loop
The if condition
for (expr1; expr2; expr3) {
stmts if (expr) {
} stmt
}
is equivalent to
evaluates expr, and if it is true (evaluates to a nonzero number), stmt is
expr1
executed. Several conditions can be nested by else if ; else introduces
while (expr2) {
stmt a statement that is executed when all conditions are false:
expr3
if (expr1) {
}
stmt1
For example, }
else if (expr2) {
n = 5 stmt2
for (i=1; i<=n; i++) { }
printf("i=%g\n", i) else {
} stmt3
printf("done\n") }

For example,
27 Topics in Applied Economics I Coding with Mata in Stata 28

n = 5 6.2 Declarations
i = 1
while (1) { Variables (scalar, vectors and matrices) need not be declared in Mata
printf("i=%g\n", i)
i++ functions. However, careful programmers use declarations in Mata. See
if (i>n) { help m2 declarations for a discussion.
break
} In the above example we would add declarations at three places: in
} front of function definitions, inside the parentheses defining the function’s
printf("i=%g\n", i)
arguments, and at the top of the body of the function, defining private
printf("done\n")
variables the function will use:
real colvector zeros(real scalar c)
6 Coding Mata functions {
real colvector a
a = J(c,1,0)
6.1 Defining functions return(a)
}
Mata allows you to create new function. For example,
In this case we tell Mata what input to expect (a scalar) and, if someone
function zeros(c) attempts to use our function incorrectly, Mata will stop execution.
{
a = J(c, 1, 0) Declarations consist of an element type (transmorphic, numeric, real,
return(a) complex, string, pointer) and an organizational type (matrix, vector,
}
rowvector, colvector, scalar).
returns a cx1 column vector of zeros. You can call the function as any
By default, declarations are optional in Mata. However, you can ask in
Mata function:
the Stata command prompt (not Mata) to be strict on declarations
b = zeros(3)
b set matastrict on
1
+-----+
1 | 0 |
2 | 0 | 6.3 Passing arguments
3 | 0 |
+-----+ Functions may require several arguments separated by a “,”. Suppose
we extend the above function zeros() to create matrices of zeros:
real matrix zeros(real scalar c, real scalar r)
{
real matrix A
29 Topics in Applied Economics I Coding with Mata in Stata 30

A = J(c, r, 0) return(J(c, 1, 0))

return(A) }
} else {
return(J(c, r, 0))
Functions may be coded to allow receiving a variable number of argu- }
ments. This is done by placing a vertical or bar (|) in front of the }
first argument that is optional. For instance, we could allow the function A function is said to be void if it returns nothing. For example,
zeros() to return a matrix if both arguments are specified and a column
void zeros(real matrix A, real scalar c,| real scalar r)
vector if only the first one is specified: {
real matrix zeros(real scalar c,| real scalar r) if (args()==1) {
{ A = J(c, 1, 0)
real matrix A }
else {
if (args()==1) r = 1 A = J(c, r, 0)
A = J(c, r, 0) }
return(A) }
}
returns nothing but changes the value of the matrix A which is passed
The function args() is used to determine the number of arguments. as first argument:
Important to note: Mata passes arguments to functions by address not A = .
by value. When you code zeros(A, 2, 3)
A
f(n) 1 2 3
+-------------+
it is the address of n that is passed to f(), not a copy of the values in n. 1 | 0 0 0 |
f(n) can therefore modify n. 2 | 0 0 0 |
+-------------+
See help m2 syntax for more details.

6.5 .mo and .mlib files

6.4 Returning values
Once defined, new Mata functions can be stored as object code (i.e.
return(expr) causes the function to stop execution and return to the in compiled form) in .mo files using the mata mosave command. The
caller, returning the evaluation of expr. return(expr) may appear mul- function can then be accessed in subsequent Mata sessions without being
tiple times in the program. For example, defined again.
real matrix zeros(real scalar c,| real scalar r) For example, running the following .do file:
{
if (args()==1) {
31 Topics in Applied Economics I Coding with Mata in Stata 32

version 10 local N = r(N)

mata: matname ‘b’ ‘indepvar’ _cons, c(.)
matname ‘V’ ‘indepvar’ _cons
real matrix zeros(real scalar c,| real scalar r) ereturn post ‘b’ ‘V’, depname(‘depvar’) obs(‘N’) esample(‘touse’)
{ ereturn local cmd = "ols"
real matrix A ereturn display

if (args()==1) r = 1 end
A = J(c, r, 0)
return(A) capture mata mata drop m_ols()
} version 10
mata:
mata mosave zeros(), replace void m_ols(string scalar varlist, string scalar touse)
{
end real matrix M, X, V
real colvector y, b
will produce the file zeros.mo which is stored in the working directory. real scalar n, k, s2
If you close Stata and run it again, the function zeros() will be readily
M = X = y = .
available.
st_view(M, ., tokens(varlist), touse)
Several Mata functions can be simultaneously stored in a .mlib file. See st_subview(y, M, ., 1)
st_subview(X, M, ., (2\.))
help mata_mlib for more details. n = rows(X)
k = cols(X)
XX = cross(X,1,X,1)
7 Coding Stata commands using Mata if (rank(XX) < k+1) {
errprintf("near singular matrix\n")
exit(499)
7.1 An example }
Xy = cross(X,1,y,0)
The following Stata and Mata commands are stored in the file ols.ado: b = cholsolve(XX,Xy)
e = y - (X, J(n,1,1))*b
program define ols, eclass s2 = (e’e)/(n-k)
version 10.0 V = s2*cholinv(XX)
syntax varlist(numeric) [if] [in]
gettoken depvar indepvar: varlist st_eclear()
marksample touse st_matrix("r(b)", b)
st_matrix("r(V)", V)
mata: m_ols("‘varlist’", "‘touse’") st_numscalar("r(N)", n)
}
tempname b V end
matrix ‘b’ = r(b)’
matrix ‘V’ = r(V)
33 Topics in Applied Economics I

8 Important Functions and Operators

See help function for a comprehensive list of available functions.