Applied Econometrics Stata Reference Working with ado-les

Nathaniel Higgins nhiggins@jhu.edu

1 An ado-le: the basics

An ado-le is an automatic do-le. Suppose you open a fresh session of Stata and load a dataset. In this dataset are three variables, y , x1, and x2. When you type regress y x1 x2 at Statas command line, Stata runs an OLS regression for you. Stata does this because there is an ado-le stored somewhere on your computer (Stata knows where it is) called regress.ado. When you type regress at the command line, Stata goes and nds the le regress.ado and executes a set of instructions given to it by regress.ado. Think of ado-les as the guts behind the commands that you issue to Stata. It gets better. You can write your own ado-les. Not only does Stata come with a lot of pre-loaded ado-les, which enable you to run all sorts of regressions, to manipulate data, etc., but Stata allows you to write your own ado-les so that you can add functionality to your software.

2 Writing your own ado-le

I want you to open up Statas do-le editor (you could use another text editor like Notepad, but if you havent done this before, its best to use the do-le editor). In the editor, type these EXACT lines of code: program add v e r s i o n 10 gen z = 1 + 2 list z end Three very important things:

1. You must have a carriage return at the end of the le (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 the le, 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 surrounded by single quotes. The left single quote is entered by pressing the key on your keyboard 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 pressing the key on your keyboard that is (usually) located to the left of the Enter key. If you dont use exactly the right type of quotes, the function we are building wont work! 3. Save the le (save it anywhere for now well move it in just a moment) as add.ado. If you write this le in Statas own do-le editor, be careful to select Ado files (*.ado) as the le type if you dont your le will be saved as a do-le instead of an ado-le and it wont work! Now, in order to make Stata aware of the program we have just created, this le must be saved 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 the Stata results window These are the places where Stata currently looks for ado-les 3. Add a location where you will store all of your ado-les and where Stata will know to look for them. Suppose you want to store all of your ado-les here: c:/ado/myadofiles. (Note that you will have to create this directory before you try to tell Stata where it is). You can make up your own location, but if you dont have a specic reason to use a dierent location, just use my suggestion. There are a few ways to do this. Here are the two that I recommend (do whichever seems easiest to you): (a) You can create a personal directory by typing a set of commands at the Stata 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 capitalization do matter. The word PERSONAL must be in all caps. If you choose 2

a dierent directory than I have suggested and your pathname contains spaces, you must enclose the pathname in double quotes. As it happens, it usually doesnt matter if you use forward- or backward slashes in the pathname. Now type: adopath again at the command line of Stata. You should nd that your personal directory is set to c:/ado/myadofiles (b) You can modify the le called profile.do on your computer Find the le called profile.do on your computer. It will usually be here: c:/Program Files/Stata10 Add a line to this le by typing: adopath + c:/ado/myadofiles Note that this change wont take eect until you restart Stata, since Stata checks your prole when it rst starts-up Go ahead and restart Stata if you havent already. Type adopath and verify that your chosen location is listed by Stata. If it is, go ahead and nd the add.ado le that you saved earlier and move it to c:/ado/myadofiles (or whatever you named your personal repository of ado-les). Now its time to test the code. To test the code, we need some data to work with. You can load any old dataset you want. If you cant think of anything o-hand, create a dataset. Just so you have something handy and you dont get distracted, you could create data using these lines of code (from an in-class example): Set seed s e t s e e d 12345 C r e a t e a matrix o f c o r r e l a t i o n s matrix C = ( 1 , 0 . 2 , 0 . 2 \ 0 . 2 , 1 , 0 . 2 \ 0 . 2 , 0 . 2 , 1 ) C r e a t e a matrix o f means matrix m = ( 3 , 2 , 2 ) C r e a t e a matrix o f s t a n d a r d d e v i a t i o n s matrix sd = ( 0 . 5 , 2 , 1 ) Draw t h r e e 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 n drawnorm x1 x2 x3 , n ( 1 0 0 ) means (m) s d s ( sd ) c o r r (C) Draw some u n o b s e r v a b l e s t u f f gen e p s = rnormal ( ) C r e a t e a dependent v a r i a b l e y gen y = 5 + 2 x1 3 x2 + e p s

Now that we have data to work with, lets try out the add function. Type add x1 x2 at the 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 rst line of code is: program add. This line of code declares the le to be a program le and gives the program a name (add). You have to have this line of code. The name of the le and the name of the program should match. The second line of code is: version 10. 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 stu starts. We are using the generate function to create a new variable called z. The new variable z is equal to the sum of the rst 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 at the command line of Stata. Right after the word add, you typed a space, then you typed the 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 blocks 1 and 2. When you type 1 in the ado-le, you are telling Stata to use whatever variable the user (the person typing things at the command line of Stata) submits as the rst argument to the function add. Likewise, when you type 2 in the ado-le, you are telling Stata to use whatever variable the user submits as the second argument to the function add. Notice that there is no provision for a third variable. So, if you were to type add x1 x2 x3 at the command line of Stata (youll have to drop z rst), you should notice that the new variable z is actually still equal to x1 + x2. Since Stata has no 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 results window. You could leave this line of code out and the new variable z would still be created, but it wouldnt be displayed. Finally, the fth line of code is end, and the sixth line of code is just a blank (just a carriage return after end). These are things that Stata requires. Dont ask why.