------------------------------------------------------------------------------- help foreclplot(Roger Newson) dialog: eclplot small eclplot dialog for Windows 98/ME users -------------------------------------------------------------------------------

Plot estimates with confidence limits

eclplotestimate_varname clmin_varname clmax_varname parmid_varname[ifexp] [inrange] [,horizontaleplottype(eplot_type)rplottype(rplot_type)nociforegroundestopts([eplot_options] [,weight])ciopts([rplot_options] [,weight])supby(supby_varname[,supby_suboptions)estopts1([eplot_options] [,weight])...estopts15([eplot_options] [,weight])ciopts1([rplot_options] [,weight])...ciopts15([rplot_options] [,weight])plot(plot)nographtwoway_options]where

estimate_varname,clmin_varnameandclmax_varnameare numeric variables containing parameter estimates, lower confidence limits, upper confidence limits, respectively, to be plotted on one axis, andparmid_varnameis a parameter identity variable to determine the position of each confidence interval on the other axis. Thetwoway_optionsare as specified for twoway; see help fortwoway_options.

Description

eclplotcreates a plot of estimates with lower and upper confidence limits on one axis against another variable on the other axis. The estimates and lower and upper confidence limits are stored in three variables, with one observation per confidence interval plotted. Data sets with such variables may be created by the parmest package (downloadable from SSC), or by statsby or postfile in official Stata. The user has a choice of plotting the confidence intervals horizontally or vertically, a choice of estimate plot types for the estimates, and a choice of range plot types for the confidence intervals, and may also overlay the confidence interval plot with other plots using the plot option. In default,eclplotdoes not print a legend unless multiple superimposed confidence interval plots are requested, and has "sensible" settings for axis titles and labels (see help fortitle_optionandaxis_options). However, these defaults may be overridden, using thetwoway_options.

Options

horizontalspecifies that the confidence intervals must be plotted horizontally, with the estimates and confidence limits on the horizontal axis and the other variable on the vertical axis. In default, ifhorizontalis not specified, the confidence intervals are plotted vertically, with the estimates and confidence limits on the vertical axis and the other variable on the horizontal axis.

eplottype(eplot_type)specifies the estimate plot type used to plot the estimates. The value of this option may be any one of the twoway plot types scatter, connected, line, area, bar, spike, and dropline. If theeplottype()option is not specified, then it is set to scatter, and the estimates are drawn as symbols.

rplottype(rplot_type)specifies the range plot type used to plot the confidence intervals. The value of this option may be any one of the range plot types allowed by twoway, namely rarea, rbar, rspike, rcap, rcapsym, rscatter, rline, and rconnected. If therplottypeoption is not specified, then it is set to rcap, and the confidence limits are drawn with capped spikes.

nociforegroundspecifies whether the confidence intervals are in the foreground (where they can overwrite the estimates) or in the background (where the estimates can overwrite them). If neitherciforegroundnornociforegroundis specified, then a sensible default is decided as follows. First, theeplottype()option is assigned a group rank, which is 1 for scatter, connected and line, 2 for dropline and spike, 3 for bar, and 4 for area. Then, theeplottype()option is assigned a group rank, which is 1 for rscatter, rconnected and rline, 2 for rcapsym, rcap and rspike, 3 for rbar, and 4 for rarea. Then, thenociforegroundoption is set tociforegroundif therplottype()group rank is equal to or less than theeplottype()group rank, and is set tonociforegroundotherwise. The default rule can therefore be described as "symbols and connecting lines in front of spikes in front of bars in front of areas", and was chosen to minimize the probability of important information being hidden.

estopts([eplot_options] [,weight])specifies any plot options for the plotting of the estimates. These options may be any of the options allowed for the estimate plot type specified by theeplottype()option. To find more about the options allowed by each estimate plot type, see help for twoway and for the individual plot types scatter, connected, line, area, bar, spike, and dropline. The optionalweightis a weight specification, of the general form[weighttype=expression], whereweighttypemay beaweight,fweightorpweight, andexpressionis a Stata expression or variable name. If it is present, and if the user has also specified theeplottype()option as dropline, scatter or connected, then it specifies that the marker symbol sizes will be weighted by the value of theexpression, which must be non-negative. Theweightcan be useful for creating Cochrane forest plots for meta-analyses, in which the marker symbol is often proportional to the study size.

ciopts([rplot_options] [,weight])specifies any plot options for drawing the confidence limits. These options may be any of the options allowed for the range plot type specified by therplottype()option, which may be any of the range plot options allowed by twoway, and defaults to rcap. For instance, the user may specify the width of the caps on each confidence limit. To find more about the options allowed by each range plot type, see help for twoway, for scatter, and for the individual range plot types rarea, rbar, rspike, rcap, rcapsym, rscatter, rline, and rconnected. The optionalweightis a weight specification, of the general form[weighttype=expression], whereweighttypemay beaweight,fweightorpweight, andexpressionis a Stata expression or variable name. If it is present, and if the user has also specified therplottype()option as rcapsym, rscatter or rconnected, then it specifies that the cap symbol sizes will be weighted by the value of theexpression, which must be non-negative.

supby(supby_varname[,supby_suboptions])specifies that multiple superimposed plots of estimates and confidence limits will be created, one for each value of the variablesupby_varname, with distinct styles. There can be up to 15 superimposed plots. Unless the user specifies otherwise, a legend will be created, identifying each plot with a value of the variablesupby_varname. The suboptions of thesupby()option are listed below underSuboptions of the supby()option.

estopts1([eplot_options] [,weight])...estopts15([eplot_options] [,weight])are only used if asupby()option is specified. They specify plot options specific to the individual superimposed estimates plots, additional to the plot options specified for all estimate plots by theestopts()option. If theweightis specified, then it overrides anyweightspecified by theestopts()option.

ciopts1([rplot_options] [,weight])...ciopts15([rplot_options] [,weight])are only used if asupby()option is specified. They specify plot options specific to the individual superimposed confidence limit plots, additional to the plot options specified for all confidence limit plots by theciopts()option. If theweightis specified, then it overrides anyweightspecified by theciopts()option.

plot(plot)provides a way to add other plots to the generated graph; see help forplot_option.

nographspecifies that no graph will be drawn. This option is useful if the user is building a twoway command from subcommands returned inr()byeclplot(see below).

twoway_optionsare any of the options documented in help fortwoway_options. These include options for titling the graph (see help fortitle_options), options for saving the graph to disk (see help forsaving_option), thelegend()option (see help forlegend_option), and theby()option (see help forby_option). In default,eclplotsets thelegend()option tolegend(off)(implying no legend) if thesupby()option is not specified, and sets the contents of the legend to contain a key for each value of thesupby()variable ifsupby()is specified. If the user specifies aby()option without alegend()suboption, then thelegend()suboption is set by default tolegend(off)ifsupby()is not specified, and tolegend(on)ifsupby()is specified. Therefore, in default,eclplotdraws a legend if and only if the user specifies thesupby()option. THese defaults add to and/or override any defaults set by the graphics scheme currently in use, and can in turn be added to and/or overridden using options set by the user.

Suboptions of thesupby()optionThe

supby()option has the syntax

supby(supby_varname[ ,missingtruncate(num)spaceby(num)offset(num)])The suboptions are as follows:

missingspecifies that superimposed plots will be produced for missing values of the variablesupby_varname.

truncate(num)specifies that, in the legend, the values of the variablesupby_varnamewill be truncated to the lengthnum.

spaceby(num)specifies a number, in units of the parameter identification variableparmid_varname, by which the superimposed plots corresponding to successive values of the variablesupby_varnamewill be spaced on the axis corresponding to the parameter identification variable. This option is used to prevent multiple superimposed plots from obscuring each other. Ifspaceby()is not specified, then it is set to zero, implying no spacing.

offset(num)specifies a number, in units of the parameter identification variableparmid_varname, by which the superimposed plot corresponding to the first value of the variablesupby_varnamewill be displaced from the value implied by the variableparmid_varname. This number may be positive or negative. Ifoffset()is not specified, then it is set to zero, implying that the plot corresponding to the first value of the variablesupby_varnamewill not be displaced from its true value. In general, the positions of the plots on the axis corresponding to the parameter identification variableparmid_varnameis given by the formula

parmpos = parmid_varname + offset + spaceby*(supby_seqnum-1)where

parmposis the position of the plot on the axis,offsetis the value of theoffset()suboption,spacebyis the value of thespaceby{}option, andsupby_seqnumis the ascending sequential order of the value of the variablesupby_varnamecorresponding to the plot.

Saved results

eclplotreturns the following macro results inr():

r(plot)Contents of plot() optionr(allplots)Sequence of twoway plot subcommands generated byeclplotr(ifin)if and/or in qualifiersr(twowayopts)twoway options generated byeclplotr(cmd)twoway command generated byeclplot

eclplotworks by constructing a twoway command, which it then executes, unlessnographis specified. Users can use the saved twoway plot subcommands, qualifiers and options to build twoway commands of their own. The resultr(allplots)contains a sequence of twoway plot subcommands separated by||. The resultr(cmd)contains a command, which can be specified by the macro expression

twoway `r(allplots)' || `r(ifin)' , `r(twowayopts)'and which is executed by

eclplotto produce the plot. Note that, if thesupby()option is specified, thenr(allplots)will contain temporary variable names, belonging to temporary variables used withineclplot, and therefore cannot be used to build new twoway plot commands.

Remarks

eclplotplots confidence intervals against another variable. More information abouteclplot, and about the creation of datasets for input toeclplot, can be found in Newson (2003), Newson (2004) and Newson (2005).Data sets used by

eclplotmay be created manually using a spreadsheet. However, they may also be created by the parmest package, downloadable from SSC. The parmest package stores results from an estimation command as a data set. (See also help for _estimates or ereturn.) It creates a data set with one observation per model parameter, or one observation per parameter per by-group, and data on parameter names, estimates, confidence limits, and other parameter attributes. The other variable, against which the confidence intervals are plotted, may be any numeric variable, but is often a categorical factor included as a predictor in the model fitted by the estimation command using the xi utility. To reconstruct such a categorical factor in a parmest output data set, the user may use the factext and descsave packages, also downloadable from SSC. Alternatively, the user may use the parmest package, possibly with the label option, and then use the sencode package (also downloadable from SSC) to encode theparmorlabelstring variable in the output data set to a numeric variable, which may be plotted byeclplotagainst the estimates and confidence limits.Under Windows 98/ME, the default eclplot dialog should not be used, as it requires too much memory. Windows 98 users who want to use dialogs with

eclplotshould therefore use the small eclplot dialog for Windows 98/ME users. (See help for smalldlg for technical details on small dialogs for Windows 98/ME users.)This version of

eclplotis written in Stata Version 9. However, Stata 8 users can download the Stata 8 version ofeclplotfrom Roger Newson's website at http://www.imperial.ac.uk/nhli/r.newson.Under Stata 7, the present author usually plotted confidence intervals using either the Stata 7 graph command (with the

connect()option) or Nicholas J. Cox's hplot package, downloadable from SSC. The hplot package is a very comprehensive package for general horizontal plots. Theeclplotpackage, on its own, cannot entirely supersede hplot, but the two packages perform overlapping sets of functions, and may possibly be viewed as being complementary.

ExamplesThe following examples use the

autodata, shipped with official Stata (see help for sysuse). A regression model is fitted for theY-variablempg(miles per gallon), predicted by the categorical variablesrep78(repair record) andforeign. The parmby command of the parmest package is used to create an output data set with one observation per parameter and data on estimates and confidence limits. The sencode package is used to create a numeric variable (with value labels) encoding the model parameter corresponding to each observation. Finally,eclplotis used to display the confidence intervals. The first example uses parameter names to label a vertical confidence interval plot. The second example uses parameter labels to label a horizontal confidence interval plot. The third example uses parameter labels to label a horizontal "detonator plot".

. sysuse auto,clear. parmby "xi:regress mpg i.foreign i.rep78", label norestore. sencode parm,gene(parmid). eclplot estimate min95 max95 parmid

. sysuse auto,clear. parmby "xi:regress mpg i.foreign i.rep78", label norestore. sencode label,gene(parmlab). eclplot estimate min95 max95 parmlab, hori

. sysuse auto,clear. parmby "xi:regress mpg i.foreign i.rep78", label norestore. sencode label, gene(parmlab). eclplot estimate min95 max95 parmlab, hori eplot(bar)The following advanced example fits the same model to the same data with a different parameterization, and uses the descsave and factext packages as well as parmby. It creates two confidence interval plots. The first plot displays two confidence intervals for the mean mileage levels expected for cars from the USA and from elsewhere with

rep78==0. The second plot displays confidence intervals for the difference in mileage expected for each non-zero level ofrep78, with a dotted reference line on the horizontal axis, indicating the difference of zero expected ifrep78has no independent effect onmpg. The plots demonstrate the use of the optionsestoptsandcioptsand the use of thetwoway_options.

. sysuse auto,clear. tab foreign,gene(orig_) nolabel. tempfile tf0. descsave foreign rep78,do(`tf0'). parmby "xi:regress mpg orig_* i.rep78,noconst",label norestore. factext,do(`tf0'). eclplot estimate min95 max95 foreign,hori estopts(msize(vlarge))ciopts(msize(vlarge)) yscale(range(-1 2)) ylab(0 1) xtitle("Meanmileage per gallon"). eclplot estimate min95 max95 rep78,hori estopts(msize(vlarge))ciopts(msize(vlarge)) yscale(range(1 6)) xline(0,lpattern(dot))xtitle("Mean difference (miles per gallon)")The following example also uses parmby and sencode. It demonstrates the use of the

supby()option ofeclplotto produce multiple superimposed detonator plots.

. sysuse auto, clear. tabulate rep78, gene(rep78_). parmby "regress mpg rep78_*, noconst", by(foreign) label norestore. sencode label if parm!="_cons", gene(parmlab). lab var parmlab "Repair record 1978". lab var estimate "Mean mileage (mpg)". eclplot estimate min95 max95 parmlab, eplot(bar)estopts(barwidth(0.25)) supby(foreign, spaceby(0.25)) xscale(range(06)) xlabel(1(1)5, angle(30)). more. eclplot estimate min95 max95 parmlab, eplot(bar) ciopts(blcolor(black))estopts(barwidth(0.25)) estopts1(bcolor(red)) estopts2(bcolor(blue))supby(foreign, spaceby(0.25)) xscale(range(0 6)) xlabel(1(1)5,angle(30)). more

AcknowledgementsI would like to thank Jean Marie Linhart and James Hassell of StataCorp for their very helpful advice on writing the dialogs for

eclplot, and also Vince Wiggins of StataCorp for his very helpful advice on writingeclplot.

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

ReferencesNewson, R. 2003. Confidence intervals and

p-values for delivery to the end user.The Stata Journal3(3): 245-269. Pre-publication draft 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. 2005. Generalized confidence interval plots using commands or dialogs. Presented at the 11th United Kingdom Stata Users' Group Meeting, London, 17 May, 2005. Also downloadable from Roger Newson's website at http://www.imperial.ac.uk/nhli/r.newson.

Also seeManual:

[G] graph intro,[G] graph twowayOn-line: help for twoway, graph, graph_intro, graph7 help for parmest, sencode, factext, descsave, hplot if installed