{smcl}
{* 31aug2004}{...}
{hline}
help for {hi:eclplot}{right:(Roger Newson)}
{right:dialog:  {dialog eclplot} {dialog eclplot_98s:small eclplot dialog for Windows 98/ME users} }
{hline}


{title:Plot estimates with confidence limits}

{p 8 21 2}{cmd:eclplot} {it:estimate_varname clmin_varname clmax_varname parmid_varname} [{cmd:if} {it:exp}] [{cmd:in} {it:range}] [{cmd:,}
{cmdab:hor:izontal}
{cmdab:eplot:type}{cmd:(}{it:eplot_type}{cmd:)}
{cmdab:rplot:type}{cmd:(}{it:rplot_type}{cmd:)}
{cmdab::no}{cmdab:cif:oreground}
{break} {cmd:estopts(}[{it:eplot_options}] [, {it:weight}]{cmd:)}
{break} {cmd:ciopts(}[{it:rplot_options}] [, {it:weight}]{cmd:)}
{break} {cmd:supby(}{it:supby_varname} [, {it:supby_suboptions}{cmd:)}
{break} {cmd:estopts1(}[{it:eplot_options}] [, {it:weight}]{cmd:)} ... {cmd:estopts15(}[{it:eplot_options}] [, {it:weight}]{cmd:)}
{break} {cmd:ciopts1(}[{it:rplot_options}] [, {it:weight}]{cmd:)} ... {cmd:ciopts15(}[{it:rplot_options}] [, {it:weight}]{cmd:)}
{break} {cmd:plot(}{it:plot}{cmd:)} {cmdab::no}{cmdab:gr:aph}
{break} {it:twoway_options} ]

{p}
where {it:estimate_varname}, {it:clmin_varname} and {it:clmax_varname}
are numeric variables containing parameter estimates, lower confidence limits, upper confidence limits,
respectively, to be plotted on one axis, and {it:parmid_varname} is a
parameter identity variable
to determine the position of each confidence interval on the other axis.
The {it:twoway_options} are as specified for {help twoway};
see help for {it:{help twoway_options}}.


{title:Description}

{p}
{cmd:eclplot} creates 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 {help parmest} package (downloadable from {help ssc:SSC}), or by {help statsby}
or {help 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 {help plot_option:plot option}. In default, {cmd:eclplot}
does not print a legend unless multiple superimposed confidence interval plots are requested,
and has "sensible" settings for axis titles and labels (see help for {it:{help title_option}}
and {it:{help axis_options}}). However, these defaults may be overridden, using the
{it:{help twoway_options}}.


{title:Options}

{p 4 8 2}
{cmd:horizontal} specifies 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, if {cmd:horizontal} is 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.

{p 4 8 2}
{cmd:eplottype(}{it:eplot_type}{cmd:)} specifies the estimate plot type used to
plot the estimates. The value of this option may be any one of the {help twoway} plot
types {help twoway_scatter:scatter},
{help twoway_connected:connected}, {help twoway_line:line}, {help twoway_area:area},
{help twoway_bar:bar}, {help twoway_spike:spike}, and {help twoway_dropline:dropline}.
If the {cmd:eplottype()} option is not specified, then it is set to {help twoway_scatter:scatter},
and the estimates are drawn as symbols.

{p 4 8 2}
{cmd:rplottype(}{it:rplot_type}{cmd:)} 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 {help twoway}, namely {help twoway_rarea:rarea}, {help twoway_rbar:rbar},
{help twoway_rspike:rspike}, {help twoway_rcap:rcap}, {help twoway_rcapsym:rcapsym},
{help twoway_rscatter:rscatter}, {help twoway_rline:rline}, and {help twoway_rconnected:rconnected}.
If the {cmd:rplottype} option is not specified, then it is set to {help twoway_rcap:rcap},
and the confidence limits are drawn with capped spikes.

{p 4 8 2}
{cmd:nociforeground} specifies 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 neither {cmd:ciforeground} nor {cmd:nociforeground} is specified,
then a sensible default is decided as follows.
First, the {cmd:eplottype()} option is assigned a group rank,
which is 1 for {help twoway_scatter:scatter}, {help twoway_connected:connected} and {help twoway_line:line},
2 for {help twoway_dropline:dropline} and {help twoway_spike:spike}, 3 for {help twoway_bar:bar},
and 4 for {help twoway_area:area}.
Then, the {cmd:eplottype()} option is assigned a group rank,
which is 1 for {help twoway_rscatter:rscatter}, {help twoway_rconnected:rconnected} and {help twoway_rline:rline},
2 for {help twoway_rcapsym:rcapsym}, {help twoway_rcap:rcap} and {help twoway_rspike:rspike},
3 for {help twoway_rbar:rbar}, and 4 for {help twoway_rarea:rarea}.
Then, the {cmd:nociforeground} option is set to {cmd:ciforeground} if the {cmd:rplottype()} group rank
is equal to or less than the {cmd:eplottype()} group rank, and is set to {cmd:nociforeground} otherwise.
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.

{p 4 8 2}
{cmd:estopts(}[{it:eplot_options}] [, {it:weight}]{cmd:)} 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 the {cmd:eplottype()} option.
To find more about the options allowed by each estimate plot type, see help for
{help twoway} and for the individual plot types
{help twoway_scatter:scatter},
{help twoway_connected:connected}, {help twoway_line:line}, {help twoway_area:area},
{help twoway_bar:bar}, {help twoway_spike:spike}, and {help twoway_dropline:dropline}.
The optional {it:weight} is a {help weight:weight specification}, of the general form
{cmd:[}{it:weighttype}={it:expression}{cmd:]},
where {it:weighttype} may be {cmd:aweight}, {cmd:fweight} or {cmd:pweight},
and {it:expression} is a Stata expression or variable name.
If it is present, and if the user has also specified the {cmd:eplottype()} option
as {help twoway_dropline:dropline}, {help twoway_scatter:scatter} or {help twoway_connected:connected},
then it specifies that the marker symbol sizes will be weighted
by the value of the {it:expression}, which must be non-negative.
The {it:weight} can be useful for creating Cochrane forest plots for meta-analyses,
in which the marker symbol is often proportional to the study size.

{p 4 8 2}
{cmd:ciopts(}[{it:rplot_options}] [, {it:weight}]{cmd:)} 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 the
{cmd:rplottype()} option, which may be any of the range plot options allowed by {help twoway},
and defaults to {help twoway_rcap: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
{help twoway}, for {help twoway_scatter:scatter}, and for the individual range plot types
{help twoway_rarea:rarea}, {help twoway_rbar:rbar},
{help twoway_rspike:rspike}, {help twoway_rcap:rcap}, {help twoway_rcapsym:rcapsym},
{help twoway_rscatter:rscatter}, {help twoway_rline:rline}, and {help twoway_rconnected:rconnected}.
The optional {it:weight} is a {help weight:weight specification}, of the general form
{cmd:[}{it:weighttype}={it:expression}{cmd:]},
where {it:weighttype} may be {cmd:aweight}, {cmd:fweight} or {cmd:pweight},
and {it:expression} is a Stata expression or variable name.
If it is present, and if the user has also specified the {cmd:rplottype()} option
as {help twoway_rcapsym:rcapsym}, {help twoway_rscatter:rscatter} or {help twoway_rconnected:rconnected},
then it specifies that the cap symbol sizes will be weighted
by the value of the {it:expression}, which must be non-negative.

{p 4 8 2}
{cmd:supby(}{it:supby_varname} [, {it:supby_suboptions}]{cmd:)} specifies that multiple superimposed plots
of estimates and confidence limits will be created,
one for each value of the variable {it:supby_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
variable {it:supby_varname}. The suboptions of the {cmd:supby()} option are listed below under
{hi:Suboptions of the {cmd:supby()} option}.

{p 4 8 2}
{cmd:estopts1(}[{it:eplot_options}] [, {it:weight}]{cmd:)} ... {cmd:estopts15(}[{it:eplot_options}] [, {it:weight}]{cmd:)}
are only used if a {cmd:supby()} 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 the {cmd:estopts()} option.
If the {it:weight} is specified, then it overrides any {it:weight} specified by the {cmd:estopts()} option.

{p 4 8 2}
{cmd:ciopts1(}[{it:rplot_options}] [, {it:weight}]{cmd:)} ... {cmd:ciopts15(}[{it:rplot_options}] [, {it:weight}]{cmd:)}
are only used if a {cmd:supby()} 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 the {cmd:ciopts()} option.
If the {it:weight} is specified, then it overrides any {it:weight} specified by the {cmd:ciopts()} option.

{p 4 8 2}
{cmd:plot(}{it:plot}{cmd:)} provides a way to add other plots to the generated
graph; see help for {it:{help plot_option}}.

{p 4 8 2}
{cmd:nograph} specifies that no graph will be drawn. This option is useful
if the user is building a {help twoway} command from subcommands returned in {hi:r()} by {cmd:eclplot}
(see below).

{p 4 8 2}
{it:twoway_options} are any of the options documented in help for
{it:{help twoway_options}}.  These include options for titling the graph
(see help for {it:{help title_options}}), options for saving the graph to disk
(see help for {it:{help saving_option}}),
the {cmd:legend()} option (see help for {it:{help legend_option}}),
and the {cmd:by()} option (see help for {it:{help by_option}}).
In default, {cmd:eclplot} sets the {cmd:legend()} option to {cmd:legend(off)}
(implying no legend) if the {cmd:supby()} option is not specified,
and sets the contents of the legend to contain a key for each value of the {cmd:supby()} variable
if {cmd:supby()} is specified.
If the user specifies a {cmd:by()} option without a {cmd:legend()} suboption,
then the {cmd:legend()} suboption is set by default to {cmd:legend(off)}
if {cmd:supby()} is not specified, and to {cmd:legend(on)} if {cmd:supby()} is specified.
Therefore, in default, {cmd:eclplot} draws a legend if and only if the user specifies the {cmd:supby()} option.
THese defaults add to and/or override any defaults set by the {help scheme:graphics scheme} currently in use,
and can in turn be added to and/or overridden using options set by the user.


{title:Suboptions of the {cmd:supby()} option}

{p}
The {cmd:supby()} option has the syntax

{p 8 21 2}{cmd:supby(} {it:supby_varname} [ , {cmdab:m:issing} {cmdab:t:runcate}{cmd:(}{it:num}{cmd:)}
{cmdab:spa:ceby}{cmd:(}{it:num}{cmd:)} {cmdab:off:set}{cmd:(}{it:num}{cmd:)} ]
{cmd:)}

{p}
The suboptions are as follows:

{p 4 8 2}
{cmd:missing} specifies that superimposed plots will be produced for missing values of the variable {it:supby_varname}.

{p 4 8 2}
{cmd:truncate(}{it:num}{cmd:)} specifies that, in the {help legend_option:legend}, the values of the variable
{it:supby_varname} will be truncated to the length {it:num}.

{p 4 8 2}
{cmd:spaceby(}{it:num}{cmd:)} specifies a number, in units of the parameter identification variable {it:parmid_varname},
by which the superimposed plots corresponding to successive values of the variable {it:supby_varname}
will be spaced on the axis corresponding to the parameter identification variable.
This option is used to prevent multiple superimposed plots from obscuring each other.
If {cmd:spaceby()} is not specified, then it is set to zero, implying no spacing.

{p 4 8 2}
{cmd:offset(}{it:num}{cmd:)} specifies a number, in units of the parameter identification variable {it:parmid_varname},
by which the superimposed plot corresponding to the first value of the variable {it:supby_varname}
will be displaced from the value implied by the variable {it:parmid_varname}.
This number may be positive or negative.
If {cmd:offset()} is not specified, then it is set to zero,
implying that the plot corresponding to the first value of the variable {it:supby_varname}
will not be displaced from its true value.
In general, the positions of the plots on the axis corresponding to the parameter identification variable {it:parmid_varname}
is given by the formula

{p 8 8 2}
{it:parmpos = parmid_varname + offset + spaceby*(supby_seqnum-1)}

{p 8 8 2}
where {it:parmpos} is the position of the plot on the axis, {it:offset} is the value of the {cmd:offset()} suboption,
{it:spaceby} is the value of the {cmd:spaceby{}} option, and {it:supby_seqnum} is the ascending sequential order
of the value of the variable {it:supby_varname} corresponding to the plot.


{title:Saved results}

{p}
{cmd:eclplot} returns the following macro results in {hi:r()}:

{hi:r(plot)}         Contents of {help plot_option:plot() option}
{hi:r(allplots)}     Sequence of {help twoway} plot subcommands generated by {cmd:eclplot}
{hi:r(ifin)}         {help if} and/or {help in} qualifiers
{hi:r(twowayopts)}   {help twoway_options:twoway options} generated by {cmd:eclplot}
{hi:r(cmd)}          {help twoway} command generated by {cmd:eclplot}

{p}
{cmd:eclplot} works by constructing a {help twoway} command, which it then executes,
unless {cmd:nograph} is specified.
Users can use the saved {help twoway} plot subcommands, qualifiers and options to build {help twoway} commands
of their own. The result {hi:r(allplots)} contains a sequence of {help twoway} plot subcommands
separated by {hi:||}. The result {hi:r(cmd)} contains a command, which can be specified by the macro expression

{cmd:twoway `r(allplots)' || `r(ifin)' , `r(twowayopts)'}

{p}
and which is executed by {cmd:eclplot} to produce the plot. Note that, if the {cmd:supby()} option is specified,
then {hi:r(allplots)} will contain {help tempvar:temporary variable names}, belonging to temporary variables used within
{cmd:eclplot}, and therefore cannot be used to build new {help twoway} plot commands.


{title:Remarks}

{p}
{cmd:eclplot} plots confidence intervals against
another variable.
More information about {cmd:eclplot},
and about the creation of datasets for input to {cmd:eclplot},
can be found in Newson (2003), Newson (2004) and Newson (2005).

{p}
Data sets used by {cmd:eclplot} may be created manually using a spreadsheet.
However, they may also be created by the {help parmest}
package, downloadable from {help ssc:SSC}. The {help parmest}
package stores results from an {help estimates:estimation command} as a data set.
(See also help for {help _estimates} or {help 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 {help xi} utility. To reconstruct such a categorical factor in a {help parmest}
output data set, the user may use the {help factext} and {help descsave}
packages, also downloadable from SSC. Alternatively, the user may use the
{help parmest} package, possibly with the {help label} option,
and then use the {help sencode} package (also downloadable from SSC)
to encode the {hi:parm} or {hi:label} string variable in the output data set
to a numeric variable, which may be plotted by {cmd:eclplot} against the
estimates and confidence limits.

{p}
Under Windows 98/ME, the {dialog eclplot:default eclplot dialog} should not be used, as it
requires too much memory. Windows 98 users who want to use dialogs with {cmd:eclplot}
should therefore use the {dialog eclplot_98s:small eclplot dialog for Windows 98/ME users}.
(See help for {help smalldlg} for technical details on small dialogs for Windows 98/ME users.)

{p}
This version of {cmd:eclplot} is written in Stata Version 9.
However, Stata 8 users can download the Stata 8 version of {cmd:eclplot} from
{net "from http://www.imperial.ac.uk/nhli/r.newson":Roger Newson's website at http://www.imperial.ac.uk/nhli/r.newson}.

{p}
Under Stata 7, the present author usually plotted confidence intervals using either
the {help graph7:Stata 7 graph command} (with the {cmd:connect()} option) or
Nicholas J. Cox's {help hplot} package,
downloadable from {help ssc:SSC}.
The {help hplot} package is a very comprehensive package for general horizontal plots.
The {cmd:eclplot} package, on its own, cannot entirely supersede {help hplot},
but the two packages perform overlapping sets of functions, and may possibly be
viewed as being complementary.


{title:Examples}

{p}
The following examples use the {hi:auto} data, shipped with official Stata
(see help for {help sysuse}). A regression model is fitted for the {it:Y}-variable {hi:mpg}
(miles per gallon), predicted by the categorical variables {hi:rep78} (repair record) and {hi:foreign}.
The {help parmby} command of the {help parmest} package is used to create an output data set
with one observation per parameter and data on estimates and confidence limits.
The {help sencode} package is used to create a numeric variable (with value labels)
encoding the model parameter corresponding to each observation.
Finally, {cmd:eclplot} is 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".

{p 4 8 2}{cmd:. sysuse auto,clear}{p_end}
{p 4 8 2}{cmd:. parmby "xi:regress mpg i.foreign i.rep78", label norestore}{p_end}
{p 4 8 2}{cmd:. sencode parm,gene(parmid)}{p_end}
{p 4 8 2}{cmd:. eclplot estimate min95 max95 parmid}{p_end}

{p 4 8 2}{cmd:. sysuse auto,clear}{p_end}
{p 4 8 2}{cmd:. parmby "xi:regress mpg i.foreign i.rep78", label norestore}{p_end}
{p 4 8 2}{cmd:. sencode label,gene(parmlab)}{p_end}
{p 4 8 2}{cmd:. eclplot estimate min95 max95 parmlab, hori}{p_end}

{p 4 8 2}{cmd:. sysuse auto,clear}{p_end}
{p 4 8 2}{cmd:. parmby "xi:regress mpg i.foreign i.rep78", label norestore}{p_end}
{p 4 8 2}{cmd:. sencode label, gene(parmlab)}{p_end}
{p 4 8 2}{cmd:. eclplot estimate min95 max95 parmlab, hori eplot(bar)}{p_end}

{p}
The following advanced example fits the same model to the same data with a different parameterization,
and uses the {help descsave} and {help factext} packages as well as {help 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 {hi:rep78==0}.
The second plot displays confidence intervals
for the difference in mileage expected for each non-zero level of {hi:rep78}, with a dotted reference line
on the horizontal axis, indicating the difference of zero expected if {hi:rep78} has no independent effect
on {hi:mpg}. The plots demonstrate the use of the options {cmd:estopts} and {cmd:ciopts} and the use of
the {it:{help twoway_options}}.

{p 4 8 2}{cmd:. sysuse auto,clear}{p_end}
{p 4 8 2}{cmd:. tab foreign,gene(orig_) nolabel}{p_end}
{p 4 8 2}{cmd:. tempfile tf0}{p_end}
{p 4 8 2}{cmd:. descsave foreign rep78,do(`tf0')}{p_end}
{p 4 8 2}{cmd:. parmby "xi:regress mpg orig_* i.rep78,noconst",label norestore}{p_end}
{p 4 8 2}{cmd:. factext,do(`tf0')}{p_end}
{p 4 8 2}{cmd:. eclplot estimate min95 max95 foreign,hori estopts(msize(vlarge)) ciopts(msize(vlarge)) yscale(range(-1 2)) ylab(0 1) xtitle("Mean mileage per gallon")}{p_end}
{p 4 8 2}{cmd:. 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)")}{p_end}

{p}
The following example also uses {help parmby} and {help sencode}. It demonstrates the use of the {cmd:supby()} option
of {cmd:eclplot} to produce multiple superimposed detonator plots.

{p 4 8 2}{cmd:. sysuse auto, clear}{p_end}
{p 4 8 2}{cmd:. tabulate rep78, gene(rep78_)}{p_end}
{p 4 8 2}{cmd:. parmby "regress mpg rep78_*, noconst", by(foreign) label norestore}{p_end}
{p 4 8 2}{cmd:. sencode label if parm!="_cons", gene(parmlab)}{p_end}
{p 4 8 2}{cmd:. lab var parmlab "Repair record 1978"}{p_end}
{p 4 8 2}{cmd:. lab var estimate "Mean mileage (mpg)"}{p_end}
{p 4 8 2}{cmd:. eclplot estimate min95 max95 parmlab, eplot(bar) estopts(barwidth(0.25)) supby(foreign, spaceby(0.25)) xscale(range(0 6)) xlabel(1(1)5, angle(30))}{p_end}
{p 4 8 2}{cmd:. more}{p_end}
{p 4 8 2}{cmd:. 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))}{p_end}
{p 4 8 2}{cmd:. more}{p_end}


{title:Acknowledgements}

{p}
I would like to thank Jean Marie Linhart and James Hassell of StataCorp for their very helpful advice
on writing the dialogs for {cmd:eclplot}, and also Vince Wiggins of StataCorp for his very helpful advice
on writing {cmd:eclplot}.


{title:Author}

{p}
Roger Newson, Imperial College London, UK.
Email: {browse "mailto:r.newson@imperial.ac.uk":r.newson@imperial.ac.uk}


{title:References}

{p}
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}.

{p}
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}.

{p}
Newson, R. 2005. Generalized confidence interval plots using commands or dialogs.
Presented at {browse "http://ideas.repec.org/s/boc/usug05.html" :the 11th United Kingdom Stata Users' Group Meeting, London, 17 May, 2005}.
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: }Manual: {hi:[G] graph intro}, {hi:[G] graph twoway}
{p_end}
{p 4 13 2}
On-line: help for {help twoway}, {help graph}, {help graph_intro}, {help graph7}{break}
help for {help parmest}, {help sencode}, {help factext}, {help descsave}, {help hplot} if installed
{p_end}
