Stata 15 help for return

[P] return -- Return stored results


Return results for general commands, stored in r()

return list [, all]

return clear

return scalar name = exp

return local name = exp

return local name ["]string["]

return matrix name [=] matname [, copy]

return add

Return results for estimation commands, stored in e()

ereturn list [, all]

ereturn clear

ereturn post [b [V [Cns]]] [weight] [, depname(string) obs(#) dof(#) esample(varname) properties(string)]

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 list

sreturn clear

sreturn local name = exp

sreturn local name ["]string["]

where b, V, and Cns are matnames, which is the name of an existing matrix.

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 results.


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 examples.

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 return command:

program mysum, rclass syntax varname return local varname `varlist' tempvar new quietly { 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) } end

You can run this program and then list the returned results:

. sysuse auto . mysum mpg . return list

scalars: r(mean) = 21.2972972972973 r(sum) = 1576 r(N) = 74

macros: r(varname) : "mpg"

The values r(mean), r(sum), r(N), and r(varname) can now be referred to directly.

. display "The variable is " r(varname) " with mean " r(mean) The variable is mpg with mean 21.297297

© Copyright 1996–2018 StataCorp LLC   |   Terms of use   |   Privacy   |   Contact us   |   What's new   |   Site index