Stata 15 help for ereturn

[P] ereturn -- Post the estimation results

Syntax

Set macro returned by estimation command

ereturn local name ... (see [P] macro)

Set scalar returned by estimation command

ereturn scalar name = exp

Set matrix returned by estimation command

ereturn matrix name [=] matname [, copy]

Clear e() stored results

ereturn clear

List e() stored results

ereturn list [, all]

Store coefficient vector and variance-covariance matrix into e()

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

Change coefficient vector and variance-covariance matrix

ereturn repost [b = b] [V = V] [Cns = Cns] [weight] [, esample( varname) properties(string) buildfvinfo findomitted rename resize]

Display coefficient table

ereturn display [, eform(string) first neq(#) plus level(#) display_options]

where name is the name of the macro, scalar, or matrix that will be returned in e(name) by the estimation program; matname is the name of an existing matrix; b is a 1 x p coefficient vector (matrix); V is a p x p covariance matrix; and Cns is a c x (p+1) constraint matrix.

fweights, aweights, iweights, and pweights are allowed; see weight.

Description

ereturn local, ereturn scalar, and ereturn matrix set e() macros, scalars, and matrices other than b, V, and Cns returned by estimation commands. See [P] return for more discussion on returning results.

ereturn clear clears the e() stored results.

ereturn list lists the names and values of the macros and scalars stored in e(), and the names and sizes of the matrices stored in e() by the last estimation command.

ereturn post clears all existing e-class results and stores the coefficient vector (b), variance-covariance matrix (V), and constraint matrix (Cns) in Stata's system areas, making available all the postestimation features described in postest. b, V, and Cns are optional for ereturn post; some commands (such as factor) do not have a b, V, or Cns but do set the estimation sample, e(sample), and properties, e(properties). You must use ereturn post before setting other e() macros, scalars, and matrices.

ereturn repost changes the b, V, or Cns matrix (allowed only after estimation commands that posted their results with ereturn post) or changes the declared estimation sample or e(properties). The specified matrices cease to exist after post or repost; they are moved into Stata's system areas. The resulting b, V, and Cns matrices in Stata's system areas can be retrieved by reference to e(b), e(V), and e(Cns). ereturn post and repost deal with only the coefficient and variance-covariance matrices, whereas ereturn matrix is used to store other matrices associated with the estimation command.

ereturn display displays or redisplays the coefficient table corresponding to results that have been previously posted using ereturn post or repost.

For a discussion of posting results with constraint matrices (Cns in the syntax diagram above), see [P] makecns, but only after reading this entry.

Options

copy specified with ereturn matrix indicates that the matrix is to be copied; that is, the original matrix should be left in place.

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.

depname(string) specified with ereturn post supplies a name that should be that of the dependent variable but can be anything; that name is stored and added to the appropriate place on the output whenever ereturn display is executed.

obs(#) specified with ereturn post supplies the number of observations on which the estimation was performed; that number is stored in e(N).

dof(#) specified with ereturn post supplies the number of (denominator) degrees of freedom that is to be used with t and F statistics and is stored in e(df_r). This number is used in calculating significance levels and confidence intervals by ereturn display and by subsequent test commands performed on the posted results. If the option is not specified, normal (Z) and chi-squared statistics are used.

esample(varname) specified with ereturn post or ereturn repost gives the name of the 0/1 variable indicating the observations involved in the estimation. The variable is removed from the dataset but is available for use as e(sample); see [U] 20.7 Specifying the estimation subsample. If the esample() option is not specified with ereturn post, it is set to all zeros (meaning no estimation sample). See [P] mark for details of the marksample command that can help create varname.

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.

buildfvinfo specified with ereturn post and ereturn repost computes the H matrix that postestimation commands contrast, margins, and pwcompare use for determining estimable functions.

findomitted specified with ereturn post and ereturn repost adds the omit operator o. to variables in the column names corresponding to zero-valued diagonal elements of e(V). This option is generally unnecessary but is useful when _rmcoll is not used before estimation.

rename is allowed only with the b = b syntax of ereturn repost and tells Stata to use the names obtained from the specified b matrix as the labels for both the b and V estimation matrices. These labels are subsequently used in the output produced by ereturn display.

resize is allowed only with ereturn repost and tells Stata that the replacements b, V, and Cns have a different number of elements than the originals. This option implies rename.

eform(string) specified with ereturn display indicates that the exponentiated form of the coefficients is to be output and reporting of the constant is to be suppressed. string is used to label the exponentiated coefficients; see [R] eform_option.

first requests that Stata display only the first equation and make it appear as if only one equation were estimated.

neq(#) requests that Stata display only the first # equations and make it appear as if only # equations were estimated.

plus changes the bottom separation line produced by ereturn display to have a + symbol at the position of the dividing line between variable names and results. This is useful if you plan on adding more output to the table.

level(#), an option of ereturn display, specifies the confidence level, as a percentage, of confidence intervals for the estimated parameters; see [R] level.

display_options: noci, nopvalues, noomitted, vsquish, noemptycells, baselevels, allbaselevels, nofvlabel, fvwrap(#), fvwrapon(style), cformat(%fmt), pformat(%fmt), sformat(%fmt), and nolstretch; see [R] estimation options.

Examples

See [P] ereturn for the general outline of an estimation command program and for examples of ereturn post, repost, and display. Within such a program you could store e() results using something like

... ereturn local depvar "`depname'" ereturn scalar N = `nobs' ereturn matrix lambda lam ereturn local cmd "myestcmd" ...

The user of an estimation command would type

. ereturn list

to see what was returned from an estimation command.

--------------------------------------------------------------------------- Setup . sysuse auto . regress weight length displ

List stored results . ereturn list

Access individual e() results . display "the adjusted R-squared is: `e(r2_a)' . display "the residual sum-of-squares is: `e(r22)' . matrix list e(V) . matrix list e(b) ---------------------------------------------------------------------------

Stored results

ereturn post stores the following in e():

Scalars e(N) number of observations e(df_r) degrees of freedom, if specified

Macros e(wtype) weight type e(wexp) weight expression e(properties) estimation properties; typically b V

Matrices e(b) coefficient vector e(Cns) constraints matrix e(V) variance-covariance matrix of the estimators

Functions e(sample) marks estimation sample

ereturn repost stores the following in e():

Macros e(wtype) weight type e(wexp) weight expression e(properties) estimation properties; typically b V

Matrices e(b) coefficient vector e(Cns) constraints matrix e(V) variance-covariance matrix of the estimators

Functions e(sample) marks estimation sample

With ereturn post, all previously stored estimation results -- e() items -- are removed. ereturn repost, however, does not remove previously stored estimation results. ereturn clear removes the current e() results.

ereturn display stores the following in r():

Scalars r(level) confidence level of confidence intervals

Macros r(label#) label on the #th coefficient, such as (base), (omitted), (empty), or (constrained) r(table) information from the coefficient table (see below)

r(table) contains the following information for each coefficient:

b coefficient value se standard error t/z test statistic for coefficient pvalue observed significance level for t/z ll lower limit of confidence interval ul upper limit of confidence interval df degrees of freedom associated with coefficient crit critical value associated with t/z eform indicator for exponentiated coefficients


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