Using the Return List in Stata

Whether you are programming or trying to retrieve values calculated in Stata, your best bet is probably to use the return list command in Stata. For many of Stata's commands (particularly statistical ones), statistics generated or other data are saved in scalars, matrices, or macros. You may want access to this data for a variety of reasons:

• To return more precise statistics, because Stata sometimes truncates values in output, but not in return values.
• To reorganize data output to make it easier to read, copy, or interpret.
• To build programs in Stata.

Example 1: Basic Usage
Lets use return list on a value we have generated. Type the following commands into stata:

1. 1
2. 2
3. 3
4. 4

sysuse citytemp4.dta
tab division
return list
di `r(N)'

You should see the following output:

The scalar r(N) is returned and displayed using di r(N).

A scalar is a variable that can contain either a value or text. The return list indicates that two scalars are available for our use: r(N), which is the total, and r(r), the number of geographic regions.

We can display these values by typing display and surrounding them with a forward and backward quote. That is, a ` and '. The ` is shared with the tilde(~) key while the ' is a single quote. It seems strange to me (I really wish Stata devised a simpler syntax, but I don't think they are planning on changing it anytime soon).

Example 2: Creating your own Table
Sometimes you may want to construct your own table. For instance, in cases where you use summarize on a large number of subsets of your data and want to retrieve a desired stastic from each. This can be a tedious, error-prone process. The solution is to construct your own table using macros and loops. This will make the process quicker and more accurate.

1. 1
2. 2
3. 3
4. 4
5. 5
6. 6
7. 7
8. 8
9. 9
10. 10
11. 11
12. 12

forvalues num = 1/9 {
noisily summarize heatdd if division == `num'
local mean`num' `r(mean)'
}

noisily display _column(1) "Division" _column(20) "Mean"

forvalues num = 1/9 {
local div_label : label(division)`num'
noisily display _column(1) "`div_label'" _column(20) string(round(`mean`num'',0.001))
}

This above code is a do file which uses citytemp4.dta to produce a table of the mean of heatdd by regions coded in the division variable. To load this, type sysuse citytemp4.dta. Copy and paste the above code into a do file and try running it. The output will look as follows:

The outputted table

This table can be copied and pasted into Excel where it can be easily manipulated further. How does it work?

There are two loops in the do file which are designated using forvalues. We loop through the values 1-9 because there are 9 geographic regions coded in the variable division. division is a numeric variable which is coded using labels:  N. Eng = 1; Mid Atl = 2; E.N.C. = 3, etc.)

The First Loop

1. 1
2. 2
3. 3
4. 4

forvalues num = 1/9 {
noisily summarize heatdd if division == `num'
local mean`num' `r(mean)'
}

In the first loop, we summarize the data by each geographic area coded in division (line 2) and save it using macros. Note that I took advantage of the value the loop is on in my command by specifying it. I used the name num, and its specified within the loop as `num'. This is how we specify which geographic region coded in division to be summarized in fact. See how we restrict the summarize command with if division == `num'?

In line 3 we create macros. Again, `num' will be replaced by the number the loop is currenty on (1-9). This will cause 9 macros to be created: mean1, mean2, mean3, ... , mean9. Each macro will contain the mean returned from summarize.

Line 4 closes the loop.

1. 6

noisily display _column(1) "Division" _column(20) "Mean"

Line 6 prints a table heading. We specify noisily to force output of this display command because its being run within a do-file. The _column(#) tells display where to start the text that follows. This is important in lining up output.

The Second Loop

1. 8
2. 9
3. 10
4. 11
5. 12

forvalues num = 1/9 {
local div_label : label(division)`num'
noisily display _column(1) "`div_label'" _column(20) string(round(`mean`num'',0.001))
}

The second loop is run the same as the first (line 1 = line 8). Its purpose is to print out a table of geographic regions and their associated means under the heatdd variable using the values saved in the first loop . line 9 defines a macro within our loop called div_label. This macro utilizes an extended function which will grab the label for a corresponding value. The colon following div_label signals that we are using an extended function. The usage of this extended function is to type label(variable name)#, where variable name is the variable you want to get a label from and number is the corresponding value that codes for that label.

Each time the loop occurs, div_label is replaced by the label corresponding to the value of the loop we are on. Then it is printed in line 10 and the process occurs again.

line 10 gives us what we were always after. It prints the geographic region coded under division and its corresponding heatdd mean. string(round(`mean`num'',0.001)) is a lot to digest. It is a series of nested functions. They are performed from the inside to the outside. The following list should clear things up. Each line shows what the computer does, successively on loop 3.

string(	round(	`mean	`num'	'	,0.001)	)	The computer starts with the most 'nested' thing, in this case `num'.
string(	round(	`mean	3'	'	,0.001)	)	The computer starts in the middle, figuring out the value of the loop we are on.
string(	round(	6353.	72815533980		,0.001)	)	The value of mean3 is retreived.
string(		6353.	728			)	This value is rounded to the nearest 0.001
		"6353.	728"				The value is converted to a string so it can be outputted. This is the end result.

Hopefully your off to a good start building output in this custom manner and saving considerable time doing so!

See Also

• How Can I access information stored after I run a command in Stata (returned results)?