{smcl}
{* 16jul2004}{...}
{hline}
help for {cmd:ellip}{right:(SJ4-#: gr32_1)}
{hline}

{title:Graphing confidence ellipses}
{title:[An update of {cmd:ellip} for Stata 8]}

{p 8 14 2}{cmd:ellip} {it:yvar} {it:xvar} [{cmd:if}
{it:exp}] [{cmd:in} {it:range}] [{cmd:,} 
{cmd:means}
{it:common_options}
]

{p 8 14 2}{cmd:ellip} {it:yvar} [{it:xvar}] [{cmd:if}
{it:exp}] [{cmd:in} {it:range}] {cmd:,} {cmd:coefs} 
[{cmdab:p:ool}{cmd:(}{it:#}{cmd:)} 
[{cmd:plopts}{cmd:(}{it:line_options}{cmd:)}
{cmd:pcopts}{cmd:(}{it:connect_options}{cmd:)}]
{it:common_options}
]

where {it:common_options} are:

{p 14 14 2}{cmdab:c:onstant}{cmd:(}{it:statname} [{it:#}] | {it:#}{cmd:)}
{cmdab:l:evel}{cmd:(}{it:#}{cmd:)}
{cmd:formula}{cmd:(}{it:acosr} | {it:theta}{cmd:)}
{cmdab:g:enerate}{cmd:(}{it:ynewvar} {it:xnewvar}{cmd:)}
{cmdab:nogr:aph}
{cmd:replace}
{cmd:evr}{cmd:(}{it:#}{cmd:)}
{cmdab:f:rom}{cmd:(}{it:#}{cmd:)}
{cmdab:t:o}{cmd:(}{it:#}{cmd:)}
{cmdab:np:oints}{cmd:(}{it:#}{cmd:)} 
{cmd:overlay}
{cmd:total}
[{cmdab:tl:abel}{cmd:(}{it:label}{cmd:)}]
{cmdab:diam:eter}{cmd:(}{it:#}{cmd:)}
[{cmd:dlopts}{cmd:(}{it:line_options}{cmd:)}]
{cmd:plot}{cmd:(}{it:plot}{cmd:)}
{it:connect_options}
{it:twoway_options}


{title:Description}

{p 4 4 2}{cmd:ellip} calculates a confidence ellipse from the elliptically
distributed variables {it:yvar} and {it:xvar}, and then graphs the confidence
ellipse using {cmd:graph twoway line}. By default, or if the option
{cmd:means} is specified, {it:yvar} and {it:xvar} are data variables. If
the option {cmd:coefs} is specified, {it:yvar} and {it:xvar} are the first two
independent variables after an immediately preceding {cmd:regress}. If
{cmd:coefs} is specified without {it:xvar}, then the {it:_cons} in
{cmd:regress} is used for {it:xvar}.   


{title:Options}

{p 4 8 2}{cmd:means} | {cmd:coefs} specifies how to center the 
confidence ellipse. The default, and the {cmd:means} option uses two variable
means, whereas {cmd:coefs} uses the first two regression coefficients from an
immediately preceding {cmd:regress}. Default subtitles are "Means centered"
and "Coefficient centered", respectively. If you restricted {cmd:regress} to a
portion of the data using {cmd:if} or {cmd:in}, then you will generally want to
use the same conditions with {cmd:coefs}. coefs is not allowed with
{cmd:by}{cmd:(}{cmd:)}, because it would be misleading, since Stata only
remembers the last set of estimates. 

{p 4 8 2}{cmd:pool}{cmd:(}{it:#}{cmd:)} displays a confidence ellipse labeled
"pooled ellipse, bp" using all the data, a confidence ellipse labeled
"best subset ellipse, b" using a theoretically unproblematic subset, and
a connected curve labeled "fractionally pooled curve" with # connecting
lines. {cmd:pool}{cmd:(}{cmd:)} must be used with {cmd:if} or {cmd:in}, and with 
{cmd:coefs}. {cmd:pool}{cmd:(}{cmd:)} is incompatible with 
{cmd:by}{cmd:(}{cmd:)}, {cmd:diameter}{cmd:(}{cmd:)}, and
{cmd:evr}{cmd:(}{cmd:)}. {cmd:formula}{cmd:(}{cmd:)} is ignored. See Alexandersson (1998) for examples.

{p 4 8 2}{cmd:plopts}{cmd:(}{it:line_options}{cmd:)}, to be used with 
{cmd:pool()}, affect the rendition of the pooled line; see {help line_options}.

{p 4 8 2}{cmd:pcopts}{cmd:(}{it:connect_options}{cmd:)}, to be used with 
{cmd:pool()}, affect the rendition of the connecting points in the pooled line;
see {help connect_options}. Sort options are ignored.

{p 4 8 2}{cmd:constant}{cmd:(}{it:statname} [{it:#}] | {it:#}{cmd:)} 
specifies the boundary constant c. The overall and {cmd:means} default is
{cmd:c}{cmd:(}{it:4}{cmd:)} and
corresponds to a joint confidence interval of 1 - exp^(-#/2) * 100, or 86%. The
{cmd:coefs} default is {cmd:c}{cmd:(}{it:f 2}{cmd:)}. Available statnames are:

{p 8 22 2}{it:statname} {space 2} definition of statname; calculation of c{p_end}
	{hline 61}
{p 8 22 2}{cmd:sd} {space 8} Standard deviation; c = #^2.{p_end}
{p 8 22 2}{space 11} Confidence level is 1 - exp^(-(#^2)/2) * 100.{p_end}
{p 8 22 2}{space 11} sd cannot be used with level().{p_end}
{p 8 22 2}{cmd:t2} {space 8} Hotelling's  T2 / n; c = #(n-1)/(n-#) * F.{p_end}
{p 8 22 2}{cmd:pt2} {space 7} prediction T2; c = t2 * (n+1) / n.{p_end}
{p 8 22 2}{cmd:chi2} {space 6} Chi-squared; c = chi2(#).{p_end}
{p 8 22 2}{cmd:chi2_n} {space 4} sample-adjusted chi2; c = chi2(#) / n.{p_end}
{p 8 22 2}{cmd:pchi2_n} {space 3} Prediction chi2_n; c = chi2(#) / n * (n + 1).{p_end}
{p 8 22 2}{cmd:f} {space 9} Multiplier-fixed F; c = 2 * F(#,n-#).{p_end}
{p 8 22 2}{cmd:f_scheffe} {space 1} Scheffe-adjusted F; c = # * F(#,n-#).{p_end}
{p 8 22 2}{cmd:fadj} {space 6} Denominator-adjusted F; c = 2 * F(2,n-#).{p_end}

{p 4 8 2}{cmd:level}{cmd:(}{it:#}{cmd:)} specifies the confidence level, in 
percent, for calculation of the confidence ellipse; the default {it:#} is
95. {cmd:level}{cmd:(}{cmd:)} cannot be used with {cmd:constant}{cmd:(}{it:sd}{cmd:)}.

{p 4 8 2}{cmd:formula}{cmd:(}{it:acosr} | {it:theta}{cmd:)} is included only for the
curious users to show that two seemingly different formulas are
equivalent. {cmd:formula}{cmd:(}{it:acosr}{cmd:)} is based on the angular distance,
acos(r), and on the amplitudes. {cmd:formula}{cmd:(}{it:theta}{cmd:)} is based on
the rotation angle of the major axis against the x-axis, theta, and on the
semi-major and semi-minor axes, a and b. {cmd:formula}{cmd:(}{it:acosr}{cmd:)} is
the default. 

{p 4 8 2}{cmd:generate}{cmd:(}{it:ynewvar} {it:xnewvar}{cmd:)} generates two
new variables, {it:ynewvar} and {it:xnewvar}, which define the confidence
ellipse. If the current dataset contains fewer observations than in 
{cmd:npoints}{cmd:(}{cmd:)}, then the length of the dataset will be expanded
accordingly with missing values, even if ynewvar and xnewvar are temporary
variables, and a warning message is displayed. {cmd:generate}{cmd:(}{cmd:)}
cannot be used with {cmd:by}{cmd:(}{cmd:)}.

{p 4 8 2}{cmd:nograph} specifies to not construct a graph. In contrast,
the built-in nodraw option merely suppresses the display of the graph. {cmd:nograph}
is often used together with {cmd:generate}{cmd:(}{cmd:)}.

{p 4 8 2}{cmd:replace} replaces any existing variables in 
{cmd:generate}{cmd:(}{cmd:)}.

{p 4 8 2}{cmd:evr}{cmd:(}{it:#}{cmd:)} specifies the error variance ratio #
of {it:yvar} to {it:xvar}, where # is a floating point number between 0 and
99999. The default is 1. The ratio 0 corresponds to regression of x on y, 1 
corresponds to orthogonal regression and the major axis, and a very large
number, say 99999, corresponds to regression of y on x. See McCartin (2003).

{p 4 8 2}{cmd:from}{cmd:(}{it:#}{cmd:)} specifies the value from which the
ellipse parameter runs. The default is 0. You only need to specify this option
if you do not want to display the beginning of an ellipse.

{p 4 8 2}{cmd:to}{cmd:(}{it:#}{cmd:)} specifies the value to which the
ellipse parameter runs. The default is 2 pi. You only need to specify this option if
you do not want to display the end of an ellipse. If {cmd:from}{cmd:(}{cmd:)} is
smaller than {cmd:to}{cmd:(}{cmd:)}, as by default, the parameter runs
clockwise. Otherwise, the parameter runs counter-clockwise.

{p 4 8 2}{cmd:overlay}, to be used with {cmd:by}{cmd:(}{cmd:)}, creates an 
overlaid graph for all by-groups. {cmd:overlay} cannot be used with
 {cmd:by}{cmd:(}{it:..., total}{cmd:)}. 

{p 4 8 2}{cmd:total}, to be used with {cmd:by}{cmd:(}{cmd:)}, adds an extra
by-group with a confidence ellipse for the entire dataset. 

{p 4 8 2}{cmd:tlabel}{cmd:(}{it:label}{cmd:)}, to be used with {cmd:total}, adds
a user-specified label for the by-graph produced by the option total. The default
label is "Total". 

{p 4 8 2} {cmd:diameter}{cmd:(}{it:#}{cmd:)} adds a diameter of the ellipse with
slope -99999 <= {it:#} <= 99999. A diameter of the ellipse is any chord through
the center of the ellipse. The option is incompatible with
{cmd:pool}{cmd:(}{cmd:)}.

{p 4 8 2}{cmd:rlopts}{cmd:(}{it:line_options}{cmd:)}, to be used with 
{cmd:refline()}, affect the rendition of the reference line; see
{help line_options}.

{p 4 8 2}{cmd:plot}{cmd:(}{it:plot}{cmd:)} provides a way to add other plots
to the generated graph; see help {help plot_option}. By default, when this
option is specified, the legend appears; see help {help legend_option}. By
default the descriptive text in the legend is obtained from the y-variables'
variable labels. Examples of such plots are another confidence ellipse, a
regression line, inscribing reference lines, a scatter plot of {it:yvar} and
{it:xvar} and of the midpoint. 

{p 4 8 2}
{it:connect_options} are any of the options documented in help
{help connect_options}. The options {cmd:sort}[{cmd:(}{it:varlist}{cmd:)}] and
{cmd:cmissing(}{c -(}{cmd:y}|{cmd:n}{c )-} ...{cmd:)} are ignored. The
default is {cmd:cmissing(}{cmd:n} ...{cmd:)}, meaning that ellipses are not
connected to each other.

{p 4 8 2}
{it:twoway_options} are any of the options documented in help
{help twoway_options}. These include options for titling the graph
(see help {help title_options}), options for saving the graph to disk
(see help {help saving_option}), and the {cmd:by()} option
(see help {help by_option}). The {cmd:by()} option is incompatible
with the option {cmd:pool}{cmd:(}{cmd:)}. 
{cmd:by}{cmd:(}{it:..., total}{cmd:)} adds an extra by-group for all by-groups
combined; it may not be used with the option {cmd:overlay}. 


{title:Remarks}

{p 4 4 2}This is version 2 of {cmd:ellip}, see Alexandersson (1998). 
Two of the most notable new features are the feature to graph confidence
ellipses around variable means, and the feature to add inscribed lines. These
features allow a geometric characterization of linear regression with unequal
error variances, as in McCartin (2003). To access the dialogs interactively, 
type {cmd: db ellip} or see help {help ellip_dlg}. To create menu items
permanently, copy these lines to {bf:profile.do}:


    {cmd: if _caller() > 7 {c -(}}
    {cmd:     if "`c(console)'"=="" {c -(}}
    {cmd:         window menu append submenu "stUserGraphics" "Confidence Ellipses"}
    {cmd:         window menu append item "Confidence Ellipses" ///}
    {cmd:             "for Means" "db ellip_means"}
    {cmd:         window menu append item "Confidence Ellipses" ///}
    {cmd:             "for Regression Coefficients" "db ellip_coefs"}
    {cmd:     {c )-}}
    {cmd: {c )-}}


    Results are saved in r(); see help {help return list}.


{title:Examples}

{p 4 8 2}
{* how to "click to run" for several commands as in gr_example2.ado?}
    {cmd:. sysuse auto, clear}

    {cmd:. ellip mpg weight} {space 12} // graph the default ellipse with c(4)
      {it:({stata "gr_example auto:ellip mpg weight":click to run})}
	  
    {cmd:. ellip mpg weight, g(ey ex)} {space 3}// also generate the ellipse variables

    {cmd:. ellip mpg weight, c(t2) plot(line ey ex)}
          // overlaid graph of 95% T2 and default ellipses

    {cmd:. reg mpg weight}
    
    {cmd:. ellip weight, coefs c(chi2)}
          // 95% Chi-square confidence ellipse around _b[weight] and _b[_cons]
	  
{p 4 4 2}
Many more examples are available in a test script package on SSC. To find out
details: {stata ssc describe ellip:ssc describe ellip}. To
download: {stata ssc install ellip:ssc install ellip} and
{stata net get ellip:net get ellip}.    
    

{title:Author}    

        Anders Alexandersson, Mississippi State University, USA
        Email: {browse "mailto:aa1@msstate.edu":aa1@msstate.edu}.  
   
   
{title:References}

{p 4 8 2}Alexandersson, A. 1998. gr32: Confidence 
ellipses. {it:Stata Technical Bulletin} 46: 10-13. In
{it:Stata Technical Bulletin Reprints}, vol. 8, 54-57. College Station, TX: Stata
Press. 

{p 4 8 2}McCartin, B. 2003. A Geometric Characterization of Linear 
Regression. {it:Statistics: A Journal of Theoretical and Applied Statistics} 
37(2): 101-117.


{title:Also see}

{p 4 13 2}Manual:  {hi:[G] graph twoway}, {hi:[G] graph twoway line} 

{p 4 13 2}Online:  help for {help graph_twoway}, {help line}
