These functions draw ellipses, including data ellipses, and confidence ellipses for linear, generalized linear, and possibly other models.

```
ellipse(center, shape, radius, log="", center.pch=19, center.cex=1.5,
segments=51, draw=TRUE, add=draw, xlab="", ylab="",
col=carPalette()[2], lwd=2, fill=FALSE, fill.alpha=0.3, grid=TRUE, ...)
```dataEllipse(x, y, groups, group.labels=group.levels, ellipse.label,
weights, log="", levels=c(0.5, 0.95), center.pch=19,
center.cex=1.5, draw=TRUE, plot.points=draw, add=!plot.points, segments=51,
robust=FALSE, xlab=deparse(substitute(x)), ylab=deparse(substitute(y)),
col=if (missing(groups)) carPalette()[1:2] else carPalette()[1:length(group.levels)],
pch=if (missing(groups)) 1 else seq(group.levels),
lwd=2, fill=FALSE, fill.alpha=0.3, grid=TRUE, id=FALSE, ...)

confidenceEllipse(model, ...)

# S3 method for lm
confidenceEllipse(model, which.coef, vcov.=vcov,
L, levels=0.95, Scheffe=FALSE, dfn,
center.pch=19, center.cex=1.5, segments=51, xlab, ylab,
col=carPalette()[2], lwd=2, fill=FALSE, fill.alpha=0.3, draw=TRUE, add=!draw, ...)
# S3 method for glm
confidenceEllipse(model, chisq, ...)

# S3 method for default
confidenceEllipse(model, which.coef, vcov.=vcov,
L, levels=0.95, Scheffe=FALSE, dfn,
center.pch=19, center.cex=1.5, segments=51, xlab, ylab,
col=carPalette()[2], lwd=2, fill=FALSE, fill.alpha=0.3, draw=TRUE, add=!draw, ...)

center

2-element vector with coordinates of center of ellipse.

shape

\(2\times 2\) shape (or covariance) matrix.

radius

radius of circle generating the ellipse.

log

when an ellipse is to be added to an existing plot, indicates
whether computations were on logged values and to be plotted on logged
axes; `"x"`

if the x-axis is logged, `"y"`

if the y-axis is
logged, and `"xy"`

or `"yx"`

if both axes are logged. The
default is `""`

, indicating that neither axis is logged.

center.pch

character for plotting ellipse center; if `FALSE`

or `NULL`

the center point isn't plotted.

center.cex

relative size of character for plotting ellipse center.

segments

number of line-segments used to draw ellipse.

draw

if `TRUE`

produce graphical output; if `FALSE`

, only invisibly return coordinates of ellipse(s).

add

if `TRUE`

add ellipse(s) to current plot.

xlab

label for horizontal axis.

ylab

label for vertical axis.

x

a numeric vector, or (if `y`

is missing) a 2-column numeric matrix.

y

a numeric vector, of the same length as `x`

.

groups

optional: a factor to divide the data into groups; a separate ellipse will be plotted for each group (level of the factor).

group.labels

labels to be plotted for the groups; by default, the levels of the `groups`

factor.

ellipse.label

a label for the ellipse(s) or a vector of labels; if several ellipses are drawn and just one label is given, then that label will be repeated. The default is not to label the ellipses.

weights

plot.points

if `FALSE`

data ellipses are drawn,
but points are not plotted.

levels

draw elliptical contours at these (normal) probability or confidence levels.

robust

if `TRUE`

use the `cov.trob`

function in the MASS package
to calculate the center and covariance matrix for the data ellipse.

model

a model object produced by `lm`

or `glm`

.

which.coef

2-element vector giving indices of coefficients to plot; if missing, the first two coefficients (disregarding the regression constant) will be selected.

vcov.

a coefficient-covariance matrix or a function (such as `hccm`

) to
compute the coefficent-covariance
matrix from `model`

; the default is the `vcov`

function.

L

As an alternative to selecting coefficients to plot, a transformation matrix can be specified to compute two
linear combinations of the coefficients; if the `L`

matrix is given, it takes precedence over the `which.coef`

argument. `L`

should have two rows and as many columns as there are coefficients. It can be given directly as a
numeric matrix, or specified by a pair of character-valued expressions, in the same manner as for the
`link{linearHypothesis}`

function, but with no right-hand side.

Scheffe

if `TRUE`

scale the ellipse so that its projections onto the
axes give Scheffe confidence intervals for the coefficients.

dfn

``numerator'' degrees of freedom (or just degrees of freedom for a GLM) for
drawing the confidence ellipse. Defaults to the number of coefficients in the model (disregarding the constant) if
`Scheffe`

is `TRUE`

, or to `2`

otherwise; selecting `dfn = 1`

will
draw the ``confidence-interval generating'' ellipse, with projections on the axes
corresponding to individual confidence intervals with the stated level of coverage.

chisq

if `TRUE`

, the confidence ellipse for the coefficients in a generalized linear model are
based on the chisquare statistic, if `FALSE`

on the $F$-statistic. This corresponds to using the default
and linear-model methods respectively.

col

color for lines and ellipse center; the default is the *second* entry
in the current car palette (see `carPalette`

and `par`

). For `dataEllipse`

, two colors can be given, in
which case the first is for plotted points and the second for lines and the ellipse center;
if ellipses are plotted for `groups`

, then this is a vector of colors for the groups.

pch

for `dataEllipse`

this is the plotting character (default, symbol `1`

, a hollow circle)
to use for the points; if ellipses are plotted by `groups`

, then this a vector of plotting characters,
with consecutive symbols starting with `1`

as the default.

lwd

line width; default is `2`

(see `par`

).

fill

fill the ellipse with translucent color `col`

(default, `FALSE`

)?

fill.alpha

transparency of fill (default = `0.3`

).

…

other plotting parameters to be passed to `plot`

and
`line`

.

id

controls point identification; if `FALSE`

(the default), no points are identified;
can be a list of named arguments to the `showLabels`

function;
`TRUE`

is equivalent to `list(method="mahal", n=2, cex=1, col=carPalette()[1], location="lr")`

(with the default `col`

actually dependent on the number of groups),
which identifies the 2 points with the largest Mahalanobis distances from the center of the data.

grid

If TRUE, the default, a light-gray background grid is put on the graph

These functions are mainly used for their side effect of producing plots. For
greater flexibility (e.g., adding plot annotations), however, `ellipse`

returns invisibly the (x, y) coordinates of the calculated ellipse.
`dataEllipse`

and `confidenceEllipse`

return invisibly the coordinates of one or more ellipses, in the latter instance a list named by
`levels`

.

The ellipse is computed by suitably transforming a unit circle.

`dataEllipse`

superimposes the normal-probability contours over a scatterplot
of the data.

Fox, J. (2016)
*Applied Regression Analysis and Generalized Linear Models*,
Third Edition. Sage.

Fox, J. and Weisberg, S. (2019)
*An R Companion to Applied Regression*, Third Edition, Sage.

Monette, G. (1990)
Geometry of multiple regression and 3D graphics.
In Fox, J. and Long, J. S. (Eds.)
*Modern Methods of Data Analysis.* Sage.

# NOT RUN { dataEllipse(Duncan$income, Duncan$education, levels=0.1*1:9, ellipse.label=0.1*1:9, lty=2, fill=TRUE, fill.alpha=0.1) confidenceEllipse(lm(prestige~income+education, data=Duncan), Scheffe=TRUE) confidenceEllipse(lm(prestige~income+education, data=Duncan), vcov.=hccm) confidenceEllipse(lm(prestige~income+education, data=Duncan), L=c("income + education", "income - education")) wts <- rep(1, nrow(Duncan)) wts[c(6, 16)] <- 0 # delete Minister, Conductor with(Duncan, { dataEllipse(income, prestige, levels=0.68) dataEllipse(income, prestige, levels=0.68, robust=TRUE, plot.points=FALSE, col="green3") dataEllipse(income, prestige, weights=wts, levels=0.68, plot.points=FALSE, col="brown") dataEllipse(income, prestige, weights=wts, robust=TRUE, levels=0.68, plot.points=FALSE, col="blue") }) with(Prestige, dataEllipse(income, education, type, id=list(n=2, labels=rownames(Prestige)), pch=15:17, xlim=c(0, 25000), center.pch="+", group.labels=c("Blue Collar", "Professional", "White Collar"), ylim=c(5, 20), level=.95, fill=TRUE, fill.alpha=0.1)) # }