-------------------------------------------------------------------------------
help for parmest and parmby        (STB-49: dm65; STB-58: dm65.1; 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 disk file, or written to the memory (overwriting any pre-existing dataset).

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

options Description ------------------------------------------------------------------------- list(list_spec) List output dataset to Stata log and/or Results window 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

options Description ------------------------------------------------------------------------- eform Exponentiate estimates and confidence limits dof(#) 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 -------------------------------------------------------------------------

where numbering_rule is

level | rank

See parmest_ci_opts for details of these options.

Variable-adding options for parmest and parmby

options Description ------------------------------------------------------------------------- label Variable containing X-variable labels ylabel Variable containing Y-variable labels idnum(#) Numeric dataset ID variable idstr(string) String dataset ID variable 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

options Description ------------------------------------------------------------------------- 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 -------------------------------------------------------------------------

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

options Description ------------------------------------------------------------------------- by(varlist) Specify variables defining by-groups command Add a variable containing the command called -------------------------------------------------------------------------

See parmby_only_opts for details of these options.

Output datasets created by parmest and parmby

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

Remarks

More information about the use of parmest and parmby can be found in 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, and is the command usually used in any new programs for creating output datasets on disk or in memory. parmest is an older command, and is now mainly 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)

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 eq 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 the dsconcat command, to form a single dataset in memory, with one observation for each parameter in each regression. The dsconcat command can be downloaded from SSC using the ssc command in Stata. 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) . dsconcat `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 the dsconcat command (downloadable from SSC). 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 dsconcat 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 tf$modseq . parmby "regr mpg `X'",by(foreign) label command format(estimate min95 max95 %8.2f p %8.1e) idn($modseq) saving(`tf$modseq',replace) flist(tflist) . } . dsconcat $tflist . sort idnum command foreign parmseq . describe . by idnum command:list foreign parm label estimate min95 max95 p,noobs

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

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.

Author

Roger Newson, Imperial College London, UK. Email: r.newson@imperial.ac.uk

References

Newson, R. 2006. Resultssets, resultsspreadsheets, and resultsplots in Stata. Presented at the 4th German Stata Users' Group Meeting, Mannheim, 31 March, 2006. Also downloadable from Roger Newson's website at http://www.imperial.ac.uk/nhli/r.newson.

Newson, R. 2004. From datasets to resultssets in Stata. Presented at the 10th United Kingdom Stata Users' Group Meeting, London, 29 June, 2004. Also downloadable from Roger Newson's website at http://www.imperial.ac.uk/nhli/r.newson.

Newson, R. 2003. Confidence intervals and p-values for delivery to the end user. The Stata Journal 3(3): 245-269. Pre-publication draft downloadable from Roger Newson's website at http://www.imperial.ac.uk/nhli/r.newson.

Newson, R. 2002. Creating plots and tables of estimation results using parmest and friends. Presented at the 8th UK Stata Users' Group Meeting, 20-21 May, 2002. Also downloadable from Roger Newson's website at http://www.imperial.ac.uk/nhli/r.newson.

Also see

STB: STB-49 dm65, STB-58 dm65.1 Manual: [U] 20 Estimation and post-estimation commands, [D] statsby, [D] append On-line: help for append, statsby, estcom, postest, est_table help for parmcip, metaparm, parmest_outdest_opts, parmest_ci_opts, parmest_varadd_opts, parmest_varmod_opts, parmby_only_opts, parmest_resultssets help for dsconcat and lincomest if installed