Generalized ellipsoids

Description

Represents generalized ellipsoids with the "(U,D)" representation, allowing both degenerate and unbounded ellipsoids, together with methods for linear and duality transformations, and for plotting. This permits exploration of a variety to statistical issues that can be visualized using ellipsoids as discussed by Friendly, Fox & Monette (2013), "Elliptical Insights: Understanding Statistical Methods and duality transformations, and for plotting. The ideas are described in Friendly, Monette & Fox (2013) doi:10.1214/12-STS402.

Details

It uses the (U, D) representation of generalized ellipsoids in R^d, where U is square orthogonal and D is diagonal with extended non-negative real numbers, i.e. 0, Inf or a positive real). These are roughly analogous to the corresponding terms in the singular-value decomposition of a matrix, X = U D V'.

The resulting class of ellipsoids includes degenerate ellipsoids that are flat and/or unbounded. Thus ellipsoids are naturally extended to include lines, hyperplanes, points, cylinders, etc.

The class is closed under linear and affine transformations (including those between spaces of different dimensions) and under duality ('inverse') transformations.

Unbounded ellipsoids, e.g. cylinders with elliptical cross-sections, correspond to singular inner products, i.e. inner products defined by a singular inner product matrix.

Flat ellipsoids correspond to singular variances. The corresponding inner product is defined only on the supporting subspace.

Ellipsoids that are both flat and unbounded correspond to lines, points, subspaces, hyperplanes, etc.

gell can currently generate the U-D representation from 5 ways of specifying an ellipsoid:

1. From the non-negative definite dispersion (variance) matrix, Sigma: U D^2 U' = \Sigma, where some elements of the diagonal matrix D can be 0. This can only generate bounded ellipsoids, possibly flat.

2. From the non-negative definite inner product matrix 'ip': U W^2 U = C where some elements of the diagonal matrix W can be 0. Then set D = W^-1 where 0^-1 = Inf. This can only generate fat (non-empty interior) ellipsoids, possibly unbounded.

3. From a subspace spanned by 'span' Let U_1 be an orthonormal basis of Span('span'), let U_2 be an orthonormal basis of the orthogonal complement, the U = [ U_1 U_2 ] and D = diag( c(Inf,...,Inf, 0,..,0)) where the number of Inf's is equal to the number of columns of U_1.

4. From a transformation of the unit sphere given by A(Unit sphere) where A = U D V', i.e. the SVD.

5. (Generalization of 4): (A, d) where A is any matrix and d is a vector of factors corresponding to columns of A. These factors can be 0, positive or Inf. In this case U and D are such that U D(Unit sphere) = A diag(d)(Unit sphere). This is the only representation that can be used for all forms of ellipsoids and in which any ellipsoid can be represented.

Author(s)

Georges Monette and Michael Friendly

Maintainer: Michael Friendly <friendly@yorku.ca>

References

Friendly, M., Monette, G. and Fox, J. (2013). Elliptical Insights: Understanding Statistical Methods through Elliptical Geometry. Statistical Science, 28(1), 1-39. Online: https://www.datavis.ca/papers/ellipses-STS402.pdf, DOI: doi:10.1214/12-STS402

See Also

dual, ellipsoid, gell, UD

Examples

(zsph <- gell(Sigma = diag(3)))  # unit sphere in R^3

(zplane <- gell(span = diag(3)[, 1:2]))  # a plane

dual(zplane)  # line orthogonal to that plane

(zhplane <- gell(center = c(0, 0, 2), span = diag(3)[, 1:2]))  # a hyperplane

dual(zhplane)  # orthogonal line through same center (note that the 'gell'
# object with a center contains more information than the geometric plane)

zorigin <- gell(span = cbind(c(0, 0, 0)))
dual(zorigin)

# signatures of these ellipsoids
signature(zsph)
signature(zhplane)
signature(dual(zhplane))

SVD, modified to return U, and D extended with 0's

Description

Calculates U and D in the (U, D) representation of a generalized ellipsoid. This uses the SVD, modified to return U, and D extended with 0's for singular matrices.

Usage

UD(x)

Arguments

Value

A list with the following components:

Author(s)

Georges Monette

See Also

svd

Examples

# None yet

Draw Basis Vectors in an rgl Scene

Description

The function calculates and optionally draws basis vectors to be used as coordinate axes in an rgl 3D display. For geometric diagrams and some data displays, this can be more useful than using axis3d or box3d to provide guides or axes. The origin argument permits multiple diagrams or graphs in the same display, each with their own coordinate axes.

Usage

basis3d(
  matrix = diag(3),
  origin = c(0, 0, 0),
  scale = 1,
  draw = TRUE,
  label = draw,
  texts = colnames(basis),
  lwd = 3,
  cex = 2,
  ...
)

Arguments

Value

Returns invisibly a 6 x 3 matrix, whose columns are the coordinate axes, c("x", "y", "z"). Odd numbered rows give the coordinates of the origin, while even numbered rows give the locations of the tips of the vectors.

Author(s)

Michael Friendly

See Also

axis3d, box3d

Examples

# show two different sets of basis vectors
open3d()
basis3d()
A <- matrix(c(1,2,0.1,
              2,1,0.1,
              0.1,0.1,0.5), 3,3)
basis3d(t(A), col="red")

# scene with two different displays
open3d()
basis3d()
basis3d(origin=c(2,0,0))

Find the bounding box of a rgl::mesh3d or rgl::qmesh3d object

Description

Ellipsoids are created by rgl functions as meshes of points, segments, ... from coordinates in various forms. This function calculates the bounding box, defined as the range of the x, y, and z coordinates.

Usage

bbox3d(x, ...)

Arguments

Value

A 2 x 3 matrix, giving the minimum and maximum values in the rows and x, y, z coordinates in the columns.

Dual or 'Inverse' of an ellipsoid

Description

dual produces the orthogonal complement for subspaces or for ellipsoids. This is equivalent to inverting \Sigma or an inner product ip when these are non-singular.

Usage

dual(x, ...)

## S3 method for class 'gell'
dual(x, ...)

Arguments

Details

At present, dual is only defined for objects of class "gell".

In the (U,D) representation, the dual simply has the columns of U in the reverse order, and the reciprocals of the diagonal elements of D, also in reverse order.

Value

A (U, D) representation of the dual, with components LIST, use

Author(s)

Georges Monette

References

Dempster, A. (1969). Elements of Continuous Multivariate Analysis Reading, MA: Addison-Wesley.

See Also

gell

Examples

(zplane <- gell(span = diag(3)[,1:2]))  # a plane

dual(zplane)  # line orthogonal to that plane

(zhplane <- gell(center = c(0,0,2), span = diag(3)[,1:2]))  # a hyperplane

dual(zhplane) # orthogonal line through same center (note that the 'gell'
              # object with a center contains more information than the geometric plane)

zorigin <- gell(span = cbind(c(0,0,0)))
dual( zorigin )

Plot Generalized Ellipsoids in 3D using rgl

Description

ell3d is a convenience wrapper for ellipsoid specialized for class "gell" objects. It plots an ellipsoid in the current rgl window.

Usage

ell3d(x, ...)

## Default S3 method:
ell3d(x, shape, radius = 1, segments = 40, shade = TRUE, wire = FALSE, ...)

## S3 method for class 'gell'
ell3d(
  x,
  length = 10,
  sides = 30,
  segments = 40,
  shade = TRUE,
  wire = FALSE,
  ...
)

Arguments

Value

Returns the result of the call to ellipsoid

Note

This implementation is subject to change.

Author(s)

Georges Monette

See Also

ellipsoid, gell

Examples

# a proper ellipsoid, and its inverse
c1 <- c(0,0,0)
C1 <- matrix(c(6, 2, 1,
               2, 3, 2,
               1, 2, 2), 3,3)

open3d()
zell1 <- gell(center=c1, Sigma=C1)
E1 <- ell3d(zell1, col="blue", alpha=0.1)
# inverse of C1
E1I <- ell3d(dual(zell1), col="blue", alpha=0.1, wire=TRUE)

#open3d()  ## to see this in a new window
# a singular ellipsoid and its inverse
c2 <- c1
C2 <- matrix(c(6, 2, 0,
               2, 3, 0,
               0, 0, 0), 3,3)

E2 <- ell3d( zell2 <-gell( center = c2, Sigma = C2), 
             col = 'red', alpha = 0.25, wire = TRUE)
E2I <- ell3d( dual(gell( center = c2, Sigma = C2)), 
             length=3, col = 'red', alpha = 0.25, wire = TRUE )

# signatures
signature(zell1)
signature(zell2)

Calculate an ellipsoid in 3D

Description

Calculates a qmesh3d object representing a 3D ellipsoid with given center and shape matrix. The function allows for degenerate ellipsoids where the shape matrix has rank < 3 and plots as an ellipse or a line.

Usage

ellipsoid(center, shape, radius = 1, segments = 60, warn.rank = FALSE)

Arguments

Details

The ellipsoid is calculated by transforming a unit sphere by the Cholesky square root of the shape matrix, and translating to the center.

The ellipsoid can be plotted with plot3d

Value

A qmesh3d object

Author(s)

Michael Friendly and John Fox, extending Duncan Murdoch

Examples

## none yet

(U, D) Representation of an Ellipsoid in R^p.

Description

gell provides a set of ways to specify a generalized ellipsoid in R^p, using the (U, D) representation to include all special cases, where U is a square orthogonal matrix, and D is diagonal with extended non-negative real numbers, i.e. 0, Inf or a positive real.

Usage

gell(x, ...)

## Default S3 method:
gell(x, center = 0, Sigma, ip, span, A, u, d = 1, epsfac = 2, ...)

## S3 method for class 'gell'
gell(x, ...)

Arguments

Details

The resulting class of ellipsoids includes degenerate ellipsoids that are flat and/or unbounded. Thus ellipsoids are naturally defined to include lines, hyperplanes, points, cylinders, etc.

gell can currently generate the (U, D) representation from 5 ways of specifying an ellipsoid:

1. From the non-negative definite dispersion (variance) matrix, Sigma: U D^2 U' = Sigma, where some elements of the diagonal matrix D can be 0. This can only generate bounded ellipsoids, possibly flat.

2. From the non-negative definite inner product matrix 'ip': U W^2 U = C where some elements of the diagonal matrix W can be 0. Then set D = W^-1 where 0^-1 = Inf. This can only generate fat (non-empty interior) ellipsoids, possibly unbounded.

3. From a subspace spanned by 'span' Let U_1 be an orthonormal basis of Span('span'), let U_2 be an orthonormal basis of the orthogonal complement, the U = [ U_1 U_2 ] and D = diag( c(Inf,...,Inf, 0,..,0)) where the number of Inf's is equal to the number of columns of U_1.

4. From a transformation of the unit sphere given by A(Unit sphere) where A = UDV', i.e. the SVD.

5. (Generalization of 4): A, d where A is any matrix and d is a vector of factors corresponding to columns of A. These factors can be 0, positive or Inf. In this case U and D are such that U D(Unit sphere) = A diag(d)(Unit sphere). This is the only representation that can be used for all forms of ellipsoids and in which any ellipsoid can be represented.

Value

A (U, D) representation of the ellipsoid, with components

Author(s)

Georges Monette

References

Friendly, M., Monette, G. and Fox, J. (2013). Elliptical Insights: Understanding Statistical Methods through Elliptical Geometry. Statistical Science, 28(1), 1-39.

See Also

dual, gmult, signature,

Examples

gell(Sigma = diag(3))    # the unit sphere

(zplane <- gell(span = diag(3)[,1:2]))    # a plane

Linear Transformation of a Generalized Ellipsoid

Description

Linear transformation of a generalized ellipsoid, including projections to subspaces.

Usage

gmult(A, G, epsfac = 2)

Arguments

Details

The matrix A can be non-singular, for a standard linear transformation, or singular, for a projection to a subspace.

Value

gell object

Note

This implementation should be changed so that it provides an S3 method for class "gell" objects for which it was intended.

Author(s)

Georges Monette

See Also

gell, dual, signature

Examples

(zplane <- gell(span = diag(3)[,1:2]))  # a plane

dual(zplane)  # orthogonal line
(zplane2 <- gmult( cbind( c(1,1,1), c(1,-1,0), c(1,0,-1)), zplane))

# correctly wipes out one dimension
(zplane3 <- gmult( cbind( c(1,0,0), c(1,0,0), c(0,0,1)), zplane)) 

Tests for Classes of Generalized Ellipsoids

Description

These functions provide tests for classes of generalized ellipsoids in the (U, D) representation, based on the numbers of positive, zero and infinite singular values in D.

They are included here mainly as computational definitions of the terms ‘bounded’ for an ellipsoid with finite extent, ‘fat’, for a bounded ellipsoid with non-empty interior, ‘flat’, for degenerate (singular) ellipsoids in R^p with empty interior.

Usage

isBounded(x, ...)

## S3 method for class 'gell'
isBounded(x, ...)

isFat(x, ...)

## S3 method for class 'gell'
isFat(x, ...)

isFlat(x, ...)

## S3 method for class 'gell'
isFlat(x, ...)

isUnbounded(x, ...)

## S3 method for class 'gell'
isUnbounded(x, ...)

Arguments

Value

TRUE or FALSE

Author(s)

Georges Monette

References

Friendly, M., Monette, G. and Fox, J. (2013). Elliptical Insights: Understanding Statistical Methods through Elliptical Geometry. Statistical Science, 28(1), 1-39.

See Also

signature

Examples

# None yet

Save and Restore the par3d Parameters for an rgl Scene

Description

Use this function to make a manually manipulated rgl view reproducible, within sessions or across sessions. Within an R session, simply use par3d.save to record the par3d parameters for the view(s) to named objects. Across sessions, use the filename argument to save these to .rds files

Usage

par3d.save(
  params = c("userMatrix", "scale", "zoom", "FOV"),
  filename,
  dev = rgl.cur()
)

par3d.restore(parms, filename)

Arguments

Value

par3d.save returns a list with the current values of the par3d parameters named in params.

Author(s)

Michael Friendly

See Also

par3d

Examples

## Not run: 
	library(rgl)
	open3d()
	# ...
	parms <- par3d.save()
	# ....
	par3d.restore(parms)
	

## End(Not run)

Signature of a Generalized Ellipsoid

Description

Calculates the signature of a generalized ellipsoid, a vector of length 3 giving the number of positive, zero and infinite singular values in the (U, D) representation

Usage

signature(G)

Arguments

Value

A vector of length 3, with named components pos, zero and inf

Author(s)

Georges Monette

References

Friendly, M., Monette, G. and Fox, J. (2013). Elliptical Insights: Understanding Statistical Methods through Elliptical Geometry. Statistical Science, 28(1), 1-39.

See Also

isBounded

Examples

(zsph <- gell(Sigma = diag(3)))  # unit sphere in R^3

(zplane <- gell(span = diag(3)[,1:2]))  # a plane

dual(zplane)  # line orthogonal to that plane

(zhplane <- gell(center = c(0,0,2), span = diag(3)[,1:2]))  # a hyperplane

dual(zhplane) # orthogonal line through same center (note that the 'gell'
              # object with a center contains more information than the geometric plane)

zorigin <- gell(span = cbind(c(0,0,0)))
dual( zorigin )

# signatures of these ellipsoids
signature(zsph)
signature(zhplane)
signature(dual(zhplane))