|
Title
[P] return -- Return stored results
Syntax
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.
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.
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.
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 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 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.
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
| 
发帖
雷达卡
京公网安备 11010802022788号
