**Acknowledgment**

**1 Introduction**

**2 The mechanics of using Mata**

2.1 Introduction

2.2 Mata code appearing in do-files

2.3 Mata code appearing in ado-files

2.4 Mata code to be exposed publicly

**3 A programmer's tour of Mata**

3.1 Preliminaries

3.1.1 Results of expressions are displayed when not stored

3.1.2 Assignment

3.1.3 Multiple assignment

3.2 Real, complex, and string values

3.2.1 Real values

3.2.2 Complex values

3.2.3 String values (ASCII, Unicode, and binary)

3.3 Scalars, vectors, and matrices

3.3.1 Functions rows(), cols(), and length()

3.3.2 Function I()

3.3.3 Function J()

3.3.4 Row-join and column-join operators

3.3.5 Null vectors and null matrices

3.4 Mata's advanced features

3.4.1 Variable types

3.4.2 Structures

3.4.3 Classes

3.4.4 Pointers

3.5 Notes for programmers

3.5.1 How programmers use Mata's interactive mode

3.5.2 What happens when code has errors

3.5.3 The _error() abort function

**4 Mata's programming statements**

4.1 The structure of Mata programs

4.2 The program body

4.2.1 Expressions

4.2.2 Conditional execution statement

4.2.3 Looping statements

4.2.3.1 while

4.2.3.2 for

4.2.3.3 do while

4.2.3.4 continue and break

4.2.4 goto

4.2.5 return

4.2.5.1 Functions returning values

4.2.5.2 Functions returning void

**5 Mata's expressions**

5.1 More surprises

5.2 Numeric and string literals

5.2.1 Numeric literals

5.2.1.1 Base-10 notation

5.2.1.2 Base-2 notation

5.2.2 Complex literals

5.2.3 String literals

5.3 Assignment operator

5.4 Operator precedence

5.5 Arithmetic operators

5.6 Increment and decrement operators

5.7 Logical operators

5.8 (Understand this ? skip : read) Ternary conditional operator

5.9 Matrix row and column join and range operators

5.9.1 Row and column join

5.9.2 Comma operator is overloaded

5.9.3 Row and column count vectors

5.10 Colon operators for vectors and matrices

5.11 Vector and matrix subscripting

5.11.1 Element subscripting

5.11.2 List subscripting

5.11.3 Permutation vectors

5.11.3.1 Use to sort data

5.11.3.2 Use in advanced mathematical programming

5.11.4 Submatrix subscripting

5.12 Pointer and address operators

5.13 Cast-to-void operator

**6 Mata's variable types**

6.1 Overview

6.2 The forty variable types

6.2.1 Default initialization

6.2.2 Default eltype, orgtype, and therefore, variable type

6.2.3 Partial types

6.2.4 A forty-first type for returned values from functions

6.3 Appropriate use of transmorphic

6.3.1 Use transmorphic for arguments of overloaded functions

6.3.2 Use transmorphic for output arguments

6.3.2.1 Use transmorphic for passthru variables

6.3.3 You must declare structures and classes if not passthru

6.3.4 How to declare pointers

**7 Mata's strict option and Mata's pragmas**

7.1 Overview

7.2 Turning matastrict on and off

7.3 The messages that matastrict produces, and suppressing them

**8 Mata's function arguments**

8.1 Introduction

8.2 Functions can change the contents of the caller's arguments

8.2.1 How to document arguments that are changed

8.2.2 How to write functions that do not unnecessarily change arguments

8.3 How to write functions that allow a varying number of arguments

8.4 How to write functions that have multiple syntaxes

**9 Programming example: n_choose_k() three ways**

9.1 Overview

9.2 Developing n_choose_k()

9.3 n_choose_k() packaged as a do-file

9.3.1 How I packaged the code: n_choose_k.do

9.3.2 How I could have packaged the code

9.3.2.1 n_choose_k.mata

9.3.2.2 test_n_choose_k.do

9.3.3 Certification files

9.4 n_choose_k() packaged as an ado-file

9.4.1 Writing Stata code to call Mata functions

9.4.2 nchooseki.ado

9.4.3 test_nchooseki.do

9.4.4 Mata code inside of ado-files is private

9.5 n_choose_k() packaged as a Mata library routine

9.5.1 Your approved source directory

9.5.1.1 make_lmatabook.do

9.5.1.2 test.do

9.5.1.3 hello.mata

9.5.1.4 n_choose_k.mata

9.5.1.5 test_n_choose_k.do

9.5.2 Building and rebuilding libraries

9.5.3 Deleting libraries

**10 Mata's structures**

10.1 Overview

10.2 You must define structures before using them

10.3 Structure jargon

10.4 Adding variables to structures

10.5 Structures containing other structures

10.6 Surprising things you can do with structures

10.7 Do not omit the word scalar in structure declarations

10.8 Structure vectors and matrices and use of the constructor function

10.9 Use of transmorphic with structures

10.10 Structure pointers

**11 Programming example: Linear regression**

11.1 Introduction

11.2 Self-threading code

11.3 Linear-regression system lr*() version 1

11.3.1 lr*() in action

11.3.2 The calculations to be programmed

11.3.3 lr*() version-1 code listing

11.3.4 Discussion of the lr*() version-1 code

11.3.4.1 Getting started

11.3.4.2 Assume subroutines

11.3.4.3 Learn about Mata's built-in subroutines

11.3.4.4 Use of built-in subroutine cross()

11.3.4.5 Use more subroutines

11.4 Linear-regression system lr*() version 2

11.4.1 The deviation from mean formulas

11.4.2 The lr*() version-2 code

11.4.3 lr*() version-2 code listing

11.4.4 Other improvements you could make

11.5 Closeout of lr*() version 2

11.5.1 Certification

11.5.2 Adding lr*() to the lmatabook.mlib library

**12 Mata's classes**

12.1 Overview

12.1.1 Classes contain member variables

12.1.2 Classes contain member functions

12.1.3 Member functions occult external functions

12.1.4 Members—variables and functions—can be private

12.1.5 Classes can inherit from other classes

12.1.5.1 Privacy versus protection

12.1.5.2 Subclass functions occult superclass functions

12.1.5.3 Multiple inheritance

12.1.5.4 And more

12.2 Class creation and deletion

12.3 The this prefix

12.4 Should all member variables be private?

12.5 Classes with no member variables

12.6 Inheritance

12.6.1 Virtual functions

12.6.2 Final functions

12.6.3 Polymorphisms

12.6.4 When to use inheritance

12.7 Pointers to class instances

**13 Programming example: Linear regression 2**

13.1 Introduction

13.2 LinReg in use

13.3 LinReg version-1 code

13.4 Adding OPG and robust variance estimates to LinReg

13.4.1 Aside on numerical accuracy: Order of addition

13.4.2 Aside on numerical accuracy: Symmetric matrices

13.4.3 Finishing the code

13.5 LinReg version-2 code

13.6 Certifying LinReg version 2

13.7 Adding LinReg version 2 to the lmatabook.mlib library

**14 Better variable types**

14.1 Overview

14.2 Stata's macros

14.3 Using macros to create new types

14.4 Macroed types you might use

14.4.1 The boolean type

14.4.2 The Code type

14.4.3 Filehandle

14.4.4 Idiosyncratic types, such as Filenames

14.4.5 Macroed types for structures

14.4.6 Macroed types for classes

14.4.7 Macroed types to avoid name conflicts

**15 Programming constants**

15.1 Problem and solution

15.2 How to define constants

15.3 How to use constants

15.4 Where to place constant definitions

**16 Mata's associative arrays**

16.1 Introduction

16.2 Using class AssociativeArray

16.3 Finding out more about AssociativeArray

**17 Programming example: Sparse matrices**

17.1 Introduction

17.2 The idea

17.3 Design

17.3.1 Producing a design from an idea

17.3.2 The design goes bad

17.3.3 Fixing the design

17.3.3.1 Sketches of R_*x*() and S_*x*() subroutines

17.3.3.2 Sketches of class's multiplication functions

17.3.4 Design summary

17.3.5 Design shortcomings

17.4 Code

17.5 Certification script

**18 Programming example: Sparse matrices, continued**

18.1 Introduction

18.2 Making overall timings

18.2.1 Timing T1, Mata R=RR

18.2.2 Timing T2, SpMat R=RR

18.2.3 Timing T3, SpMat R=SR

18.2.4 Timing T4, SpMat R=RS

18.2.5 Timing T5, SpMat R=SS

18.2.6 Call a function once before timing

18.2.7 Summary

18.3 Making detailed timings

18.3.1 Mata's timer() function

18.3.2 Make a copy of the code to be timed

18.3.3 Make a do-file to run the example to be timed

18.3.4 Add calls to timer_on() and timer_off() to the code

18.3.5 Analyze timing results

18.4 Developing better algorithms

18.4.1 Developing a new idea

18.4.2 Aside

18.4.2.1 Features of associative arrays

18.4.2.2 Advanced use of pointers

18.5 Converting the new idea into code sketches

18.5.0.3 Converting the idea into a sketch of R_SxS()

18.5.0.4 Sketching subroutine cols_of_row()

18.5.1 Converting sketches into completed code

18.5.1.1 Double-bang comments and messages

18.5.1.2 // NotReached comments

18.5.1.3 Back to converting sketches

18.5.2 Measuring performance

18.6 Cleaning up

18.6.1 Finishing R_SxS() and cols_of_row()

18.6.2 Running certification

18.7 Continuing development

**19 The Mata Reference Manual**

**A Writing Mata code to add new commands to Stata**

A.1 Overview

A.2 Ways to structure code

A.3 Accessing Stata's data from Mata

A.4 Handling errors

A.5 Making the calculation and displaying results

A.6 Returning results

A.7 The Stata interface functions

A.7.1 Accessing Stata's data

A.7.2 Modifying Stata's data

A.7.3 Accessing and modifying Stata's metadata

A.7.4 Changing Stata's dataset

A.7.5 Accessing and modifying Stata macros, scalars, matrices

A.7.6 Executing Stata commands from Mata

A.7.7 Other Stata interface functions

**B Mata's storage type for complex numbers**

B.1 Complex values

B.2 Complex values and literals

B.3 Complex scalars, vectors, and matrices

B.4 Real, complex, and numeric eltypes

B.5 Functions Re(), Im(), and C()

B.6 Function eltype()

**C How Mata differs from C and C++**

C.1 Introduction

C.2 Treatment of semicolons

C.3 Nested comments

C.4 Argument passing

C.5 Strings are not arrays of characters

C.6 Pointers

C.6.1 Pointers to existing objects

C.6.2 Pointers to new objects, allocation of memory

C.6.3 The size and even type of the object may change

C.6.4 Pointers to new objects, freeing of memory

C.6.5 Pointers to subscripted values

C.6.6 Pointer arithmetic is not allowed

C.7 Lack of switch/case statements

C.8 Mata code aborts with error when C would crash

**D Three-dimensional arrays (advanced use of pointers)**

D.1 Introduction

D.2 Creating three-dimensional arrays

**References**