# Ellipses

From car v2.0-20
by John Fox

##### 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=palette()[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)) palette()[1:2] else palette()[1:length(group.levels)],
pch = if (missing(groups)) 1 else seq(group.levels), lwd = 2,
fill = FALSE, fill.alpha = 0.3, grid = TRUE, labels, id.method = "mahal",
id.n = if (id.method[1] == "identify") Inf else 0, id.cex = 1,
id.col = if (missing(groups)) palette()[1] else palette()(1:length(groups)),
...)
confidenceEllipse(model, ...)
## S3 method for class 'lm':
confidenceEllipse(model, which.coef, L, levels=0.95, Scheffe=FALSE, dfn,
center.pch=19, center.cex=1.5, segments=51, xlab, ylab,
col=palette()[2], lwd=2, fill=FALSE, fill.alpha=0.3, draw=TRUE, add=!draw, ...)
## S3 method for class 'glm':
confidenceEllipse(model, chisq, ...)
## S3 method for class 'default':
confidenceEllipse(model, which.coef, L, levels=0.95, Scheffe=FALSE, dfn,
center.pch=19, center.cex=1.5, segments=51, xlab, ylab,
col=palette()[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"`

- 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 - 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 theMASS 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.
- 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`

arg - 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 - 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 resp - col
- color for lines and ellipse center; the default is the
*second*entry in the current color palette (see`palette`

and`par`

). For < - 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 symb - 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`

. - labels,id.method,id.n,id.cex,id.col
- Arguments for the labelling of
points. The default is
`id.n=0`

for labeling no points. See`showLabels`

for details of these arguments. - 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. (2008)
*Applied Regression Analysis and Generalized Linear Models*,
Second Edition. Sage.
Fox, J. and Weisberg, S. (2011)
*An R Companion to Applied Regression*, Second 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

```
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),
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.n=2, pch=15:17,
labels=rownames(Prestige), 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 2.0-20, License: GPL (>= 2)*

### Community examples

Looks like there are no examples yet.