help for parmest and parmby(Roger Newson)

Convert estimation results to a dataset with one observation per parameter

The parmest package includes 4 modules,
which produce datasets with one observation for each of a set of estimated parameters,
and variables containing estimates, confidence limits, P-values and other parameter attributes.
The modules are as follows:

Module Description

parmest Create dataset from most recent estimation results

parmby Create dataset by calling an estimation command once for each by-group

parmcip Confidence limits and P-values from estimates and standard errors

metaparm Confidence limits and P-values for linear combinations of independent parameters
(as in a meta-analysis)

The modules parmest and parmby are documented here.
See parmcip and metaparm for the other modules.

Syntax for parmest and parmby

parmest , [ parmest_outdest_opts
parmest_ci_opts
parmest_varadd_opts
parmest_varmod_opts
]

parmby [`]"command"['] , [ parmest_opts
parmby_only_opts
]

where parmest_opts are options allowed by parmest and command is a Stata estimation command.

Description

parmest takes, as input, the most recently calculated set of estimation results,
created by the most recently executed estimation command.
It creates, as output, a new dataset, with one observation per estimated parameter, and variables
containing parameter names, estimates, standard errors, z-test or t-test statistics,
P-values, confidence limits, and other estimation results if requested by the user.
parmby executes an estimation command for each by-group specified by the by-variables,
and then creates an output dataset with one observation for each estimated parameter
in each by-group for which the command executed successfully, and all the variables in the parmest
output dataset, together with the by-variables.
The output dataset created by parmby or parmest
may be listed to the Stata log, or saved to a new data frame,
or saved to a disk file, or written to the current data frame
(overwriting any pre-existing dataset).

Output datasets created by parmest and parmby

These output datasets (or resultssets) are described in detail in parmest_resultssets.

Options for use with parmest and parmby

parmest and parmby have a large number of options, which fall into the following 5 groups:

Option group Description

parmest_outdest_opts Output-destination options for parmest and parmby

parmest_ci_opts Confidence-interval options for parmest and parmby

parmest_varadd_opts Variable-adding options for parmest and parmby

parmest_varmod_opts Variable-modifying options for parmest and parmby

parmby_only_opts Options for parmby only

Output-destination options for parmest and parmby

list(list_spec) List output dataset to Stata log and/or Results window

frame(framename[,replace change]) Save output dataset to a data frame

saving(filename[,replace]) Save output dataset to a disk file

norestore Write output dataset to memory

fast Write output dataset to memory without precautions

flist(global_macro_name) Append output filename to a global macro

where list_spec is a specification of the form

[varlist] [if] [in] [ , [list_options ] ]

and list_options is a list of options used by the list command.

See parmest_outdest_opts for details of these options.

Confidence-interval options for parmest and parmby

eform Exponentiate estimates and confidence limits

dof(numscalar) Scalar degrees of freedom for calculating confidence limits

level(numlist) Confidence level(s) for calculating confidence limits

clnumber(numbering_rule) Numbering rule for naming confidence limit variables

mcompare(method) Multiple-comparison method

mcomci(method) Multiple-comparison method for confidence limits only

bmatrix(matrix_expression) Matrix from which parameter estimates will be extracted

vmatrix(matrix_expression) Matrix from which parameter variances will be extracted

dfmatrix(matrix_expression) Matrix from which parameter degrees of freedom will be extracted

where numscalar is

# | scalar_name

and numbering_rule is

level | rank

and method is

noadjust | bonferroni | sidak

See parmest_ci_opts for details of these options.

Variable-adding options for parmest and parmby

msetype Variable containing parameter matrix stripe element type

omit Variable containing parameter omit status

empty Variable containing parameter empty cell status

label Variable containing X-variable labels

ylabel Variable containing Y-variable labels

idnum(#) Numeric dataset ID variable

idstr(string) String dataset ID variable

plower Variable containing lower one-tailed P-values

pupper Variable containing upper one-tailed P-values

stars(numlist) Variable containing stars for the P-value

emac(name_list) Variables containing macro estimation results

escal(name_list) Variables containing scalar estimation results

erows(name_list) Variables containing rows of matrix estimation results

ecols(name_list) Variables containing columns of matrix estimation results

evec(name_list) Variables containing vectors extracted from matrix estimation results

where name_list is a list of names of Stata estimation results.

See parmest_varadd_opts for details of these options.

Variable-modifying options for parmest and parmby

rename(renaming_list) Rename variables in the output dataset

format(formatting_list) Display formats for variables in the output dataset

float Set storage type of numeric variables to float or lower precision

nodouble Alternative option for specifying float

nozerop Reset zero P-values to smallest positive double-precision number

nullvalue(#) Value of estimated parameters under null hypotheses

where renaming_list is a list of variable names of form

oldvarname_1 newvarname_1 ... oldvarname_n newvarname_n

and formatting_list is a list of form

varlist_1 format_1 ... varlist_n format_n

See parmest_varmod_opts for details of these options.

Options for parmby only

by(varlist) Specify variables defining by-groups

command Add a variable containing the command called

See parmby_only_opts for details of these options.

Remarks

More information about the use of parmest and parmby
can be found in Newson (2010), Newson (2008), Newson (2006), Newson (2004), Newson (2003) and Newson (2002).
parmby is similar to statsby, but it creates a data
set with one observation per parameter per by-group, instead of a dataset with one
observation per by-group.
Also, in default, parmby outputs the estimation output
to the log, although the user can use quietly to suppress this.
parmby is a "quasi-byable" front end for parmest.
parmest is frequently used when the user wishes simply to use the list() option to list the estimation
output with user-specified formats or parameter labels, so that the results for each parameter are presented
to a number of decimal places and/or significant figures specified by the user, and may also be labelled
with the variable label, corresponding to the parameter.
The parmest command is therefore
used as an alternative version of estimates table,
with the added power to calculate confidence limits.
With either parmby or parmest,
the user must specify at least one of the four output-destination options
list(), saving(), norestore and/or fast.
These options specify whether the output dataset is listed to the Stata log, saved to a disk file,
or written to the memory (overwriting any pre-existing dataset).
parmby works by calling parmest, which in turn works by calling parmcip.

Examples

The following examples use the list() option to list a subset of the output dataset to the Stata log.
After these examples are executed, there is no new dataset either in the memory or on disk.

. regr price mpg weight,robust

. parmest,format(estimate min95 max95 %8.2f p %8.1e) list(,)

. glm mpg foreign,family(gamma) link(power -1)

. parmest, label format(estimate min95 max95 p %8.2f p %8.1e) list(parm label estimate min95 max95 p,clean noobs)

. regress price mpg weight foreign displacement headroom,robust

. parmest,label format(p %8.1e) stars(0.05 0.01 0.001 0.0001) list(parm label estimate min95 max95 p stars,clean noobs)

. parmby "qui logit foreign mpg, or", label eform for(estimate min95 max95 %8.2f p %8.1e) li(parm label estimate min95 max95 p)

. parmby "qui logit foreign mpg, or", level(95 97.5) cln(rank) label eform for(estimate min* max* %8.2f p %8.1e) li(parm label estimate min2 min1 max1 max2 p,clean noobs)

. parmby "regress weight i.foreign#i.rep78", omit empty list(if !empty, abbr(32))

The following examples use the norestore option to create an output dataset in the memory,
overwriting any pre-existing dataset.

. parmby "regr mpg weight,robust",by(foreign) label command norestore

. gene gpm=1/mpg

. rename foreign t

. parmby "regr gpm weight",by(t) label rename(t tstat p pvalue) norestore

. gene byte pw1=1

. svyset [pwei=pw1],clear

. parmby "svy :mean mpg weight price, over(foreign)", norestore ylabel ev(_N _N_subp) es(N)

. describe

. list ylabel parm ev_* es_* estimate min95 max95

The following examples use the saving() option to create an output dataset in a disk file.

. parmby "logit foreign mpg, or", label eform saving(parms1.dta)

. parmby "regr mpg weight displ,robust",by(foreign) label saving(myparms,replace)

The following example demonstrates the use of parmby with multiple regression commands,
saving the results in multiple temporary datasets. These datasets are then concatenated,
using append, to form a single dataset in memory, with one observation
for each parameter in each regression.
This example uses the options idnum()
and idstr() to create analysis identifier variables, which contain information identifying
the regression model for each parameter.

. gene gpm=1/mpg

. tempfile tf1 tf2 tf3

. parmby "regr gpm weight", lab saving(`"`tf1'"',replace) idn(1) ids(Unadjusted)

. parmby "regr gpm foreign", lab saving(`"`tf2'"',replace) idn(2) ids(Unadjusted)

. parmby "regr gpm weight foreign", lab saving(`"`tf3'"',replace) idn(3) ids(Adjusted)

. drop _all

. append using `"`tf1'"' `"`tf2'"' `"`tf3'"'

. list idnum idstr parm estimate min95 max95 p,noobs nodis

The following advanced example demonstrates the use of the flist() option with append.
parmby is used to carry out multiple regression analyses,
storing the results in temporary files, whose names are stored by the flist() option in a
global macro tflist.
The files are then concatenated using append to create a single
long dataset in memory, with one observation for each parameter of each regression model.
For each parameter, the regression model for that parameter is identified by the string variable
command and the numeric analysis identifier variable idnum. The dataset is
sorted, described and listed.

. global tflist ""

. global modseq=0

. foreach X of var headroom trunk weight length turn displacement gear_ratio {

. global modseq=$modseq+1

. tempfile tfcur

. parmby "regr mpg `X'",by(foreign) label command format(estimate min95 max95 %8.2f p %8.1e) idn($modseq) saving(`"`tfcur'"',replace) flist(tflist)

. }

. drop _all

. append using $tflist

. sort idnum command foreign parmseq

. describe

. by idnum command:list foreign parm label estimate min95 max95 p,noobs

The following advanced example demonstrates the use of parmest
with the mi estimate command prefix.
The example is based on an example from the manual entry [MI] mi estimate,
using the Albuquerque Home Prices dataset.
Note that, if the estimation command is mi estimate,
then, by default,
parmest extracts the untransformed parameter estimates, variances and degrees of freedom
from the matrix estimation results e(b_mi), e(V_mi) and e(df_mi),
respectively.
To extract the transformed parameter estimates, variances and degrees of freedom,
we must specify other matrix estimation results,
using the bmatrix(), vmatrix() and dfmatrix() options, respectively.
We can then concatenate the two sets of parameters into a single output dataset,
using append.

. use http://www.stata-press.com/data/r11/mhouses1993s30, clear

. describe

. mi estimate (ratio: _b[age]/_b[sqft]): regress price tax sqft age nfeatures ne custom corner

. parmest, norestore

. tempfile tf1

. parmest, bmat(e(b_Q_mi)) vmat(e(V_Q_mi)) dfmat(e(df_Q_mi)) saving(`"`tf1'"', replace)

. append using `"`tf1'"', gene(parmtype)

. lab def parmtype 0 "Original" 1 "Transformed"

. lab val parmtype parmtype

. lab var parmtype "Parameter type"

. describe

. list, sepby(parmtype)

More examples can be found in Newson (2010), Newson (2008), Newson (2006), Newson (2004), Newson (2003) and Newson (2002).

Saved results

parmest saves the following in r():

Scalars

r(dofpres) 1 if t-distribution used, 0 otherwise

r(dof) scalar degrees of freedom used

r(nparm) number of parameters

r(nullvalue) value of parameters under null hypotheses

Macros

r(level) confidence level(s)

r(eform) eform if specified

r(bmatrix) bmatrix() expression used

r(vmatrix) vmatrix() expression used

r(dfmatrix) dfmatrix() expression used

Note that r(dof) is set to zero if the standard Normal distribution was used,
set to a missing value if the degrees of freedom used vary between parameters,
and set to a common value if the degrees of freedom used are the same for all parameters.
Note also that r(dfmatrix) is always missing if the user sets the dof() option,
because any dfmatrix() option set by the user is then ignored.

parmby saves the above items in r()
from the last execution of parmest for the last by-group,
and also the following:

Macros

r(command) estimation command

r(by) list of by-variables

Acknowledgments

I would like to thank Nicholas J. Cox of Durham University, UK,
for coining the word resultsset to describe an output dataset created by a Stata program such as parmest.
I would also like to thank Jeremy Freese of Stanford University, CA, USA
for writing the SSC package frameappend,
from which I have modified some code for use in parmby for appending frames.

Author

Roger Newson, King's College London, UK.
Email: roger.newson@kcl.ac.uk

References

Newson, R. B. 2010. Post-parmest peripherals: fvregen, invcise, and qqvalue.
Presented at the 16th United Kingdom Stata Users' Group Meeting, London, 9-10 September, 2010.

Newson, R. B. 2008. parmest and extensions.
Presented at the 14th United Kingdom Stata Users' Group Meeting, London, 8-9 September, 2008.

Newson, R. 2006. Resultssets, resultsspreadsheets, and resultsplots in Stata.
Presented at the 4th German Stata Users' Group Meeting, Mannheim, 31 March, 2006.

Newson, R. 2004. From datasets to resultssets in Stata.
Presented at the 10th United Kingdom Stata Users' Group Meeting, London, 29-30 June, 2004.

Newson, R. 2003. Confidence intervals and p-values for delivery to the end user.
The Stata Journal 3(3): 245-269.
Download from
the Stata Journal website.

Newson, R. 2002. Creating plots and tables of estimation results using parmest and friends.
Presented at the 8th United Kingdom Stata Users' Group Meeting, 20-21 May, 2002.

Also see

Manual: ,

,

[I] estimation commands,

[D] append, [D] statsby, [R] estimates table

Help: [U] 20 Estimation and postestimation commands,

[I] estimation commands,

[D] append, [D] statsby, [R] estimates table

parmcip, metaparm,
parmest_outdest_opts, parmest_ci_opts,
parmest_varadd_opts, parmest_varmod_opts,
parmby_only_opts, parmest_resultssets

lincomest, frameappend if installed