.-
help for ^bvnellip^                                                    (vers 1.1)
.-

joint confidence region (ellipse) for 2 parameters
--------------------------------------------------

    ^bvnellip^ [var1 var2] [^if^ exp] [^in^ range]^,^ ^pl^otvrs^(^newvar1 newvar2^)^
         [^cov^ar^(^matname^)^ ^b^eta^(^matname^)^ ^df(^#^)^ ^sor^tvar^(^newvar^)^ ^replace^
          ^l^evel^(^#^)^ ^np^oints^(^#^)^ ]


Description
-----------

^bvnellip^ calculates a confidence ellipse for the joint distribution of two
parameters.  The parameters are assumed to have a bivariate normal distribution.

Either a 2x1 vector of parameter estimates and 2x2 covariance matrix OR
variable names for two existing variables must be supplied.  If existing
variables are supplied as arguments the confidence region is calculated
for the joint distribution of the variable means.

Names for two new variables to hold ellipse coordinates must be supplied in
^plotvrs()^.

returned results include means for var1 and var2 if variables are supplied.
(otherwise the supplied parameter estimates are returned here):
    r(beta1)
    r(beta2)


Options
-------

^var1 var2^ are variable names of the two variables for which the joint mean and
    confidence region is to be calculated.  If these are not specified the
    covariance matrix ^covar()^, parameter vector ^beta()^, and ^df()^ arguments must
    be supplied.

^covar(^matrix name^)^ alternatively specifies the name of the 2x2 covariance
    matrix for two parameters.  The ^beta()^ vector of parameter estimates and
    denominator degrees of freedom ^df()^ must also be supplied when this option
    is chosen over specification of the variables.

^beta(^matrix name^)^ specifies the name of a 2x1 matrix containing the 2
    parameter estimates.  Used in combination with ^covar()^ and ^df()^ options.

^df(^#^)^ specifies the denominator degrees of freedom for the standard F-test of
    Ho: beta1 = beta2 = 0; usually n-2.  Used in combination with ^covar()^ and
    ^beta()^ options.

^plotvrs(^varname1 varname2^)^ specifies names for 2 new variables to hold plot
    coordinates for the confidence ellipse.  This is not optional.

^sortvar(^newvarname^)^ is an option included for plotting purposes.  It specifies
    the name of a new variable, which when used for sorting, will order the
    corresponding plotvar coordinates for correct line connection.

^replace^ requests that if existing variables are specified for ^plotvrs()^ or
    ^sortvar()^, they should be overwritten.

^level^ specifies the confidence level, in percent, for calculation of the
    confidence region;  see help @level@.

^npoints(^#^)^ specifies the number of points to be calculated for the confidence
    ellipse.  The default is 200.


Remarks
-------

If the current dataset contains fewer observations than the number of points
specified in ^npoints()^ then the length of the dataset will be expanded
accordingly.

Similar in purpose to Anders Alexandersson's -ellip- (and uses same parametric
form for ellipse).  However, -ellip- was written to provide joint conf region
for 2 parameters in a regression framework and requires a prior regression fit.


References
----------

  Douglas, JB.  "Confidence regions for parameter pairs".
       American Statistician 47(1) 43-45, 1993.

  Weisberg, S.  Applied linear regression.  Wiley & Sons, 2nd ed., New York,
       1985.  p 97-99.


Author
------

        Gary Longton, Fred Hutchinson Cancer Research Ctr.
        glongton@@fhcrc.org


Also see
--------

    @ellip@ if installed, gr32 (STB-46)