Plot UMAP results

Convenience wrapper around plotDimRed() for UMAP embeddings returned by getUMAP(). Supports flexible visual encodings (colour, shape, size) of sample-level metadata, and can return multiple plots across UMAP component pairs and annotation variables.

plotUMAP(
  object,
  components = list(c(1, 2)),
  colour = NULL,
  colourPalette = NULL,
  NAcolour = "grey50",
  symDivColourScale = FALSE,
  shape = NULL,
  shapePalette = NULL,
  NAshape = NULL,
  showSampleNames = FALSE,
  pointSize = 2,
  alpha = 1,
  plotlyAnnotations = ""
)

Arguments

object

mesaDimRed. A dimensionality-reduction container returned by getUMAP().

components

integer(2) or list of integer(2). UMAP indices to plot (e.g. c(1, 2) for UMAP1 vs UMAP2), or a list of such pairs to produce multiple plots. Default: list(c(1, 2)).

colour

NULL or character(). Name(s) of sample-table variable(s) mapped to point colour; one plot per variable. Default: NULL (no colour mapping).

colourPalette

NULL or character(). Palette used for colouring points. If NULL, a suitable default is chosen. Default: NULL.

NAcolour

character(1). Colour for missing values in colour. Default: "grey50".

symDivColourScale

logical(1). If TRUE, diverging colour scales are centred symmetrically around zero. Ignored for non-diverging scales. Default: FALSE.

shape

NULL or character(1). Sample-table variable mapped to point shape (single variable only). Default: NULL.

shapePalette

NULL, character(1), or numeric(). Shapes used for categories of the shape variable. Options:

A numeric vector of base-R shape codes.
- 0–20: line/filled shapes.
- 21–25: filled shapes with a border (border colour = black).
A keyword, with internally defined sets:

"line-first": 15 line shapes, then 4 filled shapes (max 19 categories).
"filled-first": 4 filled shapes, then 15 line shapes (max 19 categories).
- "mixture": mixture of line and filled shapes (max 19 categories).
"filled+border": filled+border shapes (max 5 categories, or 4 if NAs in shape).

NULL: choose automatically ("mixture" for non-diverging/none; "filled+border" for diverging colour scales). Default: NULL.

NAshape

NULL or numeric(1). Shape for missing values in shape. If NULL, uses 7, or 25 when "filled+border" is active. Default: NULL.

showSampleNames

logical(1). Overlay sample names on points. Default: FALSE.

pointSize

numeric(1). Point size. Default: 2.

alpha

numeric(1). Point transparency in [0, 1]. Default: 1.

plotlyAnnotations

character(). Column names from the sample table to add as tooltips when converting to interactive plotly. Default: "" (empty string).

Value

A list of ggplot objects—one per combination of components pairs and colour variables—each depicting the chosen UMAP dimensions with requested aesthetics. Specifically:

one plot per components pair × per colour variable;
shapes/labels applied per shape/showSampleNames;
consistent axis labelling (UMAP1/UMAP2 etc.).

Examples

data(exampleTumourNormal, package = "mesa")

# Default UMAP (beta-normalised, top 1000 most variable windows)
exampleTumourNormal %>%
    getUMAP(n_neighbors = 5, min_dist = 1) %>%
    plotUMAP()
#> ------------------------------
#> Initial number of windows = 819.
#> -----------
#> Generating table of beta values for 819 regions across 10 samples.
#> -----------
#> Filtered out 220 windows with at least one missing value: 599 windows remaining.
#> ------------------------------
#> The following topVarNum values are larger than the number of remaining windows (= 599): 1000
#> These values are not used; UMAP will be done with all remaining windows instead.
#> ------------------------------
#> No filtering of windows based on window standard deviation.
#> Performing UMAP with 10 samples and 599 windows
#> -> umap1.
#> ------------------------------
#> $umap1
#> $umap1$UMAP1vsUMAP2

#> 
#> 

# Colour by group; show names
exampleTumourNormal %>%
    getUMAP(n_neighbors = 5, min_dist = 1) %>%
    plotUMAP(
        colour = "group",
        showSampleNames = TRUE
    )
#> ------------------------------
#> Initial number of windows = 819.
#> -----------
#> Generating table of beta values for 819 regions across 10 samples.
#> -----------
#> Filtered out 220 windows with at least one missing value: 599 windows remaining.
#> ------------------------------
#> The following topVarNum values are larger than the number of remaining windows (= 599): 1000
#> These values are not used; UMAP will be done with all remaining windows instead.
#> ------------------------------
#> No filtering of windows based on window standard deviation.
#> Performing UMAP with 10 samples and 599 windows
#> -> umap1.
#> ------------------------------
#> $umap1
#> $umap1$group
#> $umap1$group$UMAP1vsUMAP2

#> 
#> 
#> 

# Custom components and shape mapping
exampleTumourNormal %>%
    getUMAP(n_neighbors = 5, min_dist = 1) %>%
    plotUMAP(
        components = list(c(1, 2)),
        colour = "group",
        shape = "tissue"
    )
#> ------------------------------
#> Initial number of windows = 819.
#> -----------
#> Generating table of beta values for 819 regions across 10 samples.
#> -----------
#> Filtered out 220 windows with at least one missing value: 599 windows remaining.
#> ------------------------------
#> The following topVarNum values are larger than the number of remaining windows (= 599): 1000
#> These values are not used; UMAP will be done with all remaining windows instead.
#> ------------------------------
#> No filtering of windows based on window standard deviation.
#> Performing UMAP with 10 samples and 599 windows
#> -> umap1.
#> ------------------------------
#> $umap1
#> $umap1$group
#> $umap1$group$UMAP1vsUMAP2

#> 
#> 
#>

Arguments

Value

See also

Examples