Graphing confidence ellipses [An update of ellip for Stata 8]
ellip yvar xvar [if exp] [in range] [, means common_options ]
ellip yvar [xvar] [if exp] [in range] , coefs [pool(#) [plopts(line_options) pcopts(connect_options)] common_options ]
where common_options are:
constant(statname [#] | #) level(#) formula(acosr | theta) generate(ynewvar xnewvar) nograph replace evr(#) from(#) to(#) npoints(#) overlay total [tlabel(label)] diameter(#) [dlopts(line_options)] plot(plot) connect_options twoway_options
Description
ellip calculates a confidence ellipse from the elliptically distributed variables yvar and xvar, and then graphs the confidence ellipse using graph twoway line. By default, or if the option means is specified, yvar and xvar are data variables. If the option coefs is specified, yvar and xvar are the first two independent variables after an immediately preceding regress. If coefs is specified without xvar, then the _cons in regress is used for xvar.
Options
means | coefs specifies how to center the confidence ellipse. The default, and the means option uses two variable means, whereas coefs uses the first two regression coefficients from an immediately preceding regress. Default subtitles are "Means centered" and "Coefficient centered", respectively. If you restricted regress to a portion of the data using if or in, then you will generally want to use the same conditions with coefs. coefs is not allowed with by(), because it would be misleading, since Stata only remembers the last set of estimates.
pool(#) 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. pool() must be used with if or in, and with coefs. pool() is incompatible with by(), diameter(), and evr(). formula() is ignored. See Alexandersson (1998) for examples.
plopts(line_options), to be used with pool(), affect the rendition of the pooled line; see line_options.
pcopts(connect_options), to be used with pool(), affect the rendition of the connecting points in the pooled line; see connect_options. Sort options are ignored.
constant(statname [#] | #) specifies the boundary constant c. The overall and means default is c(4) and corresponds to a joint confidence interval of 1 - exp^(-#/2) * 100, or 86%. The coefs default is c(f 2). Available statnames are:
statname definition of statname; calculation of c ------------------------------------------------------------- sd Standard deviation; c = #^2. Confidence level is 1 - exp^(-(#^2)/2) * 100. sd cannot be used with level(). t2 Hotelling's T2 / n; c = #(n-1)/(n-#) * F. pt2 prediction T2; c = t2 * (n+1) / n. chi2 Chi-squared; c = chi2(#). chi2_n sample-adjusted chi2; c = chi2(#) / n. pchi2_n Prediction chi2_n; c = chi2(#) / n * (n + 1). f Multiplier-fixed F; c = 2 * F(#,n-#). f_scheffe Scheffe-adjusted F; c = # * F(#,n-#). fadj Denominator-adjusted F; c = 2 * F(2,n-#).
level(#) specifies the confidence level, in percent, for calculation of the confidence ellipse; the default # is 95. level() cannot be used with constant(sd).
formula(acosr | theta) is included only for the curious users to show that two seemingly different formulas are equivalent. formula(acosr) is based on the angular distance, acos(r), and on the amplitudes. formula(theta) 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. formula(acosr) is the default.
generate(ynewvar xnewvar) generates two new variables, ynewvar and xnewvar, which define the confidence ellipse. If the current dataset contains fewer observations than in npoints(), 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. generate() cannot be used with by().
nograph specifies to not construct a graph. In contrast, the built-in nodraw option merely suppresses the display of the graph. nograph is often used together with generate().
replace replaces any existing variables in generate().
evr(#) specifies the error variance ratio # of yvar to 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).
from(#) 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.
to(#) 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 from() is smaller than to(), as by default, the parameter runs clockwise. Otherwise, the parameter runs counter-clockwise.
overlay, to be used with by(), creates an overlaid graph for all by-groups. overlay cannot be used with by(..., total).
total, to be used with by(), adds an extra by-group with a confidence ellipse for the entire dataset.
tlabel(label), to be used with total, adds a user-specified label for the by-graph produced by the option total. The default label is "Total".
diameter(#) adds a diameter of the ellipse with slope -99999 <= # <= 99999. A diameter of the ellipse is any chord through the center of the ellipse. The option is incompatible with pool().
rlopts(line_options), to be used with refline(), affect the rendition of the reference line; see line_options.
plot(plot) provides a way to add other plots to the generated graph; see help plot_option. By default, when this option is specified, the legend appears; see 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 yvar and xvar and of the midpoint.
connect_options are any of the options documented in help connect_options. The options sort[(varlist)] and cmissing({y|n} ...) are ignored. The default is cmissing(n ...), meaning that ellipses are not connected to each other.
twoway_options are any of the options documented in help twoway_options. These include options for titling the graph (see help title_options), options for saving the graph to disk (see help saving_option), and the by() option (see help by_option). The by() option is incompatible with the option pool(). by(..., total) adds an extra by-group for all by-groups combined; it may not be used with the option overlay.
Remarks
This is version 2 of 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 db ellip or see help ellip_dlg. To create menu items permanently, copy these lines to profile.do:
if _caller() > 7 { if "`c(console)'"=="" { window menu append submenu "stUserGraphics" "Confidence Ellipses" window menu append item "Confidence Ellipses" /// "for Means" "db ellip_means" window menu append item "Confidence Ellipses" /// "for Regression Coefficients" "db ellip_coefs" } }
Results are saved in r(); see help return list.
Examples
. sysuse auto, clear
. ellip mpg weight // graph the default ellipse with c(4) (click to run) . ellip mpg weight, g(ey ex) // also generate the ellipse variables
. ellip mpg weight, c(t2) plot(line ey ex) // overlaid graph of 95% T2 and default ellipses
. reg mpg weight . ellip weight, coefs c(chi2) // 95% Chi-square confidence ellipse around _b[weight] and _b[_cons] Many more examples are available in a test script package on SSC. To find out details: ssc describe ellip. To download: ssc install ellip and net get ellip.
Author
Anders Alexandersson, Mississippi State University, USA Email: aa1@msstate.edu. References
Alexandersson, A. 1998. gr32: Confidence ellipses. Stata Technical Bulletin 46: 10-13. In Stata Technical Bulletin Reprints, vol. 8, 54-57. College Station, TX: Stata Press.
McCartin, B. 2003. A Geometric Characterization of Linear Regression. Statistics: A Journal of Theoretical and Applied Statistics 37(2): 101-117.
Also see
Manual: [G] graph twoway, [G] graph twoway line