# The Mata Book: A Book for Serious Programmers and Those Who Want to Be

The Mata Book: A Book for Serious Programmers and Those Who Want to Be is the book that Stata programmers have been waiting for. Mata is a serious programming language for developing small- and large-scale projects and for adding features to Stata. What makes Mata serious is that it provides structures, classes, and pointers along with matrix capabilities. The book is serious in that it covers those advanced features, and teaches them. The reader is assumed to have programming experience, but only some programming experience. That experience could be with Stata’s ado-language, or with Python, Java, C++, Fortran, or other languages like them. As the book says, “being serious is a matter of attitude, not current skill level or knowledge”.

Acknowledgment

1. INTRODUCTION

Is this book for me?

What is Mata?
What is covered in this book

2. THE MECHANICS OF USING MATA

Introduction
Mata code appearing in do-files
Mata code to be exposed publicly

3. A PROGRAMMER’S TOUR OF MATA

Preliminaries

Results of expressions are displayed when not stored
Assignment
Multiple assignment

Real, complex, and string values

Real values
Complex values
String values (ASCII, Unicode, and binary)

Scalars, vectors, and matrices

Functions rows(), cols(), and length()
Function I()
Function J()
Row-join and column-join operators
Null vectors and null matrices

Variable types
Structures
Classes
Pointers

Notes for programmers

How programmers use Mata’s interactive mode
What happens when code has errors
The _error() abort function

4. MATA’S PROGRAMMING STATEMENTS

The structure of Mata programs
The program body

Expressions
Conditional execution statement
Looping statements

while
for
do while
continue and break

goto
return

Functions returning values
Functions returning void

5. MATA’S EXPRESSIONS

More surprises
Numeric and string literals

Numeric literals

Base-10 notation
Base-2 notation

Complex literals
String literals

Assignment operator
Operator precedence
Arithmetic operators
Increment and decrement operators
Logical operators
(Understand this ? skip : read) Ternary conditional operator
Matrix row and column join and range operators

Row and column join
Row and column count vectors

Colon operators for vectors and matrices
Vector and matrix subscripting

Element subscripting
List subscripting
Permutation vectors

Use to sort data

Submatrix subscripting

Cast-to-void operator

6. MATA’S VARIABLE TYPES

Overview
The forty variable types

Default initialization
Default eltype, orgtype, and therefore, variable type
Partial types
A forty-first type for returned values from functions

Appropriate use of transmorphic

Use transmorphic for arguments of overloaded functions
Use transmorphic for output arguments

Use transmorphic for passthru variables

You must declare structures and classes if not passthru
How to declare pointers

7. MATA’S STRICT OPTION AND MATA’S PRAGMAS

Overview
Turning matastrict on and off
The messages that matastrict produces, and suppressing them

8. MATA’S FUNCTION ARGUMENTS

Introduction
Functions can change the contents of the caller’s arguments

How to document arguments that are changed
How to write functions that do not unnecessarily change arguments

How to write functions that allow a varying number of arguments
How to write functions that have multiple syntaxes

9. PROGRAMMING EXAMPLE: N_CHOOSE_K() THREE WAYS

Overview
Developing n_choose_k()
n_choose_k() packaged as a do-file

How I packaged the code: n_choose_k.do
How I could have packaged the code

n_choose_k.mata
test_n_choose_k.do

Certification files

Writing Stata code to call Mata functions
test_nchooseki.do
Mata code inside of ado-files is private

n_choose_k() packaged as a Mata library routine

make_lmatabook.do
test.do
hello.mata
n_choose_k.mata
test_n_choose_k.do

Building and rebuilding libraries
Deleting libraries

10. MATA’S STRUCTURES

Overview
You must define structures before using them
Structure jargon
Structures containing other structures
Surprising things you can do with structures
Do not omit the word scalar in structure declarations
Structure vectors and matrices and use of the constructor function
Use of transmorphic with structures
Structure pointers

11. PROGRAMMING EXAMPLE: LINEAR REGRESSION

Introduction
Linear-regression system lr*() version 1

lr*() in action
The calculations to be programmed
lr*() version-1 code listing
Discussion of the lr*() version-1 code

Getting started
Assume subroutines
Use of built-in subroutine cross()
Use more subroutines

Linear-regression system lr*() version 2

The deviation from mean formulas
The lr*() version-2 code
lr*() version-2 code listing
Other improvements you could make

Closeout of lr*() version 2

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

12. MATA’S CLASSES

Overview

Classes contain member variables
Classes contain member functions
Member functions occult external functions
Members—variables and functions—can be private
Classes can inherit from other classes

Privacy versus protection
Subclass functions occult superclass functions
Multiple inheritance
And more

Class creation and deletion
The this prefix
Should all member variables be private?
Classes with no member variables
Inheritance

Virtual functions
Final functions
Polymorphisms
When to use inheritance

Pointers to class instances

13. PROGRAMMING EXAMPLE: LINEAR REGRESSION 2

Introduction
LinReg in use
LinReg version-1 code
Adding OPG and robust variance estimates to LinReg

Aside on numerical accuracy: Order of addition
Aside on numerical accuracy: Symmetric matrices
Finishing the code

LinReg version-2 code
Certifying LinReg version 2
Adding LinReg version 2 to the lmatabook.mlib library

14. BETTER VARIABLE TYPES

Overview
Stata’s macros
Using macros to create new types
Macroed types you might use

The boolean type
The Code type
Filehandle
Idiosyncratic types, such as Filenames
Macroed types for structures
Macroed types for classes
Macroed types to avoid name conflicts

15. PROGRAMMING CONSTANTS

Problem and solution
How to define constants
How to use constants
Where to place constant definitions

16. MATA’S ASSOCIATIVE ARRAYS

Introduction
Using class AssociativeArray

17. PROGRAMMING EXAMPLE: SPARSE MATRICES

Introduction
The idea
Design

Producing a design from an idea
Fixing the design

Sketches of R_*x*() and S_*x*() subroutines
Sketches of class’s multiplication functions

Design summary
Design shortcomings
Code
Certification script

18. PROGRAMMING EXAMPLE: SPARSE MATRICES, CONTINUED

Introduction
Making overall timings

Timing T1, Mata R=RR
Timing T2, SpMat R=RR
Timing T3, SpMat R=SR
Timing T4, SpMat R=RS
Timing T5, SpMat R=SS
Call a function once before timing
Summary

Making detailed timings

Mata’s timer() function
Make a copy of the code to be timed
Make a do-file to run the example to be timed
Add calls to timer_on() and timer_off() to the code
Analyze timing results

Developing better algorithms

Developing a new idea
Aside

Features of associative arrays

Converting the new idea into code sketches

Converting the idea into a sketch of R_SxS()
Sketching subroutine cols_of_row()

Converting sketches into completed code

Back to converting sketches

Measuring performance

Cleaning up

Finishing R_SxS() and cols_of_row()
Running certification

Continuing development

19. THE MATA REFERENCE MANUAL

A. Writing Mata code to add new commands to Stata

Overview
Ways to structure code
Accessing Stata’s data from Mata
Handling errors
Making the calculation and displaying results
Returning results
The Stata interface functions

Accessing Stata’s data
Modifying Stata’s data
Changing Stata’s dataset
Accessing and modifying Stata macros, scalars, matrices
Executing Stata commands from Mata
Other Stata interface functions

B. Mata’s storage type for complex numbers

Complex values
Complex values and literals
Complex scalars, vectors, and matrices
Real, complex, and numeric eltypes
Functions Re(), Im(), and C()
Function eltype()

C. How Mata differs from C and C++

Introduction
Treatment of semicolons
Argument passing
Strings are not arrays of characters
Pointers

Pointers to existing objects
Pointers to new objects, allocation of memory
The size and even type of the object may change
Pointers to new objects, freeing of memory
Pointers to subscripted values
Pointer arithmetic is not allowed

Lack of switch/case statements
Mata code aborts with error when C would crash

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

Introduction
Creating three-dimensional arrays

References
Author index
Subject index Author: William Gould
ISBN-13: 978-1-59718-263-8