In addition to the output in the shown in the results window, many of Stata’s commands store information about the command and it’s results in memory. This allows the user, as well as other Stata commands, to easily make use of this information. Stata calls these returned results. Returned results can be very useful when you want to use information produced by a Stata command to do something else in Stata. For example, if you want to mean center a variable, you can use summarize to calculate the mean, then use the value of the mean calculated by summarize to center the variable. Using returned results will eliminate the need to retype or cut and paste the value of the mean. Another example of how returned results can be useful is if you want to generate predicted values of the outcome variable when the predictor variables are at a specific set of values, again here, you could retype the coefficients or use cut and paste, but returned results make the task much easier.
The best way to get a sense of how returned results work is to jump right in and start looking at and using them. The code below opens an example dataset and uses summarize (abbreviated sum) to generate descriptive statistics for the variable read. This produces the expected output, but more importantly for our purposes, Stata now has results from the summarize command stored in memory. But how do you know what information has been stored? A listing of the information saved by each command is included in the help file and/or printed manual, so I could look there, but I can also just type return list, which will list all the returned results in memory.
use https://stats.idre.ucla.edu/stat/stata/notes/hsb2, clear
sum read
Variable | Obs Mean Std. Dev. Min Max
-------------+--------------------------------------------------------
read | 200 52.23 10.25294 28 76
return list
scalars:
r(N) = 200
r(sum_w) = 200
r(mean) = 52.23
r(Var) = 105.1227135678392
r(sd) = 10.25293682648241
r(min) = 28
r(max) = 76
r(sum) = 10446
Above is a list of the returned results, as you can see each result is of the form r(…) where the ellipses ("…") is a short label. We could see the help file for the summarize command to find out what each item on the list is, but it is often easy to figure out what value is assigned to what result, for example, r(mean), not surprisingly contains the mean of read (you can check this against the output), but others are not as obvious, for example r(sum_w), for these, you may need to consult the manual if you think you might want to use them. Most of the time the process will be relatively easy because you’ll know what result you want to access, you will be looking at the list to find out what name it is stored under, rather than looking at the list and trying to figure out what each item is.
As you might imagine, different commands, and even the same command with different options, store different results. Below we summarize the variable read again, but add the detail option. Then we use return list to get the list of returned results. Just as the detail option adds additional information to the output, it also results in additional information stored in the returned results. The new list includes all of the information returned by the sum command above, plus skewness; kurtosis; and a number of percentiles, including the 1st ( r(p25) )and 3rd ( r(p75) ) quartiles and the median ( r(p50) ).
sum read, detail
reading score
-------------------------------------------------------------
Percentiles Smallest
1% 32.5 28
5% 36 31
10% 39 34 Obs 200
25% 44 34 Sum of Wgt. 200
50% 50 Mean 52.23
Largest Std. Dev. 10.25294
75% 60 73
90% 67 73 Variance 105.1227
95% 68 76 Skewness .1948373
99% 74.5 76 Kurtosis 2.363052
return list
scalars:
r(N) = 200
r(sum_w) = 200
r(mean) = 52.23
r(Var) = 105.1227135678392
r(sd) = 10.25293682648241
r(skewness) = .1948372909440272
r(kurtosis) = 2.363051990033788
r(sum) = 10446
r(min) = 28
r(max) = 76
r(p1) = 32.5
r(p5) = 36
r(p10) = 39
r(p25) = 44
r(p50) = 50
r(p75) = 60
r(p90) = 67
r(p95) = 68
r(p99) = 74.5
Now that we have some sense of what results are returned by the summarize command, we can make use of the returned results. Following through with one of the examples mentioned above, we will mean center the variable read. Assuming that the last command we ran was the summarize command above, the code below uses generates a new variable, c_read that contains the mean centered values of read. Notice that instead of using the actual value of the mean of read in this command, we used the name of the returned result (i.e. r(mean)), Stata knows when it sees r(mean) that we actually mean the value stored in that system variable. On the next line we summarize the new variable c_read, while the mean is not exactly equal to zero, it is within rounding error of zero, so we know that we have properly mean centered the variable read.
gen c_read = read - r(mean)
sum c_read
Variable | Obs Mean Std. Dev. Min Max
-------------+--------------------------------------------------------
c_read | 200 2.18e-07 10.25294 -24.23 23.77
As the code above suggests, we can use returned results pretty much the same way we would use an actual number. This is because Stata uses the r(…) as a placeholder for a real value. For another example of this, say that we want to calculate the variance of read from its standard deviation (ignoring the fact that summarize returns the variance in r(Var)). We can do this on the fly using the display command as a calculator. The second line of code below does this. We can even check the result by cutting and pasting the value of the standard deviation from the output, which is done in the third command below. The results are basically the same, the very slight difference is rounding error because the stored estimate r(sd) contains more digits of accuracy than the value of the standard deviation displayed in the output.
display r(sd)^2 105.12271 display 10.25294^2 105.12278
Types of returned results, r-class and e-class
Now that you know a little about returned results and how they work you are ready for a little more information about them. Returned results come in two main types, r-class, and e-class (there are also s-class and c-class results/variables, but we will not discuss them here). Commands that perform estimation, for example regressions of all types, factor analysis, and anova are e-class commands. Other commands, for example summarize, correlate and post-estimation commands, are r-class commands. The distinction between r-class and e-class commands is important because Stata stores results from e-class and r-class commands in different "places." This has two ramifications for you as a user. First, you need to know whether results are stored in r() or e() (as well as the name of the result) in order to make use of them. If you’re not sure which class a command you’ve run is in, you can either look it up in the help file, or "look" in one place (using the appropriate command to list results), if the results are not stored there they are probably in the other. A potentially more important ramification of the difference in how results from r-class and e-class commands are returned is that returned results are held in memory only until another command of the same class is run. That is, returned results from previous commands are replaced by subsequent commands of the same class. In contrast, running a command of another class will not affect the returned results. For example, if I run a regression, and then a second regression, the results of the first regression (stored in e()) are replaced by those for the second regression (also stored in e()) . However, if instead of a second regression, I ran a post-estimation command, the results from the regression would remain in e() while the results from the post estimation command would be placed in r().
While there is a distinction between the two, the actual use of results from r-class and e-class commands is very similar. For starters, the commands are parallel, to list the r-class results stored in memory the command is return list, to do the same for e-class results the command ereturn list. Further, except for the difference in naming conventions (r() vs. e()), the results are accessed in the same way. The example below demonstrates this, first we regress write on female and read, and then use ereturn list to look at the returned results.
regress write female read
Source | SS df MS Number of obs = 200
-------------+------------------------------ F( 2, 197) = 77.21
Model | 7856.32118 2 3928.16059 Prob > F = 0.0000
Residual | 10022.5538 197 50.8759077 R-squared = 0.4394
-------------+------------------------------ Adj R-squared = 0.4337
Total | 17878.875 199 89.843593 Root MSE = 7.1327
------------------------------------------------------------------------------
write | Coef. Std. Err. t P>|t| [95% Conf. Interval]
-------------+----------------------------------------------------------------
female | 5.486894 1.014261 5.41 0.000 3.48669 7.487098
read | .5658869 .0493849 11.46 0.000 .468496 .6632778
_cons | 20.22837 2.713756 7.45 0.000 14.87663 25.58011
------------------------------------------------------------------------------
ereturn list
scalars:
e(N) = 200
e(df_m) = 2
e(df_r) = 197
e(F) = 77.21062421518363
e(r2) = .4394192130387506
e(rmse) = 7.132734938503835
e(mss) = 7856.321182518186
e(rss) = 10022.5538174818
e(r2_a) = .4337280375366059
e(ll) = -675.2152914029985
e(ll_0) = -733.0934827146213
macros:
e(cmdline) : "regress write female read"
e(title) : "Linear regression"
e(vce) : "ols"
e(depvar) : "write"
e(cmd) : "regress"
e(properties) : "b V"
e(predict) : "regres_p"
e(model) : "ols"
e(estat_cmd) : "regress_estat"
matrices:
e(b) : 1 x 3
e(V) : 3 x 3
functions:
e(sample)
The list of returned results for regress includes several types of returned results listed under the headings scalars, macros, matrices and functions. We will discuss the types of returned results below, but for now we will show how you can use the scalar returned results the same way that we used the returned results from summarize. For example, one way to calculate the variance of the errors after a regression is to divide the residual sum of squares by the total degrees of freedom (i.e. n-1). The residual sum of squares is stored in e(rss) and that the n for the analysis is stored in e(N). Below we use the display command as a calculator, along with the returned results to calculate the variance of the errors.
display e(rss)/(e(N)-1) 50.364592
How results are returned: Scalars, strings, matrices and functions
As mentioned above, for both r-class and e-class commands, there are multiple types of returned results, including scalars, strings, matrices, and functions. In the lists of returned results, each type is listed under its own heading. The results listed under the heading "scalars" are just that, a single numeric value. Their usage is discussed above, so we won’t say anymore about them in this section.
Returned results listed under "macros" are generally strings that give information about the command that was run. For example, in the returned results of for the regression shown above, e(cmd_line) contains the command the user issued (without any abbreviations). These are generally used in programming Stata.
Results listed under "matrices" are, as you would expect, matrices. While the list of results returned by return list and erturn list show you the values taken on by most of the returned results, this is not practical with matrices, instead the dimensions of the matrices are listed. To see the contents of matrices you must display them using matrix commands. We do this below with the matrix of coefficients (e(b)) using the command matrix list e(b). (Note that there is another way to access coefficients and their standard errors after you fit a model, this is discussed below.) If we would like to perform matrix operations on returned matrices, or wish to access individual elements of the matrix, we can move the matrix stored as a returned result to a normal Stata matrix. This is done in the final line of syntax below.
matrix list e(b)
e(b)[1,3]
female read _cons
y1 5.486894 .56588693 20.228368
matrix b = e(b)
Finally, the results returned under the heading "functions" contain functions that can be used in a manner similar to other Stata functions. The most common function returned by Stata estimation commands is probably e(sample). This function marks the sample used in estimation of the last analysis, this is useful as datasets often contain missing values resulting in not all cases in the dataset being used in a given analysis. Assuming that the last estimation command run was the regression of write on female and read shown above, the first line of code below uses e(sample) to find the mean of read among those cases used in the model. The second line of code uses e(sample) to create a new variable called flag which is equal to 1 for cases that were used in the analysis, and zero otherwise. (Note since the example dataset contains no missing data, all of the cases are included in the analysis, and flag is a constant equal to one.)
sum read if e(sample)==1
Variable | Obs Mean Std. Dev. Min Max
-------------+--------------------------------------------------------
read | 200 52.23 10.25294 28 76
gen flag = e(sample)
Coefficients and their standard errors
As discussed above, after one fits a model, coefficients and their standard errors are stored in e() in matrix form. These matrices allow the user access to the coefficients, but Stata gives you an even easier way to access this information by storing it in the system variables _b and _se. To access the value of a regression coefficient after a regression, all one needs to do is type _b[varname] where varname is the name of the predictor variable whose coefficient you want to examine. To access the standard error, you can simply type _se[varname]. To access the coefficient and standard error of the constant we use _b[_cons] and _se[_cons] respectively. Below we run the same regression model we ran above (omitting the output), using female and read to predict write. Once we have estimated the model, we use the display command to show that the values in _b are equal to our regression coefficients. Finally, we calculate the predicted value of write when a female (female=1) student has a read score of 52.
regress write female read
Source | SS df MS Number of obs = 200
-------------+------------------------------ F( 2, 197) = 77.21
Model | 7856.32118 2 3928.16059 Prob > F = 0.0000
Residual | 10022.5538 197 50.8759077 R-squared = 0.4394
-------------+------------------------------ Adj R-squared = 0.4337
Total | 17878.875 199 89.843593 Root MSE = 7.1327
------------------------------------------------------------------------------
write | Coef. Std. Err. t P>|t| [95% Conf. Interval]
-------------+----------------------------------------------------------------
female | 5.486894 1.014261 5.41 0.000 3.48669 7.487098
read | .5658869 .0493849 11.46 0.000 .468496 .6632778
_cons | 20.22837 2.713756 7.45 0.000 14.87663 25.58011
------------------------------------------------------------------------------
display _b[_cons]
20.228368
display _b[female]
5.486894
display _b[read]
.56588693
display _b[_cons] + _b[female]*1 + _b[read]*52
55.141383