fviz_umap: Visualize a UMAP or t-SNE embedding

In factoextra: Extract and Visualize the Results of Multivariate Data Analyses

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(),
  ...
)

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.

Value

a ggplot2 object.

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. \Sexpr[results=rd]{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

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)
}

factoextra documentation built on July 24, 2026, 9:06 a.m.