factoextra (version 2.2.0)

fviz_umap: Visualize a UMAP or t-SNE embedding

Description

fviz_umap() and fviz_tsne() draw a ggplot2 scatter plot of a two-dimensional embedding produced by UMAP or t-SNE, with factoextra's grouping, ellipse and palette styling. They accept the result of uwot::umap() / umap::umap() / Rtsne::Rtsne(), or a plain matrix / data frame of coordinates.

Unlike PCA, an embedding has no eigenvalues: the axes explain no fixed percentage of variance, so they are labelled UMAP1/UMAP2 (tSNE1/tSNE2) without a percentage, and there is deliberately no scree plot, no variable loadings, and no correlation circle - those are meaningless for an embedding. For methods that do have eigenvalues (PCA, CA, MCA, MDS) see fviz_pca and as_factoextra_pca.

Read more: UMAP in R: Nonlinear Dimension Reduction & Visualization and t-SNE in R: Visualize High-Dimensional Data.

Usage

fviz_umap(
  X,
  dims = c(1L, 2L),
  habillage = NULL,
  col.ind = NULL,
  geom = "point",
  label = FALSE,
  pointsize = 1.5,
  labelsize = 4,
  addEllipses = FALSE,
  ellipse.type = "convex",
  ellipse.level = 0.95,
  mean.point = FALSE,
  palette = NULL,
  gradient.cols = NULL,
  density = FALSE,
  facet.by = NULL,
  repel = TRUE,
  max.points = NULL,
  sample.seed = 123,
  legend.title = NULL,
  caption = NULL,
  ggtheme = theme_minimal(),
  ...
)
fviz_tsne(
  X,
  dims = c(1L, 2L),
  habillage = NULL,
  col.ind = NULL,
  geom = "point",
  label = FALSE,
  pointsize = 1.5,
  labelsize = 4,
  addEllipses = FALSE,
  ellipse.type = "convex",
  ellipse.level = 0.95,
  mean.point = FALSE,
  palette = NULL,
  gradient.cols = NULL,
  density = FALSE,
  facet.by = NULL,
  repel = TRUE,
  max.points = NULL,
  sample.seed = 123,
  legend.title = NULL,
  caption = NULL,
  ggtheme = theme_minimal(),
  ...
)

Value

a ggplot2 object.

Arguments

X

an embedding: a uwot::umap() result (a matrix, or a list with $embedding), an Rtsne::Rtsne() result ($Y), a umap::umap() result ($layout), or a numeric matrix / data frame of coordinates (one column per dimension).

dims

two distinct positive integer indices specifying which embedding dimensions to plot.

habillage

an optional factor / vector used to colour the points by group (discrete). Its length must equal the number of embedded observations.

col.ind

point colour: a factor / character vector (discrete groups) or a numeric vector to colour by a continuous feature value (as in a Seurat feature plot). A single colour name is also allowed. The eigenvalue metrics accepted by fviz_pca_ind ("cos2", "contrib", ...) are rejected here - an embedding has no such quantities.

geom

character: "point" and/or "text".

label

logical; if TRUE, label the points by row name.

pointsize, labelsize

point and label size.

addEllipses

logical; if TRUE, draw an outline around each group. Default FALSE. When TRUE the default ellipse.type is "convex" (a hull) rather than a normal/t confidence ellipse: a confidence ellipse assumes a metric that UMAP/t-SNE do not preserve.

ellipse.type, ellipse.level

ellipse type and confidence level. See fviz_cluster.

mean.point

logical; if TRUE, show group mean points. Default FALSE - a centroid in embedding space is not a feature-space mean.

palette, gradient.cols

discrete group palette / continuous colour gradient, passed to ggpar.

density

logical; if TRUE, overlay 2D density contour lines (a visual aid, not a probability readout).

facet.by

optional variable (length = number of observations) to facet by.

repel

logical; if TRUE, use ggrepel for labels.

max.points, sample.seed

passed to the downsampling used for large embeddings; see fviz_pca_ind.

legend.title

colour legend title. Defaults to "Groups" for a discrete colouring and "value" for a continuous feature.

caption

optional plot caption (e.g. an interpretation reminder). Off by default.

ggtheme, ...

passed to ggscatter / ggplot2.

Details

UMAP and t-SNE produce a low-dimensional embedding, not a variance decomposition. Local relationships are often more informative than global geometry, but both remain method- and parameter-dependent. In particular, the size of a cluster, the distance between well-separated clusters, and the amount of empty space between them are not quantitatively meaningful and change with perplexity or n_neighbors (Wattenberg et al., 2016). Similar embedding scatter plots are drawn by Seurat::DimPlot() / FeaturePlot() and ggpca.

References

McInnes, L., Healy, J. and Melville, J. (2018). UMAP: Uniform Manifold Approximation and Projection for Dimension Reduction. arXiv:1802.03426.

Wattenberg, M., Viégas, F. and Johnson, I. (2016). How to Use t-SNE Effectively. Distill. tools:::Rd_expr_doi("10.23915/distill.00002").

See Also

fviz_pca, as_factoextra_pca, fviz_cluster. Online tutorials: UMAP in R: Nonlinear Dimension Reduction & Visualization and t-SNE in R: Visualize High-Dimensional Data.

Examples

# \donttest{
if (requireNamespace("uwot", quietly = TRUE)) {
  set.seed(123)
  um <- uwot::umap(iris[, 1:4], n_neighbors = 15)
  fviz_umap(um, habillage = iris$Species, addEllipses = TRUE)
  # colour by a continuous feature value
  fviz_umap(um, col.ind = iris$Petal.Length)
}
# }