# Ellipses

##### Ellipses, Data Ellipses, and Confidence Ellipses

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

##### Usage

```
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, ...)

##### Arguments

- 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
a numeric vector of weights, of the same length as

`x`

and`y`

to be used by`cov.wt`

or`cov.trob`

in computing a weighted covariance matrix; if absent, weights of`1`

are used.- 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

##### Details

The ellipse is computed by suitably transforming a unit circle.

`dataEllipse`

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

##### Value

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`

.

##### References

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.

##### See Also

##### Examples

```
# 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))
# }
```

*Documentation reproduced from package car, version 3.0-4, License: GPL (>= 2)*