{smcl} {hline} help for {cmd:parmest} and {cmd:parmby}{right:(STB-49: dm65; STB-58: dm65.1; Roger Newson)} {hline} {title:Convert estimation results to a dataset with one observation per parameter} {pstd} The {cmd: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, {it:P}-values and other parameter attributes. The modules are as follows: {p2colset 4 16 18 2}{...} {p2col:Module}Description{p_end} {p2line} {p2col:{cmd:parmest}}Create dataset from most recent estimation results{p_end} {p2col:{cmd:parmby}}Create dataset by calling an estimation command once for each by-group{p_end} {p2col:{helpb parmcip}}Confidence limits and {it:P}-values from estimates and standard errors{p_end} {p2col:{helpb metaparm}}Confidence limits and {it:P}-values for linear combinations of independent parameters (as in a meta-analysis) {p_end} {p2line} {p2colreset} {pstd} The modules {cmd:parmest} and {cmd:parmby} are documented here. See {helpb parmcip} and {helpb metaparm} for the other modules. {title:Syntax for {cmd:parmest} and {cmd:parmby}} {p 8 21 2} {cmd:parmest} {cmd:,} [ {it:{help parmest##parmest_outdest_opts:parmest_outdest_opts}} {it:{help parmest##parmest_ci_opts:parmest_ci_opts}} {it:{help parmest##parmest_varadd_opts:parmest_varadd_opts}} {it:{help parmest##parmest_varmod_opts:parmest_varmod_opts}} ] {p 8 21 2} {cmd:parmby} [{cmd:`}]{cmd:"}{it:command}{cmd:"}[{cmd:'}] {cmd:,} [ {it:parmest_opts} {it:{help parmest##parmby_only_opts:parmby_only_opts}} ] {pstd} where {it:parmest_opts} are options allowed by {cmd:parmest} and {it:command} is a Stata {help estcom:estimation command}. {title:Description} {pstd} {cmd:parmest} takes, as input, the most recently calculated set of {help return:estimation results}, created by the most recently executed {help est:estimation command}. It creates, as output, a new dataset, with one observation per estimated parameter, and variables containing parameter names, estimates, standard errors, {it:z}-test or {it:t}-test statistics, {it:P}-values, confidence limits, and other estimation results if requested by the user. {cmd:parmby} executes an {help est: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 {cmd:parmest} output dataset, together with the by-variables. The output dataset created by {cmd:parmby} or {cmd:parmest} may be listed to the Stata log, or saved to a disk file, or written to the memory (overwriting any pre-existing dataset). {title:Options for use with {cmd:parmest} and {cmd:parmby}} {pstd} {cmd:parmest} and {cmd:parmby} have a large number of options, which fall into the following 5 groups: {p2colset 4 26 28 2}{...} {p2col:Option group}Description{p_end} {p2line} {p2col:{it:{help parmest##parmest_outdest_opts:parmest_outdest_opts}}}Output-destination options for {cmd:parmest} and {cmd:parmby}{p_end} {p2col:{it:{help parmest##parmest_ci_opts:parmest_ci_opts}}}Confidence-interval options for {cmd:parmest} and {cmd:parmby}{p_end} {p2col:{it:{help parmest##parmest_varadd_opts:parmest_varadd_opts}}}Variable-adding options for {cmd:parmest} and {cmd:parmby}{p_end} {p2col:{it:{help parmest##parmest_varmod_opts:parmest_varmod_opts}}}Variable-modifying options for {cmd:parmest} and {cmd:parmby}{p_end} {p2col:{it:{help parmest##parmby_only_opts:parmby_only_opts}}}Options for {cmd:parmby} only{p_end} {p2line} {p2colreset} {marker parmest_outdest_opts}{...} {title:Output-destination options for {cmd:parmest} and {cmd:parmby}} {synoptset 32} {synopthdr} {synoptline} {synopt:{opt li:st(list_spec)}}List output dataset to Stata log and/or Results window{p_end} {synopt:{cmdab:sa:ving}{cmd:(}{it:filename}[{cmd:,replace}]{cmd:)}}Save output dataset to a disk file{p_end} {synopt:{cmdab::no}{cmdab:re:store}}Write output dataset to memory{p_end} {synopt:{opt fast}}Write output dataset to memory without precautions{p_end} {synopt:{opt fl:ist(global_macro_name)}}Append output filename to a global macro{p_end} {synoptline} {pstd} where {it:list_spec} is a specification of the form {pstd} [{varlist}] {ifin} [ , [{help list:{it:list_options}} ] ] {pstd} and {help list:{it:list_options}} is a list of options used by the {helpb list} command. {pstd} See {help parmest_outdest_opts:{it:parmest_outdest_opts}} for details of these options. {marker parmest_ci_opts}{...} {title:Confidence-interval options for {cmd:parmest} and {cmd:parmby}} {synoptset 24} {synopthdr} {synoptline} {synopt:{opt ef:orm}}Exponentiate estimates and confidence limits{p_end} {synopt:{opt d:of(#)}}Degrees of freedom for calculating confidence limits{p_end} {synopt:{cmdab:le:vel}{cmd:(}{help numlist:{it:numlist}}{cmd:)}}Confidence level(s) for calculating confidence limits{p_end} {synopt:{opt cln:umber(numbering_rule)}}Numbering rule for naming confidence limit variables{p_end} {synoptline} {pstd} where {it:numbering_rule} is {pstd} {cmd:level} | {cmd:rank} {pstd} See {help parmest_ci_opts:{it:parmest_ci_opts}} for details of these options. {marker parmest_varadd_opts}{...} {title:Variable-adding options for {cmd:parmest} and {cmd:parmby}} {synoptset 16} {synopthdr} {synoptline} {synopt:{opt l:abel}}Variable containing {it:X}-variable labels{p_end} {synopt:{opt yl:abel}}Variable containing {it:Y}-variable labels{p_end} {synopt:{opt idn:um(#)}}Numeric dataset ID variable{p_end} {synopt:{opt ids:tr(string)}}String dataset ID variable{p_end} {synopt:{cmdab:sta:rs}{cmd:(}{help numlist:{it:numlist}})}Variable containing stars for the {it:P}-value{p_end} {synopt:{opt em:ac(name_list)}}Variables containing macro estimation results{p_end} {synopt:{opt es:cal(name_list)}}Variables containing scalar estimation results{p_end} {synopt:{opt er:ows(name_list)}}Variables containing rows of matrix estimation results{p_end} {synopt:{opt ec:ols(name_list)}}Variables containing columns of matrix estimation results{p_end} {synopt:{opt ev:ec(name_list)}}Variables containing vectors extracted from matrix estimation results{p_end} {synoptline} {pstd} where {it:name_list} is a list of names of Stata {help estimates:estimation results}. {pstd} See {help parmest_varadd_opts:{it:parmest_varadd_opts}} for details of these options. {marker parmest_varmod_opts}{...} {title:Variable-modifying options for {cmd:parmest} and {cmd:parmby}} {synoptset 24} {synopthdr} {synoptline} {synopt:{opt ren:ame(renaming_list)}}Rename variables in the output dataset{p_end} {synopt:{opt fo:rmat(formatting_list)}}Display formats for variables in the output dataset{p_end} {synopt:{opt float}}Set storage type of numeric variables to {cmd:float} or lower precision{p_end} {synopt:{cmdab::no}{cmdab:dou:ble}}Alternative option for specifying {cmd:float}{p_end} {synoptline} {pstd} where {it:renaming_list} is a list of {help varname: variable names} of form {pstd} {it:oldvarname_1 newvarname_1 ... oldvarname_n newvarname_n} {pstd} and {it:formatting_list} is a list of form {pstd} {it:{help varlist:varlist_1} {help format:format_1} ... {help varlist:varlist_n} {help format:format_n}} {pstd} See {help parmest_varmod_opts:{it:parmest_varmod_opts}} for details of these options. {marker parmby_only_opts}{...} {title:Options for {cmd:parmby} only} {synoptset 24} {synopthdr} {synoptline} {synopt:{cmd:by(}{varlist}{cmd:)}}Specify variables defining by-groups{p_end} {synopt:{opt com:mand}}Add a variable containing the command called{p_end} {synoptline} {pstd} See {help parmby_only_opts:{it:parmby_only_opts}} for details of these options. {title:Output datasets created by {cmd:parmest} and {cmd:parmby}} {pstd} These output datasets (or resultssets) are described in detail in {help parmest_resultssets:{it:parmest_resultssets}}. {title:Remarks} {pstd} More information about the use of {cmd:parmest} and {cmd:parmby} can be found in Newson (2006), Newson (2004), Newson (2003) and Newson (2002). {cmd:parmby} is similar to {helpb 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, {cmd:parmby} outputs the estimation output to the log, although the user can use {helpb quietly} to suppress this. {cmd:parmby} is a "quasi-byable" front end for {cmd:parmest}, and is the command usually used in any new programs for creating output datasets on disk or in memory. {cmd:parmest} is an older command, and is now mainly used when the user wishes simply to use the {cmd: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 {cmd:parmest} command is therefore used as an alternative version of {helpb est_table:estimates table}, with the added power to calculate confidence limits. With either {cmd:parmby} or {cmd:parmest}, the user must specify at least one of the four {help parmest_outdest_opts:output-destination options} {cmd:list()}, {cmd:saving()}, {cmd:norestore} and/or {cmd: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). {cmd:parmby} works by calling {cmd:parmest}, which in turn works by calling {helpb parmcip}. {title:Examples} {pstd} The following examples use the {cmd: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. {p 16 20}{inp:. regr price mpg weight,robust}{p_end} {p 16 20}{inp:. parmest,format(estimate min95 max95 %8.2f p %8.1e) list(,)}{p_end} {p 16 20}{inp:. glm mpg foreign,family(gamma) link(power -1)}{p_end} {p 16 20}{inp:. parmest, label format(estimate min95 max95 p %8.2f p %8.1e) list(parm label estimate min95 max95 p,clean noobs)}{p_end} {p 16 20}{inp:. regress price mpg weight foreign displacement headroom,robust}{p_end} {p 16 20}{inp:. 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)}{p_end} {p 16 20}{inp:. parmby "qui logit foreign mpg, or", label eform for(estimate min95 max95 %8.2f p %8.1e) li(parm label estimate min95 max95 p)}{p_end} {p 16 20}{inp:. 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)}{p_end} {pstd} The following examples use the {cmd:norestore} option to create an output dataset in the memory, overwriting any pre-existing dataset. {p 16 20}{inp:. parmby "regr mpg weight,robust",by(foreign) label command norestore}{p_end} {p 16 20}{inp:. gene gpm=1/mpg}{p_end} {p 16 20}{inp:. rename foreign t}{p_end} {p 16 20}{inp:. parmby "regr gpm weight",by(t) label rename(t tstat p pvalue) norestore}{p_end} {p 16 20}{inp:. gene byte pw1=1}{p_end} {p 16 20}{inp:. svyset [pwei=pw1],clear}{p_end} {p 16 20}{inp:. parmby "svy :mean mpg weight price, over(foreign)", norestore ylabel ev(_N _N_subp) es(N)}{p_end} {p 16 20}{inp:. describe}{p_end} {p 16 20}{inp:. list eq ylabel parm ev_* es_* estimate min95 max95}{p_end} {pstd} The following examples use the {cmd:saving()} option to create an output dataset in a disk file. {p 16 20}{inp:. parmby "logit foreign mpg, or", label eform saving(parms1.dta)}{p_end} {p 16 20}{inp:. parmby "regr mpg weight displ,robust",by(foreign) label saving(myparms,replace)}{p_end} {pstd} The following example demonstrates the use of {cmd:parmby} with multiple regression commands, saving the results in multiple temporary datasets. These datasets are then concatenated, using the {helpb dsconcat} command, to form a single dataset in memory, with one observation for each parameter in each regression. The {helpb dsconcat} command can be downloaded from {help ssc:SSC} using the {helpb ssc} command in Stata. This example uses the options {cmd:idnum()} and {cmd:idstr()} to create analysis identifier variables, which contain information identifying the regression model for each parameter. {p 16 20}{inp:. gene gpm=1/mpg}{p_end} {p 16 20}{inp:. tempfile tf1 tf2 tf3}{p_end} {p 16 20}{inp:. parmby "regr gpm weight", lab saving(`tf1',replace) idn(1) ids(Unadjusted)}{p_end} {p 16 20}{inp:. parmby "regr gpm foreign", lab saving(`tf2',replace) idn(2) ids(Unadjusted)}{p_end} {p 16 20}{inp:. parmby "regr gpm weight foreign", lab saving(`tf3',replace) idn(3) ids(Adjusted)}{p_end} {p 16 20}{inp:. dsconcat `tf1' `tf2' `tf3'}{p_end} {p 16 20}{inp:. list idnum idstr parm estimate min95 max95 p,noobs nodis}{p_end} {pstd} The following advanced example demonstrates the use of the {cmd:flist()} option with the {helpb dsconcat} command (downloadable from {help ssc:SSC}). {cmd:parmby} is used to carry out multiple regression analyses, storing the results in temporary files, whose names are stored by the {cmd:flist()} option in a global macro {hi:tflist}. The files are then concatenated using {helpb 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 {hi:command} and the numeric analysis identifier variable {hi:idnum}. The dataset is sorted, described and listed. {p 16 20}{inp:. global tflist ""}{p_end} {p 16 20}{inp:. global modseq=0}{p_end} {p 16 20}{inp:. foreach X of var headroom trunk weight length turn displacement gear_ratio {c -(}}{p_end} {p 16 20}{inp:. global modseq=$modseq+1}{p_end} {p 16 20}{inp:. tempfile tf$modseq}{p_end} {p 16 20}{inp:. 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)}{p_end} {p 16 20}{inp:. {c )-}}{p_end} {p 16 20}{inp:. dsconcat $tflist}{p_end} {p 16 20}{inp:. sort idnum command foreign parmseq}{p_end} {p 16 20}{inp:. describe}{p_end} {p 16 20}{inp:. by idnum command:list foreign parm label estimate min95 max95 p,noobs}{p_end} {pstd} More examples can be found in Newson (2006), Newson (2004), Newson (2003) and Newson (2002). {title:Acknowledgments} {pstd} 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 {cmd:parmest}. {title:Author} {pstd} Roger Newson, Imperial College London, UK. Email: {browse "mailto:r.newson@imperial.ac.uk":r.newson@imperial.ac.uk} {title:References} {phang} Newson, R. 2006. Resultssets, resultsspreadsheets, and resultsplots in Stata. Presented at {browse "http://ideas.repec.org/s/boc/dsug06.html" :the 4th German Stata Users' Group Meeting, Mannheim, 31 March, 2006}. Also downloadable from {net "from http://www.imperial.ac.uk/nhli/r.newson":Roger Newson's website at http://www.imperial.ac.uk/nhli/r.newson}. {phang} Newson, R. 2004. From datasets to resultssets in Stata. Presented at {browse "http://ideas.repec.org/s/boc/usug04.html" :the 10th United Kingdom Stata Users' Group Meeting, London, 29 June, 2004}. Also downloadable from {net "from http://www.imperial.ac.uk/nhli/r.newson":Roger Newson's website at http://www.imperial.ac.uk/nhli/r.newson}. {phang} Newson, R. 2003. Confidence intervals and {it:p}-values for delivery to the end user. {it:The Stata Journal} 3(3): 245-269. Pre-publication draft downloadable from {net "from http://www.imperial.ac.uk/nhli/r.newson":Roger Newson's website at http://www.imperial.ac.uk/nhli/r.newson}. {phang} Newson, R. 2002. Creating plots and tables of estimation results using {cmd:parmest} and friends. Presented at {browse "http://ideas.repec.org/s/boc/usug02.html" :the 8th UK Stata Users' Group Meeting, 20-21 May, 2002}. Also downloadable from {net "from http://www.imperial.ac.uk/nhli/r.newson":Roger Newson's website at http://www.imperial.ac.uk/nhli/r.newson}. {title:Also see} {p 4 13 2} {bind: }STB: STB-49 dm65, STB-58 dm65.1 {p_end} {p 4 13 2} {bind: }Manual: {hi:[U] 20 Estimation and post-estimation commands}, {break} {hi:[D] statsby}, {hi:[D] append} {p_end} {p 4 13 2} On-line: help for {helpb append}, {helpb statsby}, {help estcom}, {help postest}, {help est_table} {break} help for {helpb parmcip}, {helpb metaparm}, {help parmest_outdest_opts:{it:parmest_outdest_opts}}, {it:{help parmest_ci_opts}}, {help parmest_varadd_opts:{it:parmest_varadd_opts}}, {help parmest_varmod_opts:{it:parmest_varmod_opts}}, {help parmby_only_opts:{it:parmby_only_opts}}, {help parmest_resultssets:{it:parmest_resultssets}} {break} help for {helpb dsconcat} and {helpb lincomest} if installed {p_end}