[P] return -- Return stored results
Return results for general commands, stored in r()
return list [, all]
return scalar name = exp
return local name = exp
return local name ["]string["]
return matrix name [=] matname [, copy]
Return results for estimation commands, stored in e()
ereturn list [, all]
ereturn post [b [V [Cns]]] [weight] [, depname(string) obs(#) dof(#)
ereturn scalar name = exp
ereturn local name = exp
ereturn local name ["]string["]
ereturn matrix name [=] matname [, copy]
ereturn repost [b = b] [V = V] [Cns = Cns] [weight] [, esample(
varname) properties(string) rename]
Return results for parsing commands, stored in s()
sreturn local name = exp
sreturn local name ["]string["]
where b, V, and Cns are matnames, which is the name of an existing
fweights, aweights, iweights, and pweights are allowed; see weight.
Results of calculations are stored by many Stata commands so that they
can be easily accessed and substituted into subsequent commands. This
entry summarizes for programmers how to store results. If your interest
is in using previously stored results, see [R] stored results.
return stores results in r().
ereturn stores results in e().
sreturn stores results in s().
Stata also has the values of system parameters and certain constants such
as pi stored in c(). Because these values may be referred to but not
assigned, the c-class is discussed in a different entry; see [P] creturn.
all is for use with return list or ereturn list. all specifies that
hidden and historical stored results be listed along with the usual
stored results. This option is seldom used. See Using hidden and
historical stored results and Programming hidden and historical
stored results under Remarks and examples of [P] return for more
information. These sections are written in terms of return list, but
everything said there applies equally to ereturn list.
all is not allowed with sreturn list because s() does not allow
hidden or historical results.
copy specified with return matrix or ereturn matrix indicates that the
matrix is to be copied; that is, the original matrix should be left
in place. The default is to "steal" or "rename" the existing matrix,
which is fast and conserves memory.
depname(string) is for use with ereturn post. It supplies the name of
the dependent variable to appear in the estimation output. The name
specified need not be the name of an existing variable.
obs(#) is for use with ereturn post. It specifies the number of
observations on which the estimation was performed. This number is
stored in e(N), and obs() is provided simply for convenience.
Results are no different from those for ereturn post followed by
ereturn scalar N = #.
dof(#) is for use with ereturn post. It specifies the number of
denominator degrees of freedom to be used with t and F statistics and
so is used in calculating p-values levels and confidence intervals.
The number specified is stored in e(df_r), and dof() is provided
simply for convenience. Results are no different from those for
ereturn post followed by ereturn scalar df_r = #.
esample(varname) is for use with ereturn post and ereturn repost. It
specifies the name of a 0/1 variable that is to become the e(sample)
function. varname must contain 0 and 1 values only, with 1
indicating that the observation is in the estimation subsample.
ereturn post and ereturn repost will be able to execute a little more
quickly if varname is stored as a byte variable.
varname is dropped from the dataset, or more correctly, it is stolen
and stashed in a secret place.
properties(string) specified with ereturn post or ereturn repost sets the
e(properties) macro. By default, e(properties) is set to b V if
properties() is not specified.
rename is for use with the b = b syntax of ereturn repost. All numeric
estimation results remain unchanged, but the labels of b are
substituted for the variable and equation names of the already posted
Stata commands -- and new commands that you and others write -- can be
classified as follows:
r-class: general commands such as summarize. Results are returned in
r() and generally must be used before executing more commands.
return list lists results stored in r(). return local, return
scalar, and return matrix store macros, scalars, and matrices
in return(). return add adds the current r() values to
return(). return clear clears return(). return() is local to
the program. At the end of an r-class program, items in
return() are placed in r() for final return.
e-class: estimation commands such as regress, logistic, etc., that fit
statistical models. Such estimation results stay around until
the next model is fit. Results are returned in e().
ereturn list lists results stored in e(). ereturn local,
ereturn scalar, and ereturn matrix store macros, scalars, and
matrices in e(). See [P] ereturn for more details and
information on the other subcommands.
s-class: programming commands that assist in parsing. These commands
are relatively rare. Results are returned in s().
sreturn list lists results stored in s(). sreturn local stores
macros in s().
n-class: commands that do not store results at all or, more correctly,
do not store "extra" results because where they store what they
store is explicitly specified. generate and replace are
There is also a c-class, c(), containing the values of system parameters
and settings, along with certain constants, such as the value of pi; see
[P] creturn. A program cannot be c-class.
The following r-class command demonstrates returning results via the
program mysum, rclass
return local varname `varlist'
count if !missing(`varlist')
return scalar N = r(N)
gen double `new' = sum(`varlist')
return scalar sum = `new'[_N]
return scalar mean = return(sum)/return(N)
You can run this program and then list the returned results:
. sysuse auto
. mysum mpg
. return list
r(mean) = 21.2972972972973
r(sum) = 1576
r(N) = 74
r(varname) : "mpg"
The values r(mean), r(sum), r(N), and r(varname) can now be referred to
. display "The variable is " r(varname) " with mean " r(mean)
The variable is mpg with mean 21.297297