Next: findcontour() Up: Graphics Macros Help File Previous: contourplot()   Contents


ellipse(K, Q [,x0] [,npoints:m] [method:j] [,draw:T] \
  [,graphics keyword phrases]), REAL scalar K > 0, 2 by 2
  positive definite symmetric REAL matrix Q, REAL vector x0 or length
  2, integer j, 1 <= j <= 3

Keywords: shapes, line graphs
You can use ellipse() to compute and optionally draw an ellipse with
shape defined by a specified positive definite matrix and centered at a
specified point

ellipse(K, Q [,x0] [,graphics keywords]) computes xvals and yvals, the
x- and y-coordinates of points on the ellipse defined by the equation
        (x - x0)' %*% solve(Q) %*% (x - x0) = K^2
The value returned is structure(x:xvals,y:yvals [,graphics keywords]).

K > 0 must be a REAL scalar and Q must be a 2 by 2 REAL positive
definite symmetric matrix.  If x0 is an argument, it must be a REAL
vector of length 2.  Otherwise, rep(0,2) is used for x0.

The ellipse can be plotted by
  Cmd> result <- ellipse(K, Q [,x0] [,graphics keywords])

  Cmd> lineplot(keys:result)

ellipse(K, Q [,x0], draw:T [,graphics keywords]) draws the ellipse
directly and doesn't return the coordinates as a value.  If the ellipse
is to be added to an existing graph, include add:T as an argument.

ellipse(K, Q [,x0], npoints:m ...) computes m + 1 points on the
ellipse, with the first and last being identical.  The default value
for m is 200.

There are several ways to select points on an ellipse.  Macro ellipse()
allows you to use any of three methods.

ellipse(K, Q [,x0], method:k ...), where 1 <= k <= 3, does the same,
except the way xvals and yvals are computed depends on k (default is k
= 3).

All three methods compute unit vectors u(theta) for m+1 equally
spaced values of theta from 0 to 360 degrees, where
  u(theta) = vector(cos(theta), sin(theta))

Method 1 (Pure polar coordinates):
  x(theta) = x0 + K * u(theta)/r1(theta),
    r1(theta) = sqrt(u(theta)' %*% solve(Q) %*% u(theta))
Method 2
  x(theta) = x0 + K * Q %*% u(theta)/r2(theta), where
    r2(theta) = sqrt(u(theta)' %*% Q %*% u(theta))
Method 3 (default)
  x(theta) = x0 + K*cholesky(Q)' %*% u(theta)

The default method (3) seems to do the best job, but you may want to
try one of the others to see if they produce a better looking ellipse.

See also 'graph_keys', lineplot(), cholesky(), solve(), 'matrices'

Gary Oehlert 2003-01-15