*! Help file version 1.5 written by Mead Over (mover@cgdev.org) 18Dec2018

Title

addest -- Add scalar, vector, matrix or text information to estimation results

Syntax

addest
[
,
name(charstring)
value(numeric value)
bvector(vector name)
vcematrix(matrix name)
rename
augbvector(number)
augvcematrix(number)
augcoefname(string)
augeqname(string)
textname(string)
textstring(string)
matname(ematrix_name)
matrix(existing_matrix)
findomitted
buildfvinfo
post
repost
*
]

Description

addest augments the capabilities of STATA's ereturn command
and of the post-estimation commands that use the estimation results
stored in ereturn by allowing the user to add items to those stored
with a set of estimation results.

Every estimation command leaves its results behind in memory.
The user can then view these saved results by typing ereturn list and
use any of the stored results in subsequent calculations
by referring specifically to any element stored in this space.
For example, the user may access the sample size of the
most recent estimation command by typing:

display e(N)

Furthermore, post-estimation commands provided by Stata or
contributed by users rely on the contents of ereturn for further analysis.
Examples include Stata's powerful margins and marginsplot commands
as well as its more prosaic estimates table command.
The estimates table command is useful for presenting the results
of several estimated models side by side. More powerful programs to display
the estimation results of several models in a similar table include
esttab, xml_tab, outreg and outreg2.

This addest command addresses the situation that arises if the user wishes
that a post-estimation command would display or manipulate
some characteristic of the original estimated model that is not part of the stored
results.

Options

name(charstring)) value(numeric value)

These two options are a pair and must be specified together.
The name option specifies the name of the scalar to be added to the ereturn space.
The charstring designating the name cannot contain spaces or special characters,
because it becomes the name of a Stata macro.
If the user specifies a name that already exists, its value is overwritten.

bvector(vector name) vceatrix(matrix name)

These two options are also a pair.
They enable a user to replace the vector of estimated coefficients and its variance-covariance matrix.
The new coefficient vector and variance-covariance matrix must have the same
numbers of rows and columns as those currently in the ereturn space.

rename

rename is allowed only with the bvector(vector name)
vceatrix(matrix name) syntax
and tells Stata to use the names obtained from the
specified b vector as the labels for both the b and V
estimation matrices. These labels are subsequently used in the output
produced by ereturn display or estimates table.

augbvector(number) augvceatrix(number) augcoefname(string) [ augeqname(string) ]

These four options are also a set. The first three should always be specified together.
The fourth, which specifies an equation name for the added coefficient estimate,
is only needed if the e(b) and e(V) results already stored in e(return) include equation names.
These options enable a user to add a single estimated coefficient to the coefficient vector, e(b),
and to add it's estimated variance to the estimated variance-covariance matrix
of coefficients, e(V).

textname(string_with_no_blanks) textstring(string_with_no_blanks)

These two options are a pair and must be specified together. They can be used to add
an arbitrary character string as a macro in the e(return) results.

matname(ematrix_name) matrix(existing_matrix)

These two options are a pair and must be specified together.
They load a previously created Stata matrix named existing_matrix
into the ereturn space as a matrix named ematrix_name.
The ematrix_name cannot contain spaces or special characters.
If the user specifies a name that already exists in the ereturn space,
its value is overwritten.

post or repost

When changing or updating estimation results in the ereturn space,
addest selects by default the repost option. When updating or adding
to other parts of the ereturn space, addest selects the post
option by default. Optionally, the user can override these defaults by explicitly
specifying post or repost.

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 passed direclty to ereturn repost.

buildfvinfo

specified with ereturn post and ereturn repost
computes the H matrix that postestimation commands
contrast,
margins, and
pwcompare use for determining estimable functions.
This option is passed directly to ereturn repost.

* (other options)

Any other options are passed through to either ereturn post or ereturn repost.

Example of the use of the name() and value() options

For this example, we use Galton's original data set on the heights of children,
which he used to show that children's hieight can be accurately, though not
exactly, predicted from the height of their parents. For purposes of this example,
the original data has been supplemented with data on the ages of the children.
(In reality Galton only used data from adult children.) The supplemented data
set is called galton.dta and can be downloaded with this program.

Suppose one estimates a model that predicts height based on
the father's height, fheight, the mother's height mheight and the child's age,
where age is only available as a set of three dummy variables defined respectively as:

Dage5 = 1 if age > 5, 0 otherwise.

Dage10 = 1 if age >10, 0 otherwise.

Dage15 = 1 if age>15, 0 otherwise.

All three dummies would be zero if the child is less than or equal to 5 years old.

First load the data in memory with the command:

use galton, clear

Then run a regression of the child's height only on the father's height and
the age dummies with the regression command:

regress height fheight Dage5 Dage10 Dage15

One might want to test the hypothesis that age is statistically significant with an F-test
computed by the command:

test Dage5 Dage10 Dage15

It would be convenient if a command that displays the results of a regression in tabular form
like estimates table, outreg or xml_tab, would display the results of
this F-test in the appropriate column. From a Stata do file one cannot add to
the contents of the ereturn macros.

Using addest, the solution to this problem is as follows:

regress height fheight Dage5 Dage10 Dage15
test Dage5 Dage10 Dage15
addest, name("F_of_age") value(`r(F)')
addest, name("p_of_age") value(`r(p)')
est store onlyfather

regress height mheight Dage5 Dage10 Dage15
test Dage5 Dage10 Dage15
addest, name("F_of_age") value(`r(F)')
addest, name("p_of_age") value(`r(p)')
est store onlymother

regress height fheight mheight Dage5 Dage10 Dage15
test Dage5 Dage10 Dage15
addest, name("F_of_age") value(`r(F)')
addest, name("p_of_age") value(`r(p)')
test fheight=mheight
addest, name("F_of_M_eq_F") value(`r(F)')
addest, name("p_of_M_eq_F") value(`r(p)')
est store both
.
.	<other code>
.
est table onlyfather onlymother both, stat("F_of_age" "p_of_age" "F_of_M_eq_F" "p_of_M_eq_F" F N r2)

The output of the above estimates table command is:

-----------------------------------------------------
Variable | onlyfather onlymother both
-------------+---------------------------------------
fheight | .39378776 .37366497
Dage5 | 2.5092039 2.8483203 2.5705705
Dage10 | 2.1560442 2.0992155 2.1577627
Dage15 | 1.5592282 1.6260293 1.5430182
mheight | .31865049 .28892303
_cons | 35.971966 42.515225 18.790657
-------------+---------------------------------------
F_of_age | 55.871601 55.114653 58.924464
p_of_age | 4.201e-33 1.088e-32 9.309e-35
F_of_M_eq_F | 1.7621445
p_of_M_eq_F | .18469688
F | 63.657074 52.551367 61.476023
N | 898 898 898
r2 | .22187349 .19054063 .25628248
-----------------------------------------------------

The user-written table-making commands esttab, outreg and xml_tab
can also now access and display these new statistics.

Example of the use of the options to augment e(b) and e(V)

---- To be added ----

Author

Mead Over,
Center for Global Development, Washington, DC 20036 USA.
Email: MOver@CGDev.Org if you observe any problems.