Plot a fitted multivariate gllvmTMB model — plot.gllvmTMB

Produces a variety of ggplot2 visualisations for a stacked-trait multivariate GLLVM. Dispatches on type to one of seven panels:

Usage

# S3 method for class 'gllvmTMB_multi'
plot(
  x,
  type = c("correlation", "correlation_ellipse", "loadings", "integration",
    "communality", "variance", "ordination"),
  level = c("unit", "unit_obs"),
  boot = NULL,
  axes = c(1L, 2L),
  rotation = c("varimax", "none", "promax"),
  order_axes = TRUE,
  sign_anchor = c("auto", "none"),
  anchor_traits = NULL,
  standardize_loadings = FALSE,
  ...
)

Arguments

x

A fit returned by gllvmTMB().

type

One of "correlation", "correlation_ellipse", "loadings", "integration", "communality", "variance", "ordination".

level

"unit" (between-unit) or "unit_obs" (within-unit). Legacy aliases "B" and "W" are accepted with a deprecation warning. Used by "loadings" (which level to plot; the default c("unit", "unit_obs") means "both available levels, faceted side-by-side"; pass a length-1 string to plot one tier) and "ordination" (single level required; omitted level defaults to "unit"). Ignored for "correlation" (which always shows both if available), "integration", and "variance".

Note: the default level = c("unit", "unit_obs") is intentionally a length-2 vector, not the usual match.arg shortcut. The dispatcher does not call match.arg(level) itself; each helper inspects level and decides whether to plot one tier or both. If you copy one of these helpers into your own code, mirror that pattern rather than reflexively calling match.arg(level) (which would silently collapse the default to "unit" and drop the unit_obs panel).

boot

Optional bootstrap object. This can be either a bootstrap_Sigma() result or a list with elements repeatability, communality_B, communality_W, each a data frame with columns trait, lower, upper. A bootstrap_Sigma() object can add correlation intervals to "correlation" / "correlation_ellipse", whiskers to "integration", and c^2 boundary intervals to "communality". Default NULL skips interval overlays.

axes

Length-2 or length-3 integer vector for "ordination" when d >= 2. Length 2 draws a single biplot. Length 3 draws a static pair-grid of the three axis pairs. For d = 3, the default c(1, 2) is promoted to c(1, 2, 3) so all three axes are visible. Ignored when d = 1.

rotation

One of "varimax", "none", or "promax" for "ordination" plots. The default "varimax" uses rotated, shared-variance-ordered, sign-anchored axes for interpretation. Use "none" to show the raw computational orientation. Rotation makes the biplot easier to label; use Sigma, correlations, communality, and uniqueness as the primary quantitative summaries.

order_axes

Logical. For rotated "ordination" plots, reorder latent axes by decreasing shared variance after rotation. Default TRUE. Ignored when rotation = "none".

sign_anchor

One of "auto" or "none". For rotated "ordination" plots, "auto" flips each axis so its anchor trait has a positive loading. Default "auto". Ignored when rotation = "none".

anchor_traits

Optional character vector of trait names used for sign anchoring in rotated "ordination" plots. Supply one trait per axis after any order_axes step. Missing axes fall back to the trait with the largest absolute loading. Ignored when rotation = "none".

standardize_loadings

Logical. For "ordination" plots, divide each trait loading by the square root of that trait's model-implied total variance before drawing arrows. This puts arrows on a correlation-like scale for mixed-scale traits. It changes the displayed arrow scale, not the model's communality or variance decomposition. Default FALSE.

...

Currently unused.

Value

A ggplot object with a gllvmTMB_meta attribute describing the plot type, source extractor, covariance level, interval status, and rotation status. Metadata also carries extractor notes when a plotted summary has an important caveat. Plots also carry a gllvmTMB_data attribute with the prepared plotting data; ordination stores separate scores and loadings tables.

Details

"correlation": Combined heatmap of trait correlations. Upper triangle = between-unit correlations (level = "unit"), lower triangle = within-unit correlations (level = "unit_obs"), diagonal = 1. Falls back to whichever level is present if the other tier is absent. Optional boot intervals are carried in the plot data when supplied.
"correlation_ellipse": Ellipse matrix of trait correlations. Ellipse direction and eccentricity encode the sign and strength of the correlation. This is the Figure-3-style alternative to the tile heatmap. Optional boot intervals mark correlations whose interval does not cross zero with black borders and stars. These bootstrap intervals are recovery-grade, and their coverage properties are not yet established: read a marked cell as "the interval excludes zero at the fitted point", not as a calibrated significance test.
"loadings": Tile heatmap of Lambda_B (and Lambda_W if present), faceted by level. Rows = traits, columns = factors. Pinned cells (from lambda_constraint) are drawn with a heavy outline.
"integration": Dot-and-whisker plot of repeatability (ICC), between-tier communality and within-tier communality per trait, sorted by repeatability. Optional whiskers from a boot object (skipped if boot = NULL).
"communality": Figure-3-style stacked bars of per-trait communality (c^2, shared latent proportion) and uniqueness (1 - c^2) for the available latent tiers. Optional boot intervals are drawn on the c^2 boundary when supplied.
"variance": Stacked-bar variance partition per trait, using extract_proportions(format = "long"). One bar per trait, stacks summing to 1.
"ordination": Dimension-aware latent-score ordination. 1D fits (d = 1) get a horizontal score strip with trait loading lollipops; 2D fits get a standard biplot; 3D fits get a static pair-grid biplot for the three axis pairs. For d > 3, pick two or three axes via axes.