car (version 2.1-0)

Ellipses: Ellipses, Data Ellipses, and Confidence Ellipses

Description

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

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.

Details

The ellipse is computed by suitably transforming a unit circle. dataEllipse superimposes the normal-probability contours over a scatterplot of the data.

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

cov.trob, cov.wt, linearHypothesis.

Examples

Run this code
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))

Run the code above in your browser using DataCamp Workspace