Nothing
#' @title Plot a Two-Dimensional Embedding
#'
#' @author Christian L. Goueguel
#'
#' @description
#' Draws the samples in two dimensions of an embedding, such as UMAP
#' coordinates from `embed::step_umap()`, principal component scores from
#' `recipes::step_pca()`, [robpca()] or [stats::prcomp()], colored by a
#' variable.
#'
#' @details
#' By default, the axes are the first two columns named like embedding
#' coordinates (`UMAP1`, `PC1`, `Comp1`, ...; the name followed by a
#' number), or else the first two numeric columns. A numeric `color_by` uses
#' a continuous viridis scale, other types a discrete palette.
#'
#' With `ellipse = TRUE`, a confidence ellipse is drawn for each group of a
#' discrete `color_by` (or for all the samples otherwise), with
#' [ConfidenceEllipse::confidence_ellipse()], at each level of `conf_level`
#' (0.975 by default). It covers the region expected to hold that share of
#' the samples of the group if they follow a
#' bivariate normal distribution, from their mean and covariance, or from
#' robust estimates (MCD) with `robust = TRUE`, which resist outlying
#' samples. `distribution = "hotelling"` uses the quantile of Hotelling's
#' \eqn{T^2} distribution, which accounts for the uncertainty of the
#' estimates and suits small groups. Robust estimates need larger groups
#' (the MCD fits a subset of about three quarters of the samples): with
#' fewer than about 10 samples per group, their ellipses can be flat or
#' leave out several samples. Groups with fewer than 4 samples get no
#' ellipse.
#'
#' With `hotelling = "all"`, the ellipses of Hotelling's \eqn{T^2} at each
#' level of `conf_level` (97.5% by default) are drawn for all the samples,
#' and the samples beyond the limit at the highest level of \eqn{T^2} on `ncomp`
#' components are counted in the subtitle, circled in red with
#' `flag = TRUE` and labeled with `label` (each independently of the other):
#' the classical outlier limits of a score plot. For a PCA model ([stats::prcomp()], [robpca()], [rospca()] or
#' [macropca()]), \eqn{T^2} is that of the model: the scores divided by the
#' variances of the components (the robust eigenvalues of a robust fit), so
#' the ellipses are centered at 0 with the axes of the components, and
#' semi-axes \eqn{\sqrt{\lambda_a L}} for the limit \eqn{L}. The limit is
#' the F (or Beta) limit of [hotelling_t2()] for a [stats::prcomp()] fit, and
#' the chi-square quantile of ROBPCA for a robust fit, whose flagged samples
#' are then the leverage points of [plot_outlier_map()] (with `ncomp` its
#' number of components and `conf_level = 0.975`). The scores of the
#' outlying samples then do not inflate or tilt the ellipses. For other
#' embeddings, \eqn{T^2} is computed from the mean and covariance of the
#' samples (with [hotelling_t2()] and [HotellingEllipse::ellipseCoord()]).
#' With `hotelling = "group"`, each group of a discrete `color_by` gets its own
#' ellipses and limits, from its mean and covariance, which flags the samples
#' atypical of their own group. The ellipses are labeled with their level
#' (instead of a legend), and drawn for the two components shown, while the
#' limits use `ncomp` components, so with `ncomp > 2` a flagged sample can lie inside
#' the ellipses. With `ellipse = TRUE`, the confidence ellipses are always
#' computed from the samples shown. Without groups, `ellipse = TRUE` and
#' `hotelling = "all"` would draw two ellipses of all the samples: only the
#' \eqn{T^2} ellipse is drawn, with a warning. With groups, both are drawn:
#' the confidence ellipses of the groups and the \eqn{T^2} limits of all
#' the samples. \eqn{T^2} suits linear scores such as
#' PCA or PLS; on a UMAP
#' map, whose distances are not meaningful, prefer `ellipse`.
#'
#' **Style.** The panel is grey outside the outermost ellipse (of
#' \eqn{T^2}, or of each group) and white inside, so that the samples beyond
#' the limits stand out (`panel = "white"` for a white panel), with no grid
#' and a fixed `aspect_ratio` (0.7 by default; `NULL` lets the plot fill the
#' space, `"equal"` gives both axes the same scale), and thin light grey
#' lines through the origin (when it lies in the range of the samples, as for
#' centered scores). Without ellipses, the panel is white. The groups of a
#' discrete `color_by` also get their own point shapes (`shapes`), and the axes
#' plain numbers. A caption says what the ellipses and limits are (their
#' level, distribution and estimates), which readers cannot tell from the
#' plot.
#'
#' **Publication figures.** Make the plot at its printed size, with
#' `base_size` set to the text size of the journal, for example
#' `ggsave("scores.pdf", p, width = 85, height = 75, units = "mm")` with
#' `base_size = 8` for a single column.
#'
#' **Axes.** For a [stats::prcomp()] fit or a robust PCA, the axis titles
#' give the share of the variance of each component: of the total variance
#' for [stats::prcomp()], and of the variance of the components of the
#' model for [robpca()], [rospca()] and [macropca()], which estimate only
#' these. With groups, the ellipses (confidence, or \eqn{T^2} with
#' `hotelling = "group"`) are filled with the color of their group.
#'
#' **Point size.** `point_size` is a number, or a numeric variable (a column
#' of `data` or a vector with one value per sample), such as the
#' concentration of an element, which sets the size of each point, with a
#' legend.
#'
#' **Biplot.** With `biplot = TRUE` (for a [stats::prcomp()] fit or a robust
#' PCA), the loadings of the two components are drawn over the scores: all
#' the variables as faint points, and the `biplot_top` longest as labeled
#' arrows. For spectra, the arrows are the local peaks of the loading
#' length along the wavelength, one per emission line, labeled with their
#' wavelength. Each axis of loadings is scaled to the range of its scores,
#' and read on the top and right axes. A sample lies toward the arrows of
#' the variables in which it is high.
#'
#' In a UMAP embedding, only the neighborhoods are meaningful: the sizes of
#' the clusters and the distances between them are not, and they change
#' with `neighbors` and `min_dist`. Read the plot as a map of which samples
#' are similar, not as a quantitative projection. When both axes are UMAP
#' coordinates (named `UMAP1`, `UMAP2`, ..., as by `embed::step_umap()`),
#' the lines through the origin are left out, and `hotelling` (`"all"` or
#' `"group"`) is ignored, with a warning: its \eqn{T^2} limits assume linear
#' scores.
#'
#' @param data The embedding: a data frame (such as a baked recipe), a
#' matrix, a [stats::prcomp()] fit, or an object of [robpca()],
#' [rospca()] or [macropca()].
#' @param x,y The columns of the axes, unquoted or as strings. By default,
#' the first two embedding coordinates (see details).
#' @param color_by The variable coloring the points: a column of `data`
#' (unquoted or as a string), or a vector with one value per sample.
#' @param point_size The size of the points: a number, or a numeric column
#' of `data` or vector with one value per sample to vary it. Default is 2
#' at a `base_size` of 11, scaled with `base_size`.
#' @param point_alpha The opacity of the points, between 0 and 1. Default is
#' 0.8.
#' @param ellipse A logical: draw confidence ellipses (`FALSE`, default).
#' Needs the ConfidenceEllipse package.
#' @param conf_level The confidence level(s) of the ellipses, confidence
#' and \eqn{T^2}: one or more values between 0 and 1. Default is 0.975.
#' The samples beyond a \eqn{T^2} limit are flagged at the highest level.
#' @param robust A logical: robust ellipses (`FALSE`, default).
#' @param distribution The quantile of the ellipses: `"normal"` (default,
#' chi-square) or `"hotelling"`.
#' @param hotelling Hotelling's \eqn{T^2} ellipses and outliers: `"none"`
#' (default), `"all"` (all samples) or `"group"` (within the groups of a
#' discrete `color_by`). Needs the HotellingEllipse package (1.3.0 or
#' later).
#' @param ncomp The number of components of \eqn{T^2}: the two axes, then the
#' next embedding coordinates. Default is 2.
#' @param t2_method The distribution of the \eqn{T^2} limits: `"f"`
#' (default), `"beta"` or `"new"` (see [hotelling_t2()]). Ignored for a
#' robust PCA, whose limit is the chi-square quantile of ROBPCA.
#' @param flag A logical: circle in red the samples beyond the \eqn{T^2}
#' limit (`FALSE`, default).
#' @param label The labels of the samples beyond the \eqn{T^2} limit,
#' whether or not they are circled: `NULL` or `FALSE` (default) for none,
#' `TRUE` for their row numbers, or a column of `data` or a vector with
#' one value per sample.
#' @param biplot A logical: draw the loadings over the scores (`FALSE`,
#' default).
#' @param biplot_top The number of loadings drawn as labeled arrows.
#' Default is 10.
#' @param aspect_ratio The ratio of the height to the width of the panel.
#' Default is 0.7; `NULL` lets the panel fill the plot; `"equal"` gives
#' the two axes the same scale, so that the distances between the samples
#' are not distorted (for scores in the same units).
#' @param title The plot title.
#' @param legend_title The title of the legend of `color_by`. Default is its
#' name; give it with units, such as `"K (%)"`.
#' @param palette The colors of `color_by`: `NULL` (default: Dark2 for up to 8
#' groups, viridis for a numeric variable), the name of a viridis palette
#' (`"viridis"`, `"magma"`, `"cividis"`, ...) or a vector of colors.
#' @param shapes A logical: give each group of a discrete `color_by` its own
#' point shape (up to 6 groups), so that the groups stay apart in grayscale
#' (`TRUE`, default).
#' @param legend The position of the legend: `"right"` (default), `"bottom"`,
#' `"top"`, `"inside"` (the top right corner of the panel) or `"none"`.
#' @param panel `"shaded"` (default), the panel grey outside the outermost
#' ellipse and white inside, or `"white"`.
#' @param caption `TRUE` (default), a caption saying what the ellipses and
#' limits are; `FALSE`, no caption; or a caption of your own.
#' @param base_size The size of the text, in points. Default is 11; use the
#' text size of the journal (often 7 to 9 points) for a figure saved at its
#' printed size. The points (unless `point_size` is a number), lines and
#' labels scale with it.
#' @param xlab,ylab The axis titles. Default are the names of the axes, with
#' the variance they explain for a PCA.
#' @param colour,size,alpha `r lifecycle::badge("deprecated")` Use
#' `color_by`, `point_size` and `point_alpha`.
#' @param k `r lifecycle::badge("deprecated")` Use `ncomp`.
#'
#' @return A ggplot object.
#' @seealso [hotelling_t2()], [plot_outlier_map()], [plot_loadings()], [robpca()]
#' @export plot_embedding
#'
#' @examples
#' # robust PCA of the forage spectra, with the Hotelling's T-squared limit
#' if (rlang::is_installed("HotellingEllipse", version = "1.3.0")) {
#' data(forageLIBS)
#' # the 380-430 nm window (Ca II H and K lines)
#' wl <- suppressWarnings(as.numeric(names(forageLIBS)))
#' set.seed(1)
#' forageLIBS[which(wl > 380 & wl < 430)] |>
#' center() |>
#' robpca(ncomp = 2) |>
#' plot_embedding(hotelling = "all", flag = FALSE, label = TRUE)
#' }
#'
#' # PCA of the K I lines, the samples grouped by potassium level, for a
#' # journal column
#' if (rlang::is_installed("ConfidenceEllipse")) {
#' data(forageLIBS)
#' wl <- suppressWarnings(as.numeric(names(forageLIBS)))
#' pca <- stats::prcomp(forageLIBS[which(wl > 760 & wl < 772)])
#' level <- cut(forageLIBS$K, 3, labels = c("Low K", "Mid K", "High K"))
#' p <- plot_embedding(pca, color_by = level, ellipse = TRUE, legend_title = "Potassium",
#' legend = "bottom", base_size = 8)
#' p
#' # saved at that size (here in the temporary directory)
#' ggplot2::ggsave(file.path(tempdir(), "scores.pdf"), p, width = 85, height = 80,
#' units = "mm")
#' }
#'
#' \donttest{
#' # UMAP map of the iris flowers, from embed::step_umap(): no lines through
#' # the origin, whose position means nothing on such a map
#' if (rlang::is_installed(c("recipes", "embed"))) {
#' set.seed(1)
#' umap <- recipes::recipe(Species ~ ., data = iris) |>
#' recipes::step_normalize(recipes::all_predictors()) |>
#' embed::step_umap(recipes::all_predictors(), neighbors = 15) |>
#' recipes::prep() |>
#' recipes::bake(new_data = NULL)
#' plot_embedding(umap, color_by = Species, title = "UMAP of the iris flowers")
#' }
#' }
#'
plot_embedding <- function(data, x = NULL, y = NULL, color_by = NULL, point_size = NULL,
point_alpha = 0.8,
ellipse = FALSE, conf_level = 0.975, robust = FALSE,
distribution = "normal", hotelling = "none", ncomp = 2,
t2_method = "f", flag = FALSE, label = NULL, biplot = FALSE,
biplot_top = 10, aspect_ratio = 0.7, title = NULL,
legend_title = NULL, palette = NULL, shapes = TRUE,
legend = c("right", "bottom", "top", "inside", "none"),
panel = c("shaded", "white"), caption = TRUE, base_size = 11,
xlab = NULL, ylab = NULL, colour = deprecated(), size = deprecated(),
alpha = deprecated(), k = deprecated()) {
ncomp <- renamed_arg(k, ncomp, "plot_embedding", "k", "ncomp")
df <- embedding_data(data)
variance <- embedding_variance(data)
# the former colour, size and alpha (tidy-evaluated, so tested with missing())
user_env <- rlang::caller_env()
colour_quo <- rlang::enquo(color_by)
if (!missing(colour)) {
lifecycle::deprecate_warn("0.9.0", "plot_embedding(colour)", "plot_embedding(color_by)",
user_env = user_env)
colour_quo <- rlang::enquo(colour)
}
size_quo <- rlang::enquo(point_size)
size_arg <- "point_size"
if (!missing(size)) {
lifecycle::deprecate_warn("0.9.0", "plot_embedding(size)", "plot_embedding(point_size)",
user_env = user_env)
size_quo <- rlang::enquo(size)
size_arg <- "size"
}
point_alpha <- renamed_arg(alpha, point_alpha, "plot_embedding", "alpha", "point_alpha",
user_env = user_env)
x <- embedding_column(rlang::enquo(x), df, "x")
y <- embedding_column(rlang::enquo(y), df, "y")
if (is.null(x) || is.null(y)) {
axes <- embedding_axes(df)
x <- x %||% setdiff(axes, y)[1]
y <- y %||% setdiff(axes, x)[1]
}
if (is.na(x) || is.na(y) || x == y) {
stop("'data' needs two numeric columns for the axes; give `x` and `y`.", call. = FALSE)
}
check_alpha(point_alpha, "point_alpha")
check_label(xlab, "xlab")
check_label(ylab, "ylab")
check_flag(ellipse, "ellipse")
check_flag(robust, "robust")
check_flag(biplot, "biplot")
check_flag(flag, "flag")
check_count(biplot_top, "biplot_top", lower = 0)
check_flag(shapes, "shapes")
check_number(base_size, "base_size", lower = 0, lower_open = TRUE)
legend <- match.arg(legend)
panel <- match.arg(panel)
if (!is.null(palette)) check_palette(palette)
if (!(isTRUE(caption) || isFALSE(caption) ||
(is.character(caption) && length(caption) == 1 && !is.na(caption)))) {
stop("'caption' must be TRUE, FALSE or a character string.", call. = FALSE)
}
equal <- identical(aspect_ratio, "equal")
if (!is.null(aspect_ratio) && !equal) {
check_number(aspect_ratio, "aspect_ratio", lower = 0, lower_open = TRUE)
}
# the sizes of the points, lines and labels follow the text
scale <- base_size / 11
ellipse_level <- check_conf_level(conf_level)
t2_level <- ellipse_level
distribution <- match.arg(distribution, c("normal", "hotelling"))
hotelling <- match.arg(hotelling, c("none", "all", "group"))
t2_method <- match.arg(t2_method, c("f", "beta", "new"))
# a UMAP map (embed::step_umap()): its coordinates are not linear scores,
# so it has no meaningful origin and no T-squared limits
umap <- all(grepl("^UMAP_?[0-9]+$", c(x, y), ignore.case = TRUE))
if (umap && hotelling != "none") {
warning("`hotelling = \"", hotelling, "\"` is ignored on a UMAP map: Hotelling's ",
"T-squared limits assume linear scores, such as those of a PCA.", call. = FALSE)
hotelling <- "none"
}
colour_info <- embedding_values(colour_quo, df, "color_by")
colour_values <- colour_info$values
colour_name <- legend_title %||% colour_info$name
size_info <- embedding_size(size_quo, df, size_arg)
# a number given in `point_size` is the size of the points; the default,
# and a number in the former `size`, scale with the text
point_size <- if (is.null(size_info$constant)) 2 * scale else if (size_arg == "size")
size_info$constant * scale else size_info$constant
label_quo <- rlang::enquo(label)
label_expr <- rlang::quo_get_expr(label_quo)
show_labels <- !(is.null(label_expr) || isFALSE(label_expr))
label_values <- if (show_labels && !isTRUE(label_expr)) {
embedding_values(label_quo, df, "label")$values
}
if (show_labels && !isTRUE(label_expr) && is.logical(label_values) && length(label_values) == 1) {
show_labels <- isTRUE(label_values)
label_values <- NULL
}
plot_df <- data.frame(.x = df[[x]], .y = df[[y]])
if (!is.null(colour_values)) plot_df$.colour <- colour_values
if (!is.null(size_info$values)) plot_df$.size <- size_info$values
grouped <- !is.null(colour_values) && !is.numeric(colour_values)
if (hotelling == "group" && !grouped) {
stop("`hotelling = \"group\"` needs a discrete `color_by` to define the groups.", call. = FALSE)
}
# ellipses first: their insides are white, the rest of the panel grey
layers <- list()
inside <- list()
if (ellipse && hotelling == "all" && !grouped) {
warning("Without groups, the confidence ellipse is left out: the T-squared ellipse of ",
"`hotelling = \"all\"` already covers all the samples.", call. = FALSE)
ellipse <- FALSE
}
if (ellipse) {
ellipses <- embedding_ellipses(plot_df, grouped, ellipse_level, robust, distribution)
if (!is.null(ellipses)) {
outer <- ellipses[ellipses$.level == max(ellipse_level), , drop = FALSE]
inside <- c(inside, list(outer_shapes(outer, if (grouped) ".colour" else NULL)))
fill_alpha <- 0.12 / length(ellipse_level)
layers <- c(layers, list(if (grouped) {
ggplot2::geom_polygon(data = ellipses, ggplot2::aes(.data$x, .data$y, colour = .data$.colour,
fill = .data$.colour,
group = interaction(.data$.colour, .data$.level)),
alpha = fill_alpha, linewidth = 0.5 * scale, inherit.aes = FALSE,
show.legend = FALSE)
} else {
ggplot2::geom_polygon(data = ellipses, ggplot2::aes(.data$x, .data$y, group = .data$.level),
colour = "grey40", fill = "grey60", alpha = fill_alpha,
linewidth = 0.5 * scale, inherit.aes = FALSE)
}))
}
}
t2 <- NULL
model <- NULL
if (hotelling != "none") {
check_count(ncomp, "ncomp", lower = 2)
t2_cols <- unique(c(x, y, embedding_components(df, sum(vapply(df, is.numeric, logical(1))))))
if (length(t2_cols) < ncomp) {
stop("'data' has fewer than ", ncomp, " numeric columns for the T-squared.", call. = FALSE)
}
by_group <- hotelling == "group"
model <- if (by_group) NULL else model_t2_parts(data, t2_cols[seq_len(ncomp)], x, y)
if (!is.null(model)) {
# the T-squared of the PCA model: its eigenvalues, centered at 0
t2 <- model_t2_flags(model, t2_level, t2_method)
limits <- model_t2_ellipses(model, x, y, t2_level, t2_method)
} else {
t2 <- hotelling_t2(df, columns = t2_cols[seq_len(ncomp)],
group = if (by_group) colour_values else NULL, conf_level = t2_level,
method = t2_method)
t2$.flag <- t2[[paste0("outlier_", conf_label(max(t2_level)))]]
limits <- hotelling_ellipses(plot_df, by_group, t2_level, t2_method)
}
if (!is.null(limits)) {
outer <- limits[limits$limit == t2_names(max(t2_level)), , drop = FALSE]
inside <- c(inside, list(outer_shapes(outer, if (by_group) ".colour" else NULL)))
if (by_group) {
# the ellipses of the groups filled with their color
layers <- c(layers, list(ggplot2::geom_polygon(
data = limits, ggplot2::aes(.data$x, .data$y, fill = .data$.colour,
group = interaction(.data$.colour, .data$limit)),
alpha = 0.12 / length(t2_level), colour = NA, inherit.aes = FALSE, show.legend = FALSE
)))
}
layers <- c(layers, list(if (by_group) {
ggplot2::geom_path(data = limits, ggplot2::aes(.data$x, .data$y, colour = .data$.colour,
linetype = .data$limit,
group = interaction(.data$.colour, .data$limit)),
linewidth = 0.5 * scale, inherit.aes = FALSE, show.legend = FALSE)
} else {
ggplot2::geom_path(data = limits, ggplot2::aes(.data$x, .data$y, linetype = .data$limit),
colour = "grey30", linewidth = 0.5 * scale, inherit.aes = FALSE)
}, ggplot2::scale_linetype_manual(values = t2_linetypes(t2_level), guide = "none")))
# the limits are labeled on the ellipses (at their top), not in a legend
tops <- t2_label_positions(limits, by_group)
layers <- c(layers, list(if (by_group) {
ggplot2::geom_text(data = tops, ggplot2::aes(.data$x, .data$y, label = .data$limit,
colour = .data$.colour),
hjust = -0.1, vjust = -0.3, size = 2.5 * scale, inherit.aes = FALSE,
show.legend = FALSE)
} else {
ggplot2::geom_text(data = tops, ggplot2::aes(.data$x, .data$y, label = .data$limit),
hjust = -0.1, vjust = -0.3, size = 2.5 * scale, colour = "grey30",
inherit.aes = FALSE)
}))
}
}
p <- ggplot2::ggplot(plot_df, ggplot2::aes(.data$.x, .data$.y))
outer <- if (panel == "shaded") do.call(rbind, inside)
if (!is.null(outer)) {
p <- p + ggplot2::geom_polygon(data = outer, ggplot2::aes(.data$x, .data$y, group = .data$.shape),
fill = "white", colour = NA, inherit.aes = FALSE)
}
for (layer in layers) p <- p + layer
# the axes through the origin, when it lies in the range of the samples
# (they would otherwise stretch the axes), except on a UMAP map, whose
# origin means nothing
if (!umap && min(plot_df$.y, na.rm = TRUE) <= 0 && max(plot_df$.y, na.rm = TRUE) >= 0) {
p <- p + ggplot2::geom_hline(yintercept = 0, colour = "grey75", linewidth = 0.3)
}
if (!umap && min(plot_df$.x, na.rm = TRUE) <= 0 && max(plot_df$.x, na.rm = TRUE) >= 0) {
p <- p + ggplot2::geom_vline(xintercept = 0, colour = "grey75", linewidth = 0.3)
}
loadings <- NULL
if (biplot) {
loadings <- embedding_loadings(data, x, y, plot_df, biplot_top)
p <- p + ggplot2::geom_point(data = loadings$all, ggplot2::aes(.data$x, .data$y),
colour = "grey45", size = 0.6 * scale, alpha = 0.35,
inherit.aes = FALSE)
}
n_groups <- if (grouped) length(unique(stats::na.omit(colour_values))) else 0
# a shape per group, so that the groups stay apart in grayscale
by_shape <- shapes && grouped && n_groups <= 6
point_aes <- ggplot2::aes()
if (!is.null(colour_values)) point_aes$colour <- quote(.data$.colour)
if (by_shape) point_aes$shape <- quote(.data$.colour)
if (!is.null(size_info$values)) point_aes$size <- quote(.data$.size)
point_args <- list(mapping = point_aes, alpha = point_alpha)
if (is.null(colour_values)) point_args$colour <- "#1f4e79"
if (is.null(size_info$values)) point_args$size <- point_size
p <- p + do.call(ggplot2::geom_point, point_args)
if (!is.null(colour_values)) {
p <- p + if (!is.null(palette)) {
palette_scale(palette, discrete = !is.numeric(colour_values),
aesthetics = if (is.numeric(colour_values)) "colour" else c("colour", "fill"),
name = colour_name, n = n_groups)
} else if (is.numeric(colour_values)) {
ggplot2::scale_colour_viridis_c(name = colour_name, end = 0.9)
} else if (n_groups <= 8) {
ggplot2::scale_colour_brewer(name = colour_name, palette = "Dark2",
aesthetics = c("colour", "fill"))
} else {
ggplot2::scale_colour_discrete(name = colour_name, aesthetics = c("colour", "fill"))
}
if (by_shape) {
p <- p + ggplot2::scale_shape_manual(name = colour_name, values = c(16, 17, 15, 18, 3, 4))
}
if (!is.numeric(colour_values)) {
# keys of one size, whatever the size of the points
p <- p + ggplot2::guides(colour = ggplot2::guide_legend(override.aes = list(size = 2.5 * scale)),
fill = "none")
}
}
if (!is.null(size_info$values)) {
p <- p + ggplot2::scale_size_continuous(range = c(1, 6) * scale, name = size_info$name,
breaks = three_breaks)
}
if (!is.null(loadings)) {
top <- loadings$top
if (nrow(top) > 0) {
p <- p +
ggplot2::geom_segment(data = top, ggplot2::aes(x = 0, y = 0, xend = .data$x, yend = .data$y),
colour = "#7f0000", linewidth = 0.4 * scale, inherit.aes = FALSE,
arrow = ggplot2::arrow(length = ggplot2::unit(0.15 * scale, "cm"))) +
# labels at the arrow tips, moved apart by ggrepel
ggrepel::geom_text_repel(data = top[top$labeled, , drop = FALSE],
ggplot2::aes(.data$x, .data$y, label = .data$label),
colour = "#7f0000", size = 2.6 * scale, segment.colour = "#7f000080",
min.segment.length = 0.2, max.overlaps = Inf, seed = 1,
inherit.aes = FALSE)
}
}
# the samples beyond the limit: circled (flag) and labeled (label), independently
if ((flag || show_labels) && !is.null(t2) && any(t2$.flag)) {
out <- plot_df[t2$sample[t2$.flag], , drop = FALSE]
out$.label <- if (is.null(label_values)) t2$sample[t2$.flag] else
label_values[t2$sample[t2$.flag]]
if (flag) {
circle <- if (is.null(size_info$values)) point_size + 2.5 * scale else 7 * scale
p <- p +
ggplot2::geom_point(data = out, ggplot2::aes(.data$.x, .data$.y), shape = 21, size = circle,
colour = "#c0392b", stroke = 0.8 * scale, inherit.aes = FALSE)
}
if (show_labels) {
# moved apart by ggrepel, away from all the samples (unlabeled ones
# have an empty label)
labeled <- plot_df
labeled$.label <- ""
labeled$.label[t2$sample[t2$.flag]] <- as.character(out$.label)
p <- p + ggrepel::geom_text_repel(data = labeled,
ggplot2::aes(.data$.x, .data$.y, label = .data$.label),
size = 3 * scale, colour = "#c0392b", box.padding = 0.4,
segment.colour = "#c0392b80", min.segment.length = 0.2,
max.overlaps = Inf, seed = 1, na.rm = TRUE,
inherit.aes = FALSE)
}
}
subtitle <- if (!is.null(t2)) {
n_flag <- sum(t2$.flag)
sprintf("Hotelling T\u00b2 (%d components%s): %d %s beyond the %s%% limit",
ncomp, if (hotelling == "group") ", within groups" else "", n_flag,
if (n_flag == 1) "sample" else "samples", conf_label(max(t2_level)))
}
if (!is.null(loadings)) {
fx <- loadings$factor[["x"]]
fy <- loadings$factor[["y"]]
p <- p +
ggplot2::scale_x_continuous(labels = plain_numbers, sec.axis = ggplot2::sec_axis(
~ . / fx, name = paste(x, "loading"), labels = plain_numbers)) +
ggplot2::scale_y_continuous(labels = plain_numbers, sec.axis = ggplot2::sec_axis(
~ . / fy, name = paste(y, "loading"), labels = plain_numbers))
} else {
p <- p + ggplot2::scale_x_continuous(labels = plain_numbers) +
ggplot2::scale_y_continuous(labels = plain_numbers)
}
if (equal) {
p <- p + ggplot2::coord_fixed(ratio = 1)
}
caption_text <- if (isTRUE(caption)) {
embedding_caption(ellipse, ellipse_level, grouped, robust, distribution, t2, hotelling, ncomp,
t2_level, t2_method, robust_model = isTRUE(model$robust), flag = flag,
biplot = !is.null(loadings), umap = umap,
shaded = panel == "shaded" && !is.null(outer))
} else if (is.character(caption)) {
caption
}
# grey outside the ellipses, white inside
p <- p +
ggplot2::labs(x = xlab %||% axis_title(x, variance), y = ylab %||% axis_title(y, variance),
title = title,
subtitle = subtitle, caption = caption_text) +
ggplot2::theme_grey(base_size = base_size) +
ggplot2::theme(
aspect.ratio = if (equal) NULL else aspect_ratio,
panel.grid = ggplot2::element_blank(),
panel.background = ggplot2::element_rect(fill = if (is.null(outer)) "white" else "grey90",
colour = "black", linewidth = 0.3),
legend.key = ggplot2::element_rect(fill = "white", colour = NA),
plot.caption = ggplot2::element_text(hjust = 0, colour = "grey30", size = ggplot2::rel(0.8)),
plot.caption.position = "plot"
) +
legend_theme(legend) +
compact_legend(base_size)
finish_title(p)
}
# ---- internals ---------------------------------------------------------------
# The caption: what the ellipses and the limits are, and how to read the plot.
embedding_caption <- function(ellipse, levels, grouped, robust, distribution, t2, hotelling, ncomp,
t2_level, t2_method, robust_model, flag, biplot, umap, shaded) {
pct <- function(l) paste0(paste(conf_label(l), collapse = " and "), "%")
parts <- character()
if (ellipse) {
parts <- c(parts, paste0(
"Ellipses: ", pct(levels), " confidence region", if (grouped || length(levels) > 1) "s",
" of ", if (grouped) "each group" else "the samples", ", bivariate normal, from the ",
if (robust) "robust (MCD) ", "mean and covariance (",
if (distribution == "hotelling") "Hotelling's T\u00b2 quantile" else "chi-square quantile", ")."
))
}
if (!is.null(t2)) {
limit <- if (robust_model) {
"the chi-square quantile of ROBPCA (Hubert et al., 2005)"
} else {
switch(t2_method, f = "F distribution (Jackson, 1991)",
beta = "Beta distribution of the calibration samples (Tracy et al., 1992)",
new = "F distribution of a new sample")
}
parts <- c(parts, paste0(
"Hotelling's T\u00b2 limit", if (length(t2_level) > 1) "s", " at ", pct(t2_level), " on ", ncomp,
" components", if (hotelling == "group") ", within each group", ": ", limit, "."
))
if (flag) parts <- c(parts, "Circled: the samples beyond the limit.")
}
if (biplot) parts <- c(parts, "Arrows: the loadings, read on the top and right axes.")
if (shaded) parts <- c(parts, "Grey: outside the outermost ellipse.")
if (umap) parts <- c(parts, "On a UMAP map, only the neighborhoods are meaningful.")
if (length(parts) == 0) {
return(NULL)
}
paste(strwrap(paste(parts, collapse = " "), width = 80), collapse = "\n")
}
# Legend labels and line types of the T-squared ellipses: the highest level
# solid, the others dashed, dotted, ...
t2_names <- function(levels) paste0("T\u00b2 ", conf_label(levels), "%")
t2_linetypes <- function(levels) {
types <- c("solid", "dashed", "dotted", "dotdash", "longdash", "twodash")
stats::setNames(types[rev(seq_along(levels))], t2_names(levels))
}
# Hotelling's T-squared ellipses of the groups or of all samples, at each level.
hotelling_ellipses <- function(plot_df, by_group, levels, method) {
rlang::check_installed("HotellingEllipse", version = "1.3.0",
reason = "to draw Hotelling's T-squared ellipses.")
df <- plot_df[stats::complete.cases(plot_df[c(".x", ".y")]), , drop = FALSE]
labels <- t2_names(levels)
# contours T2 = limit, rotated to the covariance of the two components
ellipse_of <- function(d) {
do.call(rbind, lapply(seq_along(levels), function(i) {
e <- as.data.frame(HotellingEllipse::ellipseCoord(
d[c(".x", ".y")], conf.limit = levels[i], method = if (method == "new") "f" else method
))
if (method == "new") {
# the limit of a new sample is the F limit times (n + 1) / n
center <- colMeans(d[c(".x", ".y")])
grow <- sqrt((nrow(d) + 1) / nrow(d))
e$x <- center[[1]] + (e$x - center[[1]]) * grow
e$y <- center[[2]] + (e$y - center[[2]]) * grow
}
e$limit <- factor(labels[i], levels = labels)
e
}))
}
if (!by_group) {
return(if (nrow(df) > 3) ellipse_of(df))
}
groups <- split(df, as.character(df$.colour))
groups <- groups[vapply(groups, nrow, integer(1)) > 3]
if (length(groups) == 0) return(NULL)
out <- do.call(rbind, lapply(names(groups), function(g) {
e <- ellipse_of(groups[[g]])
e$.colour <- g
e
}))
if (is.factor(df$.colour)) out$.colour <- factor(out$.colour, levels = levels(df$.colour))
out
}
# Scores and variances of the components of a PCA model, for its T-squared,
# or NULL when `data` is not a PCA model or the components are not its own.
model_t2_parts <- function(data, components, x, y) {
if (inherits(data, "prcomp")) {
scores <- data$x
lambda <- data$sdev[seq_len(ncol(scores))]^2
robust <- FALSE
} else if (inherits(data, "specproc_robpca") && length(data$eigenvalues) == ncol(data$scores)) {
scores <- data$scores
lambda <- data$eigenvalues
robust <- TRUE
} else {
return(NULL)
}
names(lambda) <- colnames(scores)
if (!all(c(components, x, y) %in% colnames(scores))) return(NULL)
list(scores = scores[, components, drop = FALSE], lambda = lambda, n = nrow(scores),
robust = robust)
}
# T-squared limit on `a` components: the chi-square quantile of ROBPCA for
# robust fits (the score distance cut-off), the F or Beta limit otherwise.
model_t2_limit <- function(model, level, a, method) {
if (model$robust) stats::qchisq(level, a) else t2_limit(level, a, model$n, method)
}
model_t2_flags <- function(model, levels, method) {
a <- ncol(model$scores)
t2 <- rowSums(sweep(model$scores^2, 2, model$lambda[colnames(model$scores)], "/"))
data.frame(sample = seq_len(model$n), t2 = unname(t2),
.flag = unname(t2 > model_t2_limit(model, max(levels), a, method)))
}
# The T-squared ellipses of the two components shown: centered at 0, with the
# axes of the components, and semi-axes sqrt(lambda * limit).
model_t2_ellipses <- function(model, x, y, levels, method) {
angle <- seq(0, 2 * pi, length.out = 361)
labels <- t2_names(levels)
do.call(rbind, lapply(seq_along(levels), function(i) {
limit <- model_t2_limit(model, levels[i], 2, method)
data.frame(x = sqrt(model$lambda[[x]] * limit) * cos(angle),
y = sqrt(model$lambda[[y]] * limit) * sin(angle),
limit = factor(labels[i], levels = labels))
}))
}
# Share of the variance of each component of a PCA fit (named like the
# score columns), or NULL: of the total variance for a prcomp fit, of the
# variance of the ncomp components for a robust fit.
embedding_variance <- function(data) {
if (inherits(data, "prcomp")) {
v <- data$sdev^2
return(stats::setNames(v / sum(v), colnames(data$x) %||% paste0("PC", seq_along(v)))[seq_len(ncol(data$x))])
}
if (inherits(data, "specproc_robpca")) {
v <- data$eigenvalues
if (length(v) == 0 || (!is.null(data$scores) && length(v) != ncol(data$scores))) return(NULL)
return(stats::setNames(v / sum(v), colnames(data$scores) %||% paste0("PC", seq_along(v))))
}
NULL
}
axis_title <- function(axis, variance) {
if (is.null(variance) || !axis %in% names(variance)) return(axis)
sprintf("%s (%.1f%%)", axis, 100 * variance[[axis]])
}
# Upper-right point of each T-squared ellipse (per level, and per group),
# for its label: away from the vertical line through the origin.
t2_label_positions <- function(limits, by_group) {
keys <- if (by_group) interaction(limits$.colour, limits$limit, drop = TRUE) else limits$limit
span_x <- diff(range(limits$x))
span_y <- diff(range(limits$y))
do.call(rbind, lapply(split(limits, keys, drop = TRUE), function(e) {
e[which.max(e$x / span_x + e$y / span_y), , drop = FALSE]
}))
}
# Three rounded breaks (minimum, middle, maximum) for a size legend.
three_breaks <- function(limits) {
unique(signif(seq(limits[1], limits[2], length.out = 3), 2))
}
# Smaller legend text, titles and keys, closer together.
compact_legend <- function(base_size = 11) {
ggplot2::theme(
legend.text = ggplot2::element_text(size = 8 * base_size / 11),
legend.title = ggplot2::element_text(size = 9 * base_size / 11),
legend.key.size = ggplot2::unit(0.35 * base_size / 11, "cm"),
legend.spacing.y = ggplot2::unit(0.15, "cm"),
legend.margin = ggplot2::margin(2, 2, 2, 2)
)
}
# The outermost ellipses (one per group), as polygons to fill in white.
outer_shapes <- function(ellipses, group) {
key <- if (is.null(group)) "all" else as.character(ellipses[[group]])
data.frame(x = ellipses$x, y = ellipses$y, .shape = paste(key, "outer", sep = "_"))
}
# A constant point size, or one value per sample to map.
embedding_size <- function(quo, df, arg = "point_size") {
expr <- rlang::quo_get_expr(quo)
if (is.numeric(expr) && length(expr) == 1) {
check_number(expr, arg, lower = 0, lower_open = TRUE)
return(list(constant = expr, values = NULL, name = NULL))
}
info <- embedding_values(quo, df, arg)
if (is.null(info$values)) return(list(constant = NULL, values = NULL, name = NULL))
if (length(info$values) == 1 && is.numeric(info$values)) {
check_number(info$values, arg, lower = 0, lower_open = TRUE)
return(list(constant = info$values, values = NULL, name = NULL))
}
if (!is.numeric(info$values)) {
stop("`", arg, "` must be a number, or a numeric column or vector with one value per sample.",
call. = FALSE)
}
list(constant = NULL, values = info$values, name = info$name)
}
# Loadings of the two components, each scaled to the range of its scores:
# all the variables, and the `top` longest in the plane of the plot (for
# spectra, the peaks of the length along the wavelength, one per line).
embedding_loadings <- function(data, x, y, plot_df, top) {
p <- if (inherits(data, "prcomp")) data$rotation else if (inherits(data, "specproc_robpca")) data$loadings
if (is.null(p)) {
stop("`biplot = TRUE` needs a prcomp fit or a robust PCA object (robpca(), rospca(), ",
"macropca()).", call. = FALSE)
}
if (!all(c(x, y) %in% colnames(p))) {
stop("`biplot = TRUE` needs axes that are components of the model (", x, ", ", y, ").",
call. = FALSE)
}
load <- data.frame(x = p[, x], y = p[, y])
variables <- rownames(p) %||% as.character(seq_len(nrow(p)))
wavelength <- names_to_wavelength(variables)
spectral <- length(wavelength) == length(variables)
load$label <- if (spectral) format_wavelength(wavelength, wavelength_digits(wavelength)) else variables
factor <- c(
x = 0.8 * max(abs(plot_df$.x), na.rm = TRUE) / max(abs(load$x), .Machine$double.eps),
y = 0.8 * max(abs(plot_df$.y), na.rm = TRUE) / max(abs(load$y), .Machine$double.eps)
)
load$x <- load$x * factor[["x"]]
load$y <- load$y * factor[["y"]]
norm <- sqrt((load$x / factor[["x"]])^2 + (load$y / factor[["y"]])^2)
candidates <- if (spectral && length(variables) > 20) {
local_maxima(norm, wavelength_segments(wavelength), span = 5)
} else {
seq_along(norm)
}
chosen <- candidates[order(norm[candidates], decreasing = TRUE)][seq_len(min(top, length(candidates)))]
top_load <- load[chosen, , drop = FALSE]
# arrows shorter than a fifth of the longest are drawn without a label,
# which would overlap the others near the origin
top_load$labeled <- norm[chosen] >= 0.2 * max(norm[chosen])
list(all = load, top = top_load, factor = factor)
}
# Coordinates of the confidence ellipses of the groups (or of all samples).
embedding_ellipses <- function(plot_df, grouped, levels, robust, distribution) {
rlang::check_installed("ConfidenceEllipse", reason = "to draw confidence ellipses.")
df <- plot_df[stats::complete.cases(plot_df), , drop = FALSE]
ellipse_of <- function(d) {
do.call(rbind, lapply(levels, function(l) {
e <- as.data.frame(ConfidenceEllipse::confidence_ellipse(
d, ".x", ".y", conf_level = l, robust = robust, distribution = distribution
))
e$.level <- l
e
}))
}
if (!grouped) {
if (nrow(df) < 4) return(NULL)
return(ellipse_of(df))
}
groups <- split(df, as.character(df$.colour))
small <- names(groups)[vapply(groups, nrow, integer(1)) < 4]
if (length(small) > 0) {
warning("No ellipse for the group(s) with fewer than 4 samples: ",
paste(small, collapse = ", "), ".", call. = FALSE)
}
groups <- groups[setdiff(names(groups), small)]
if (length(groups) == 0) return(NULL)
out <- do.call(rbind, lapply(names(groups), function(g) {
e <- as.data.frame(ellipse_of(groups[[g]]))
e$.colour <- g
e
}))
if (is.factor(df$.colour)) out$.colour <- factor(out$.colour, levels = levels(df$.colour))
out
}
embedding_data <- function(data) {
if (inherits(data, "prcomp")) return(as.data.frame(data$x))
if (is.list(data) && !is.data.frame(data) && is.matrix(data$scores)) {
scores <- data$scores
if (is.null(colnames(scores))) colnames(scores) <- paste0("PC", seq_len(ncol(scores)))
return(as.data.frame(scores))
}
if (is.matrix(data)) {
data <- as.data.frame(data)
if (all(grepl("^V[0-9]+$", names(data)))) names(data) <- paste0("Dim", seq_along(data))
return(data)
}
if (!is.data.frame(data)) {
stop("'data' must be a data frame, a matrix, a prcomp fit or a robust PCA object.",
call. = FALSE)
}
as.data.frame(data)
}
embedding_column <- function(quo, df, arg) {
if (rlang::quo_is_null(quo)) return(NULL)
name <- rlang::as_name(quo)
if (!name %in% names(df) || !is.numeric(df[[name]])) {
stop("`", arg, "` must be a numeric column of 'data'.", call. = FALSE)
}
name
}
# The first two embedding coordinates, or else the first two numeric columns.
embedding_axes <- function(df) {
numeric_cols <- names(df)[vapply(df, is.numeric, logical(1))]
coords <- grep("^(UMAP|PC|Comp|Dim|tSNE|TSNE|IC|LV)_?[0-9]+$", numeric_cols, value = TRUE,
ignore.case = TRUE)
axes <- if (length(coords) >= 2) coords else numeric_cols
c(axes, NA_character_, NA_character_)[1:2]
}
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.