**[P] return** -- Return stored results

__Syntax__

Return results for general commands, stored in r()

__ret__**urn** __li__**st** [**,** **all**]

__ret__**urn** **clear**

__ret__**urn** __sca__**lar** *name* **=** *exp*

__ret__**urn** __loc__**al** *name* **=** *exp*

__ret__**urn** __loc__**al** *name* [**"**]*string*[**"**]

__ret__**urn** __mat__**rix** *name* [**=**] *matname* [**,** **copy**]

__ret__**urn** **add**

Return results for estimation commands, stored in e()

__eret__**urn** __li__**st** [**,** **all**]

__eret__**urn** **clear**

__eret__**urn** **post** [*b* [*V* [*Cns*]]] [*weight*] [**,** __dep__**name(***string***)** __o__**bs(***#***)** __d__**of(***#***)**
__e__**sample(***varname***)** __prop__**erties(***string***)**]

__eret__**urn** __sca__**lar** *name* **=** *exp*

__eret__**urn** __loc__**al** *name* **=** *exp*

__eret__**urn** __loc__**al** *name* [**"**]*string*[**"**]

__eret__**urn** __mat__**rix** *name* [**=**] *matname* [**,** **copy**]

__eret__**urn** **repost** [**b =** *b*] [**V =** *V*] [**Cns =** *Cns*] [*weight*] [**,** __e__**sample(**
*varname***)** __prop__**erties(***string***)** __ren__**ame**]

Return results for parsing commands, stored in s()

__sret__**urn** __li__**st**

__sret__**urn** **clear**

__sret__**urn** __loc__**al** *name* **=** *exp*

__sret__**urn** __loc__**al** *name* [**"**]*string*[**"**]

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

**fweight**s, **aweight**s, **iweight**s, and **pweight**s are allowed; see weight.

__Description__

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

__Options__

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

__Remarks__

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.

__Examples__

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