rgl (version 1.3.1)

ellipse3d: Make an ellipsoid

Description

A generic function and several methods returning an ellipsoid or other outline of a confidence region for three parameters.

Usage

ellipse3d(x, ...)
# S3 method for default
ellipse3d(x, scale = c(1, 1, 1), centre = c(0, 0, 0), level = 0.95, 
	t = sqrt(qchisq(level, 3)), which = 1:3, subdivide = 3, smooth = TRUE, ...)
# S3 method for lm
ellipse3d(x, which = 1:3, level = 0.95, t = sqrt(3 * qf(level, 
                                                3, x$df.residual)), ...)     
# S3 method for glm
ellipse3d(x, which = 1:3, level = 0.95, t, dispersion, ...) 
# S3 method for nls
ellipse3d(x, which = 1:3, level = 0.95, t = sqrt(3 * qf(level, 
                                                3, s$df[2])), ...)

Value

A mesh3d object representing the ellipsoid.

Arguments

x

An object. In the default method the parameter x should be a square positive definite matrix at least 3x3 in size. It will be treated as the correlation or covariance of a multivariate normal distribution.

...

Additional parameters to pass to the default method or to qmesh3d.

scale

If x is a correlation matrix, then the standard deviations of each parameter can be given in the scale parameter. This defaults to c(1, 1, 1), so no rescaling will be done.

centre

The centre of the ellipse will be at this position.

level

The confidence level of a simultaneous confidence region. The default is 0.95, for a 95% region. This is used to control the size of the ellipsoid.

t

The size of the ellipse may also be controlled by specifying the value of a t-statistic on its boundary. This defaults to the appropriate value for the confidence region.

which

This parameter selects which variables from the object will be plotted. The default is the first 3.

subdivide

This controls the number of subdivisions (see subdivision3d) used in constructing the ellipsoid. Higher numbers give a smoother shape.

smooth

If TRUE, smooth interpolation of normals is used; if FALSE, a faceted ellipsoid will be displayed.

dispersion

The value of dispersion to use. If specified, it is treated as fixed, and chi-square limits for t are used. If missing, it is taken from summary(x).

Examples

# Plot a random sample and an ellipsoid of concentration corresponding to a 95% 
# probability region for a
# trivariate normal distribution with mean 0, unit variances and 
# correlation 0.8.
if (requireNamespace("MASS", quietly = TRUE)) {
  Sigma <- matrix(c(10, 3, 0, 3, 2, 0, 0, 0, 1), 3, 3)
  Mean <- 1:3
  x <- MASS::mvrnorm(1000, Mean, Sigma)
  
  open3d()
  
  plot3d(x, box = FALSE)
  
  plot3d( ellipse3d(Sigma, centre = Mean), col = "green", alpha = 0.5, add = TRUE)
}  

# Plot the estimate and joint 90% confidence region for the displacement and cylinder
# count linear coefficients in the mtcars dataset

data(mtcars)
fit <- lm(mpg ~ disp + cyl , mtcars)

open3d()
plot3d(ellipse3d(fit, level = 0.90), col = "blue", alpha = 0.5, aspect = TRUE)