This function plots ellipsoids in 3D representing the hypothesis (\(\mathbf{H}\)) and error (\(\mathbf{E}\))
sums-of-squares-and-products matrices for terms and linear hypotheses in a
multivariate linear model. It allow you to visualize model effects on three response variables
together, as opposed to the 2D views offered by heplot() and pairs.mlm().
heplot3d(mod, ...)# S3 method for mlm
heplot3d(
mod,
terms,
hypotheses,
term.labels = TRUE,
hyp.labels = TRUE,
err.label = "Error",
variables = 1:3,
error.ellipsoid = !add,
factor.means = !add,
grand.mean = !add,
remove.intercept = TRUE,
type = c("II", "III", "2", "3"),
idata = NULL,
idesign = NULL,
icontrasts = c("contr.sum", "contr.poly"),
imatrix = NULL,
iterm = NULL,
manova,
size = c("evidence", "effect.size", "significance"),
level = 0.68,
alpha = 0.05,
segments = 40,
col = getOption("heplot3d.colors", c("red", "blue", "black", "darkgreen", "darkcyan",
"magenta", "brown", "darkgray")),
lwd = c(1, 4),
shade = TRUE,
shade.alpha = 0.2,
wire = c(TRUE, FALSE),
bg.col = c("white", "black"),
fogtype = c("none", "exp2", "linear", "exp"),
fov = 30,
offset = 0.01,
xlab,
ylab,
zlab,
xlim,
ylim,
zlim,
cex.label = 1.5,
add = FALSE,
verbose = FALSE,
warn.rank = FALSE,
...
)
heplot3d invisibly returns a list containing the bounding
boxes of the error (\(\mathbf{E}\)) ellipsoid and for each term or linear hypothesis
specified in the call. Each of these is a 2 x 3 matrix with rownames "min"
and "max" and colnames corresponding to the variables plotted. An additional
component, center, contains the coordinates of the centroid in the
plot.
The function also leaves an object named .frame in the global
environment, containing the rgl object IDs for the axes, axis labels, and
bounding box; these are deleted and the axes, etc. redrawn if the plot is
added to.
a model object of class "mlm".
arguments passed from generic.
a logical value or character vector of terms in the model for
which to plot hypothesis matrices; if missing or TRUE, defaults to
all terms; if FALSE, no terms are plotted.
optional list of linear hypotheses for which to plot
hypothesis matrices; hypotheses are specified as for the
car::linearHypothesis() function in the car package; the
list elements can be named, in which case the names are used.
logical value or character vector of names for the terms
to be plotted. If TRUE (the default) the names of the terms are used;
if FALSE, term labels are not plotted.
logical value or character vector of names for the
hypotheses to be plotted. If TRUE (the default) the names of
components of the list of hypotheses are used; if FALSE, hypothesis
labels are not plotted.
Label for the error ellipse
indices or names of the three response variables to be
plotted; defaults to 1:3.
if TRUE, plot the error ellipsoid; defaults to
TRUE, if the argument add is FALSE (see below).
logical value or character vector of names of factors
for which the means are to be plotted, or TRUE or FALSE;
defaults to TRUE, if the argument add is FALSE (see
below).
if TRUE, plot the centroid for all of the data;
defaults to TRUE, if the argument add is FALSE (see
below).
if TRUE (the default), do not plot the
ellipsoid for the intercept even if it is in the MANOVA table.
``type'' of sum-of-squares-and-products matrices to compute; one
of "II", `"III"`, `"2"`, or `"3"`, where `"II"`
is the default (and `"2"` is a synonym).
an optional data frame giving a factor or factors defining the
intra-subject model for multivariate repeated-measures data. See Details of
car::Anova() for an explanation of the intra-subject design and
for further explanation of the other arguments relating to intra-subject
factors.
a one-sided model formula using the ``data'' in idata and specifying the intra-subject design for repeated measure models.
names of contrast-generating functions to be applied by default to factors and ordered factors, respectively, in the within-subject ``data''; the contrasts must produce an intra-subject model matrix in which different terms are orthogonal. The default is c("contr.sum", "contr.poly").
In lieu of idata and idesign, you can specify
the intra-subject design matrix directly via imatrix, in the form of
list of named elements. Each element gives the columns of the
within-subject model matrix for an intra-subject term to be tested, and must
have as many rows as there are responses; the columns of the within-subject
model matrix for different terms must be mutually orthogonal.
For repeated measures designs, you must specify one
intra-subject term (a character string) to select the SSPE (\(\mathbf{E}\)) matrix used
in the HE plot. Hypothesis terms plotted include the iterm effect as
well as all interactions of iterm with terms.
optional Anova.mlm object for the model; if absent a
MANOVA is computed. Specifying the argument can therefore save computation
in repeated calls.
how to scale the hypothesis ellipse relative to the error
ellipse; if "evidence", the default, the scaling is done so that a
``significant'' hypothesis ellipse at level alpha extends outside of
the error ellipse. `size = "significance"` is a synonym and does the same thing.
If `"effect.size"`, the hypothesis ellipse is on the
same scale as the error ellipse.
equivalent coverage of ellipse (assuming normally-distributed errors).
This defaults to 0.68, giving a standard 1 SD bivariate ellipse.
significance level for Roy's greatest-root test statistic; if
size="evidence" or size="significance", then the hypothesis ellipse is scaled so that it
just touches the error ellipse at the specified alpha level. A larger
hypothesis ellipse somewhere in the space of the response variables
therefore indicates statistical significance; defaults to 0.05.
number of segments composing each ellipsoid; defaults to 40.
a color or vector of colors to use in plotting ellipsoids; the
first color is used for the error ellipsoid; the remaining colors ---
recycled as necessary --- are used for the hypothesis ellipsoid. A single
color can be given, in which case it is used for all ellipsoid. For
convenience, the default colors for all heplots produced in a given session
can be changed by assigning a color vector via options(heplot3d.colors=c(...).
Otherwise, the default colors are c("pink", "blue", "black", "darkgreen", "darkcyan", "magenta", "brown", "darkgray").
a two-element vector giving the line width for drawing ellipsoids
(including those that degenerate to an ellipse) and for drawing ellipsoids
that degenerate to a line segment. The default is c(1, 4).
a logical scalar or vector, indicating whether the ellipsoids
should be rendered with rgl::shade3d(). Works like col,
except that FALSE is used for any 1 df degenerate ellipsoid.
a numeric value in the range (0,1), or a vector of such
values, giving the alpha transparency for ellipsoids rendered with
shade=TRUE.
a logical scalar or vector, indicating whether the ellipsoids
should be rendered with rgl::wire3d(). Works like col,
except that TRUE is used for any 1 df degenerate ellipsoid.
background colour, "white" or "black",
defaulting to "white".
type of ``fog'' to use for depth-cueing; the default is
"none". See rgl::bg3d().
field of view angle; controls perspective. See
rgl::view3d().
proportion of axes to off set labels; defaults to 0.01.
x-axis label; defaults to name of the x variable.
y-axis label; defaults to name of the y variable.
z-axis label; defaults to name of the z variable.
x-axis limits; if absent, will be computed from the data.
y-axis limits; if absent, will be computed from the data.
z-axis limits; if absent, will be computed from the data.
text size for ellipse labels
if TRUE, add to the current plot; the default is
FALSE. If TRUE, the error ellipsoid is neither plotted nor
returned in the output object.
if TRUE, print the MANOVA table and details of
hypothesis tests; the default is FALSE.
if TRUE, do not suppress warnings about the rank of
the hypothesis matrix when the ellipsoid collapses to an ellipse or line;
the default is FALSE.
It uses the rgl package for rendering, so it adds some arguments (e.g., fogtype) to those used
in heplot(), but is otherwise the same.
Rotating the plot can be particularly revealing, showing views in which \(\mathbf{H}\)
variation is particularly large or small in relation to \(\mathbf{E}\) variation. If you find
a view making \(\mathbf{H}\) as large as possible, this corresponds closely to the canonical
view chosen by the candisc.
See rgl::play3d() and rgl::movie3d() for details on creating animations, rotating the 3D scene around on or more coordinate axes, or zooming in/out to highlight some feature.
When the \(\mathbf{H}\) matrix for a term has rank < 3, the ellipsoid collapses to an ellipse (rank(\(\mathbf{H}\))=2) or a line (rank(\(\mathbf{H}\))=1).
The arguments xlim, ylim, and zlim can be used to
expand the bounding box of the axes, but cannot decrease it.
For use in an R Markdown, Quarto, or pkgdown document, follow the call to heplot3d()
with rgl::rglwidget() to embed the plot as an interactive, rotatable widget instead of a
static image.
In a knitted document, call rgl::setupKnitr() with autoprint = TRUE once,
near the top of the document, so that low-level rgl calls are captured automatically;
On a pkgdown reference page like this, the trailing rgl::rglwidget() call in the example is enough by
itself, and no setupKnitr() call is needed.
Note that the widget capture depends on
rglwidget() itself being the visibly-printed value -- heplot3d() returns its ellipsoid
bounding boxes invisibly (for compatibility with heplot()), so calling it alone does not trigger a plot in either context.
For a bookdown-based vignette with pkgdown: as_is: true in its YAML header
(needed for \@ref() figure/table numbering), calling rglwidget() directly
renders fine in the standalone vignette (R CMD build/devtools::build_vignettes())
but shows as a blank box on the pkgdown site: pkgdown replaces the document's
own <head> when assembling the article page, silently dropping the <script> tags
the widget needs to render, even though its scene data is still present in the page.
The fix is to pre-render the widget to a self-contained file and embed that with an
<iframe> instead, since body content (unlike the <head>) survives pkgdown's
page assembly:
w <- rgl::rglwidget()
htmlwidgets::saveWidget(w, "vignettes/images/myplot.html", selfcontained = TRUE)
and in the vignette text, in place of the live call:
htmltools::tags$iframe(src = "images/myplot.html", width = "100%", height = "500",
style = "border: none;")
pkgdown copies the referenced file into the built site automatically, the same
way it already copies images referenced via knitr::include_graphics().
Friendly, M. (2006). Data Ellipses, HE Plots and Reduced-Rank Displays for Multivariate Linear Models: SAS Software and Examples Journal of Statistical Software, 17(6), 1-42. https://www.jstatsoft.org/v17/i06/
Friendly, M. (2007). HE plots for Multivariate General Linear Models. Journal of Computational and Graphical Statistics, 16(2) 421-444. http://datavis.ca/papers/jcgs-heplots.pdf
car::Anova(), car::linearHypothesis(), for
details on MANOVA tests and linear hypotheses
heplot(), pairs.mlm(), for other plotting methods
for mlm objects
rgl::rgl-package, for details about 3D plots with rgl
candisc::heplot3d.candisc() for 3D HE plots in canonical space.
Other HE plot functions:
heplot(),
heplot1d(),
pairs.mlm()
Other 3D plotting:
arrow3d(),
bbox3d(),
cross3d(),
ellipse3d.axes()
# Soils data, from carData package
data(Soils, package = "carData")
soils.mod <- lm(cbind(pH,N,Dens,P,Ca,Mg,K,Na,Conduc) ~ Block + Contour*Depth, data=Soils)
car::Anova(soils.mod)
heplot(soils.mod, variables=c("Ca", "Mg"))
pairs(soils.mod, terms="Depth", variables=c("pH", "N", "P", "Ca", "Mg"))
heplot3d(soils.mod, variables=c("Mg", "Ca", "Na"), wire=FALSE)
rgl::rglwidget()
# Plastic data
plastic.mod <- lm(cbind(tear, gloss, opacity) ~ rate*additive, data=Plastic)
if (FALSE) {
heplot3d(plastic.mod, col=c("red", "blue", "brown", "green3"), wire=FALSE)
}
Run the code above in your browser using DataLab