help ereturn, help return, help sreturn dialog: return/ereturn list
-------------------------------------------------------------------------------
Title
[P] return -- Return saved results
[R] saved results -- Saved results
Syntax
Return results stored in r()
return list
return clear
return scalar name = exp
return local name = exp
return local name ["]string["]
return matrix name [=] matname [, copy]
return add
Return results stored in e() (also see [P] ereturn)
ereturn list
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) rename properties(string)]
Return results 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.
Description
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 save 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 save 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 saves
macros in s().
n-class: commands that do not save results at all or, more correctly, do
not save "extra" results because where they save what they save
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.
Options
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 to 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 significance levels and confidence
intervals. The number specified is saved 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.
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 `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
Also see
Manual: [P] return, [R] saved results
Help: [P] _return, [P] ereturn; [P] program; [P] creturn
