| Title: | Generalized Ellipsoids |
|---|---|
| Description: | Represents generalized geometric ellipsoids with the "(U,D)" representation. It allows degenerate and/or unbounded ellipsoids, together with methods for linear and duality transformations, and for plotting. Thus ellipsoids are naturally extended to include lines, hyperplanes, points, cylinders, etc. 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 Through Elliptical Geometry <doi:10.1214/12-STS402>. |
| Authors: | Georges Monette [aut], Michael Friendly [aut, cre] |
| Maintainer: | Michael Friendly <[email protected]> |
| License: | GPL (>= 2) |
| Version: | 0.7.3 |
| Built: | 2026-05-23 09:36:18 UTC |
| Source: | https://github.com/friendly/gellipsoid |
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.
It uses the (U, D) representation of generalized ellipsoids in ,
where
is square orthogonal and 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,
.
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:
From the non-negative definite dispersion (variance)
matrix, Sigma: ,
where some elements of the diagonal matrix
D can be 0. This can only generate bounded ellipsoids, possibly flat.
From the non-negative definite inner product matrix 'ip':
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.
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.
From a transformation of the unit sphere given by A(Unit sphere) where
, i.e. the SVD.
(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.
Georges Monette and Michael Friendly
Maintainer: Michael Friendly <[email protected]>
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
(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))(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))
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.
basis3d( matrix = diag(3), origin = c(0, 0, 0), scale = 1, draw = TRUE, label = draw, texts = colnames(basis), lwd = 3, cex = 2, ... )basis3d( matrix = diag(3), origin = c(0, 0, 0), scale = 1, draw = TRUE, label = draw, texts = colnames(basis), lwd = 3, cex = 2, ... )
matrix |
A 3 x 3 matrix, whose columns are the basis vectors, typically of unit length. |
origin |
Origin in the rgl scene of the basis vectors |
scale |
Scaling factor for the basis vectors |
draw |
If |
label |
If |
texts |
A character vector of length 3 used for labels. Defaults to
|
lwd |
Line width for vectors |
cex |
Character size for labels |
... |
Other arguments, passed to |
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.
Michael Friendly
# 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))# 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))
rgl::mesh3d or rgl::qmesh3d objectEllipsoids 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.
bbox3d(x, ...)bbox3d(x, ...)
x |
A mesh3d object |
... |
ignored |
A 2 x 3 matrix, giving the minimum and maximum values in the rows and x, y, z coordinates in the columns.
dual produces the orthogonal complement for subspaces or for
ellipsoids. This is equivalent to inverting or an inner product
ip when these are non-singular.
dual(x, ...) ## S3 method for class 'gell' dual(x, ...)dual(x, ...) ## S3 method for class 'gell' dual(x, ...)
x |
An object, of class |
... |
Other arguments, unused for now. |
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.
A (U, D) representation of the dual, with components LIST, use
u |
Right singular vectors |
d |
Singular values |
Georges Monette
Dempster, A. (1969). Elements of Continuous Multivariate Analysis Reading, MA: Addison-Wesley.
(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 )(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 )
ell3d is a convenience wrapper for ellipsoid
specialized for class "gell" objects. It plots an
ellipsoid in the current rgl window.
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, ... )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, ... )
x |
A vector of length 3 giving the center of the ellipsoid for the
default method, or a class |
... |
Other arguments, passed to |
shape |
A 3 x 3 symmetric matrix giving the shape of the ellipsoid. |
radius |
radius of the ellipsoid |
segments |
number of segments in each direction in calculating the
|
shade |
Logical. Whether the 3D ellipsoid should be shaded |
wire |
Logical. Whether the 3D ellipsoid should be rendered with its wire frame |
length |
For unbounded, (infinite) ellipsoids, the length to display for infinite dimensions |
sides |
For unbounded, cylindrical ellipsoids, the number of sides for the elliptical cross sections |
Returns the result of the call to ellipsoid
This implementation is subject to change.
Georges Monette
# 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)# 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)
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.
ellipsoid(center, shape, radius = 1, segments = 60, warn.rank = FALSE)ellipsoid(center, shape, radius = 1, segments = 60, warn.rank = FALSE)
center |
A vector of length 3 giving the center of the 3D ellipsoid, typically the mean vector of a data matrix. |
shape |
A 3 x 3 matrix giving the shape of the 3D ellipsoid, typical a covariance matrix of a data matrix. |
radius |
radius of the ellipsoid, with default |
segments |
number of line segments to use in each direction in the wire-frame representation of the ellipsoid |
warn.rank |
warn if the |
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
A qmesh3d object
Michael Friendly and John Fox, extending Duncan Murdoch
## none yet## none yet
gell provides a set of ways to specify a generalized ellipsoid in
, 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.
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, ...)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, ...)
x |
An object |
... |
Other arguments |
center |
A vector specifying the center of the ellipsoid |
Sigma |
A square, symmetric, non-negative definite dispersion (variance) matrix |
ip |
A square, symmetric, non-negative definite inner product matrix. See Details. |
span |
A subspace with a given span. See Details. |
A |
A matrix giving a linear transformation of the unit sphere. |
u |
A U matrix |
d |
Diagonal elements of a D matrix |
epsfac |
Factor of |
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:
From the non-negative definite dispersion (variance)
matrix, , where some elements of the diagonal matrix
D can be 0. This can only generate bounded ellipsoids, possibly flat.
From the non-negative definite inner product matrix
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.
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 and where the number
of Inf's is equal to the number of columns of U_1.
From a transformation of the unit sphere given by A(Unit sphere) where A = UDV', i.e. the SVD.
(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.
A (U, D) representation of the ellipsoid, with components
center |
center |
u |
Right singular vectors |
d |
Singular values |
Georges Monette
Friendly, M., Monette, G. and Fox, J. (2013). Elliptical Insights: Understanding Statistical Methods through Elliptical Geometry. Statistical Science, 28(1), 1-39.
gell(Sigma = diag(3)) # the unit sphere (zplane <- gell(span = diag(3)[,1:2])) # a planegell(Sigma = diag(3)) # the unit sphere (zplane <- gell(span = diag(3)[,1:2])) # a plane
Linear transformation of a generalized ellipsoid, including projections to subspaces.
gmult(A, G, epsfac = 2)gmult(A, G, epsfac = 2)
A |
A matrix describing a linear transformation, conforming to the U
component of |
G |
A |
epsfac |
Factor of |
The matrix A can be non-singular, for a standard linear
transformation, or singular, for a projection to a subspace.
gell object
This implementation should be changed so that it provides an S3 method
for class "gell" objects for which it was intended.
Georges Monette
(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))(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))
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 with empty interior.
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, ...)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, ...)
x |
A class |
... |
Other arguments, not used. |
TRUE or FALSE
Georges Monette
Friendly, M., Monette, G. and Fox, J. (2013). Elliptical Insights: Understanding Statistical Methods through Elliptical Geometry. Statistical Science, 28(1), 1-39.
# None yet# None yet
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
par3d.save( params = c("userMatrix", "scale", "zoom", "FOV"), filename, dev = rgl.cur() ) par3d.restore(parms, filename)par3d.save( params = c("userMatrix", "scale", "zoom", "FOV"), filename, dev = rgl.cur() ) par3d.restore(parms, filename)
params |
A list of |
filename |
Name of a |
dev |
The rgl device. Currently unused |
parms |
A list of |
par3d.save returns a list with the current values of the
par3d parameters named in params.
Michael Friendly
## Not run: library(rgl) open3d() # ... parms <- par3d.save() # .... par3d.restore(parms) ## End(Not run)## Not run: library(rgl) open3d() # ... parms <- par3d.save() # .... par3d.restore(parms) ## End(Not run)
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
signature(G)signature(G)
G |
A class |
A vector of length 3, with named components pos, zero
and inf
Georges Monette
Friendly, M., Monette, G. and Fox, J. (2013). Elliptical Insights: Understanding Statistical Methods through Elliptical Geometry. Statistical Science, 28(1), 1-39.
(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))(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))
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.
UD(x)UD(x)
x |
A matrix |
A list with the following components:
u |
Right singular vectors |
d |
Singular values |
Georges Monette
# None yet# None yet