ggbiplot: PCA scores and variable directions in one plot

In rsvd: Randomized Singular Value Decomposition

PCA scores and variable directions in one plot

Description

Display observations in a plane defined by two retained principal components from rpca, with arrows showing the corresponding variable directions. The combined view relates variation among the observations to the variables used in the fit. The optional ggplot2 package is required.

Usage

ggbiplot(
  rpcaObj,
  pcs = c(1, 2),
  loadings = TRUE,
  groups = NULL,
  alpha = 0.6,
  ellipse = TRUE,
  alpha.ellipse = 0.2,
  var_labels = TRUE,
  var_labels.names = NULL,
  ind_labels = TRUE,
  ind_labels.names = NULL
)

Arguments

rpcaObj	An object returned by rpca, with real-valued scores and directions. Complex factor maps are not supported. Fit with retx = TRUE so that rpcaObj$x is available.
pcs	Integer vector of length two selecting the retained principal components to plot, in horizontal and vertical order. The default is c(1, 2). Both indices must be finite integers within the retained component range.
loadings	Logical; when TRUE (the default), multiply each selected direction by its component standard deviation, so the coordinates are rotation[, pcs] scaled columnwise by sdev[pcs]. When FALSE, plot the unscaled entries of rotation[, pcs].
groups	Optional factor with one entry for each row of rpcaObj$x, in the same order. The length must match the number of score rows; shorter inputs are not recycled. Groups control point colours and, when requested, ellipses. The default, NULL, uses one colour and draws no ellipse. If rpca omitted incomplete observations, supply groups for the retained rows only.
alpha	Numeric value between zero and one controlling point transparency, with zero fully transparent and one opaque. The default is 0.6.
ellipse	Logical; draw a filled data ellipse for each supplied group when TRUE (the default). The defaults of stat_ellipse give a multivariate-t ellipse at level 0.95. See Details for its interpretation.
alpha.ellipse	Numeric value between zero and one controlling ellipse transparency. The default is 0.2; ignored when no ellipse is drawn.
var_labels	Logical; label the variable arrows when TRUE (the default).
var_labels.names	Optional character vector with one label per row of rpcaObj$rotation, in the original variable order. By default, the rotation row names are used, or sequential variable numbers when names are absent. Labels are displayed only when var_labels = TRUE.
ind_labels	Logical; show a text label for each observation when TRUE (the default). Set to FALSE to reduce clutter.
ind_labels.names	Optional character vector with one label per row of rpcaObj$x, in the same order. By default, the score row names are used, or sequential row numbers when names are absent. Labels are displayed only when ind_labels = TRUE.

Details

Each point represents one observation, with coordinates taken directly from rpcaObj$x. These fitted component scores reflect the centering and scaling requested in rpca. The plotting function leaves their normalization unchanged. Axis labels give each selected component's share of the total processed variance in rpcaObj$var, which includes variance outside the retained components.

Each arrow represents one variable. The loadings argument changes its coordinates by including or omitting the component standard deviations. Arrows and observations retain their respective loading and score scales; the function does not rescale them to match visually.

For centered variables with unit sample variance and nonzero component variance, the default coordinates equal the correlations with fitted scores for a deterministic SVD. A randomized fit can introduce approximation error in this interpretation. Other preprocessing choices give scaled directions that need not be correlations. Use ggcorplot to examine the directions separately with a unit circle.

When groups are supplied, data ellipses summarize the spread of fitted scores within each group under the multivariate-t model used by stat_ellipse. They do not estimate confidence regions for group means or test group separation. The multivariate-t computation also requires the recommended package MASS. Small groups or degenerate score distributions may not support ellipse estimation; use ellipse = FALSE in that case.

Value

A ggplot2 plot object. Print the object to draw the plot, or add layers, labels, and themes with ggplot2.

Author(s)

N. Benjamin Erichson

See Also

rpca, ggindplot, ggcorplot, ggscreeplot, ggplot, stat_ellipse

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  set.seed(42)
  fit <- rpca(iris[, 1:4], k = 2)
  p <- ggbiplot(fit, groups = iris$Species, ellipse = FALSE,
                ind_labels = FALSE)
  print(p + ggplot2::labs(title = "Iris scores and variable directions"))
}

rsvd documentation built on Nov. 2, 2026, 5:06 p.m.