Applied Econometrics

Stata Reference

Working with ado-files

Nathaniel Higginsnhiggins@jhu.edu

1 An ado-file: the basics

An ado-file is an automatic do-file. Suppose you open a fresh session of Stata and loada dataset. In this dataset are three variables, y, x1, and x2. When you type regress yx1 x2 at Statas command line, Stata runs an OLS regression for you. Stata does thisbecause there is an ado-file stored somewhere on your computer (Stata knows where itis) called regress.ado. When you type regress at the command line, Stata goes andfinds the file regress.ado and executes a set of instructions given to it by regress.ado.Think of ado-files as the guts behind the commands that you issue to Stata.

It gets better. You can write your own ado-files. Not only does Stata come with a lot ofpre-loaded ado-files, which enable you to run all sorts of regressions, to manipulate data,etc., but Stata allows you to write your own ado-files so that you can add functionalityto your software.

2 Writing your own ado-file

I want you to open up Statas do-file editor (you could use another text editor likeNotepad, but if you havent done this before, its best to use the do-file editor). In theeditor, type these EXACT lines of code:

program addve r s i on 10gen z = 1 + 2 l i s t zend

Three very important things:

1

1. You must have a carriage return at the end of the file (after the word end above).That is, if you put the cursor right after the d in end, hit Enter on your keyboard.You can hit Enter more than once, i.e. you can have many extra blank lines in thefile, but you must do it at least once! If you dont, youll be very disappointed.

2. Look at the line of code gen z = 1 + 2. The numbers 1 and 2 are surroundedby single quotes. The left single quote is entered by pressing the key on yourkeyboard that is (usually) located to the left of the number 1 (the character usually shares the key with a tilde). The right single quote is entered by pressingthe key on your keyboard that is (usually) located to the left of the Enter key. Ifyou dont use exactly the right type of quotes, the function we are building wontwork!

3. Save the file (save it anywhere for now well move it in just a moment) asadd.ado. If you write this file in Statas own do-file editor, be careful to selectAdo files (*.ado) as the file type if you dont your file will be saved as ado-file instead of an ado-file and it wont work!

Now, in order to make Stata aware of the program we have just created, this file must besaved in a place where Stata knows to look for it. To do that, follow these steps:

1. Open up Stata (if you havent already)

2. Type:adopath

at the command line of Stata

Several directory listings (locations on your computer) will be printed to theStata results window

These are the places where Stata currently looks for ado-files3. Add a location where you will store all of your ado-files and where Stata will

know to look for them. Suppose you want to store all of your ado-files here:c:/ado/myadofiles. (Note that you will have to create this directory before youtry to tell Stata where it is). You can make up your own location, but if you donthave a specific reason to use a different location, just use my suggestion. There area few ways to do this. Here are the two that I recommend (do whichever seemseasiest to you):

(a) You can create a personal directory by typing a set of commands at theStata command line

Type:sysdir set PERSONAL c:/ado/myadofiles

at the command line of Stata

Note that you must type this verbatim. The spacing and the capitaliza-tion do matter. The word PERSONAL must be in all caps. If you choose

2

a different directory than I have suggested and your pathname containsspaces, you must enclose the pathname in double quotes. As it happens,it usually doesnt matter if you use forward- or backward slashes in thepathname.

Now type:adopath

again at the command line of Stata. You should find that your personaldirectory is set to c:/ado/myadofiles

(b) You can modify the file called profile.do on your computer

Find the file called profile.do on your computer. It will usually be here:c:/Program Files/Stata10

Add a line to this file by typing:adopath + c:/ado/myadofiles

Note that this change wont take effect until you restart Stata, since Statachecks your profile when it first starts-up

Go ahead and restart Stata if you havent already. Type adopath and verify that yourchosen location is listed by Stata. If it is, go ahead and find the add.ado file that yousaved earlier and move it to c:/ado/myadofiles (or whatever you named your personalrepository of ado-files). Now its time to test the code.

To test the code, we need some data to work with. You can load any old datasetyou want. If you cant think of anything off-hand, create a dataset. Just so you havesomething handy and you dont get distracted, you could create data using these linesof code (from an in-class example):

Set seeds e t seed 12345 Create a matrix o f c o r r e l a t i o n smatrix C = (1 , 0 . 2 , 0 . 2 \ 0 . 2 , 1 , 0 . 2 \ 0 . 2 , 0 . 2 , 1) Create a matrix o f meansmatrix m = (3 , 2 , 2 ) Create a matrix o f standard d e v i a t i o n smatrix sd = ( 0 . 5 , 2 , 1 ) Draw three random v a r i a b l e from a m u l t i v a r i a t e d i s t r i b u t i o ndrawnorm x1 x2 x3 , n (100) means (m) sds ( sd ) co r r (C) Draw some unobservable s t u f fgen eps = rnormal ( )

Create a dependent v a r i a b l e ygen y = 5 + 2x1 3x2 + eps

3

Now that we have data to work with, lets try out the add function. Type add x1 x2 atthe command line of Stata. You should see that Stata creates a new variable called z,which is equal to x1 + x2, and that z is printed to the results window of Stata.

OK, now what exactly is going on. Lets examine the add.ado line-by-line. The firstline of code is: program add. This line of code declares the file to be a program file andgives the program a name (add). You have to have this line of code. The name of thefile and the name of the program should match. The second line of code is: version10. This line tells Stata what version of Stata you intend this code to work for.

The third line of code is: gen z = 1 + 2. This is where the real stuff starts. Weare using the generate function to create a new variable called z. The new variable z isequal to the sum of the first two variables that the user types after the command add.Remember when you tested the function to see if it worked? You typed add x1 x2 atthe command line of Stata. Right after the word add, you typed a space, then you typedthe name of the variable x1, then another space, then x2. The line of code gen z = 1+ 2 tells Stata to create a new variable z, and to create it using the building blocks1 and 2. When you type 1 in the ado-file, you are telling Stata to use whatevervariable the user (the person typing things at the command line of Stata) submits asthe first argument to the function add. Likewise, when you type 2 in the ado-file, youare telling Stata to use whatever variable the user submits as the second argument tothe function add. Notice that there is no provision for a third variable. So, if you wereto type add x1 x2 x3 at the command line of Stata (youll have to drop z first), youshould notice that the new variable z is actually still equal to x1 + x2. Since Stata hasno idea what to do with a third argument, it will ignore x3.

The fourth line of code is list z. This tells Stata to print the result z to the resultswindow. You could leave this line of code out and the new variable z would still becreated, but it wouldnt be displayed.

Finally, the fifth line of code is end, and the sixth line of code is just a blank (just acarriage return after end). These are things that Stata requires. Dont ask why.

4

An ado-file: the basicsWriting your own ado-file