[U] User's Guide

234 [ U ] 18 Programming StataThe return() function is just like the r() function, except that return() refers to the results thatthis program will return rather than to the saved results that currently are returned (which here are dueto summarize). That is, when you code the return command, the result is not immediately postedto r(). Rather, Stata holds onto the result in return() until your program concludes, and then itcopies the contents of return() to r(). While your program is active, you may use the return()function to access results you have already “returned”. (return() works just like r() works afteryour program returns, meaning that you may code ‘return()’ to perform macro substitution.)18.10.2 Saving results in e()Saving in e() is in most ways similar to saving in r(): you add the eclass option to the programstatement, and then you use ereturn . . . just as you used return . . . to store results. There are,however, some significant differences:1. Unlike r(), estimation results are saved in e() the instant you issue an ereturn scalar,ereturn local, or ereturn matrix command. Estimation results can consume considerablememory, and Stata does not want to have multiple copies of the results floating around. Thatmeans you must be more organized and post your results at the end of your program.2. In your code when you have your estimates and are ready to begin posting, you will firstclear the previous estimates, set the coefficient vector e(b) and corresponding variance matrixe(V), and set the estimation-sample function e(sample). How you do this depends on howyou obtained your estimates:2.1 If you obtained your estimates by using Stata’s likelihood maximizer ml, this is automaticallyhandled for you; skip to step 3.2.2 If you obtained estimates by “stealing” an existing estimator, e(b), e(V), and e(sample)already exist, and you will not want to clear them; skip to step 3.2.3 If you write your own code from start to finish, you use the ereturn post command;see [P] ereturn. You will code something like “ereturn post ‘b’ ‘V’, esample(‘touse’)”,where ‘b’ is the name of the coefficient vector, ‘V’ is the name ofthe corresponding variance matrix, and ‘touse’ is the name of a variable containing 1if the observation was used and 0 if it was ignored. ereturn post clears the previousestimates and moves the coefficient vector, variance matrix, and variable into e(b), e(V),and e(sample).2.4 A variation on (2.3) is when you use an existing estimator to produce the estimates butdo not want all the other e() results stored by the estimator. Then you codetempvar tousetempname b Vmatrix ‘b’ = e(b)matrix ‘V’ = e(V)qui gen byte ‘touse’ = e(sample)ereturn post ‘b’ ‘V’, esample(‘touse’)3. You now save anything else in e() that you wish by using the ereturn scalar, ereturnlocal, or ereturn matrix command.4. Save e(cmdline) by codingereturn local cmdline ‘"‘0’"’This is not required, but it is considered good style.