plotDimRed: Generate scatter plot(s) using liger object

In rliger: Linked Inference of Genomic Experimental Relationships

Generate scatter plot(s) using liger object

Description

This function allows for using available cell metadata to build the x-/y-axis. Available per-cell data can be used to form the color/shape annotation, including cell metadata, raw or processed gene expression, and unnormalized or aligned factor loading. Multiple coloring variable is allowed from the same specification of slot, and this returns a list of plots with different coloring values. Users can further split the plot(s) by grouping on cells (e.g. datasets).

Usage

plotDimRed(
  object,
  colorBy = NULL,
  useDimRed = NULL,
  slot = c("cellMeta", "rawData", "normData", "scaleData", "H.norm", "H", "normPeak",
    "rawPeak"),
  colorByFunc = NULL,
  cellIdx = NULL,
  splitBy = NULL,
  shapeBy = NULL,
  titles = NULL,
  ...
)

plotClusterDimRed(object, useCluster = NULL, useDimRed = NULL, ...)

plotDatasetDimRed(object, useDimRed = NULL, ...)

plotByDatasetAndCluster(
  object,
  useDimRed = NULL,
  useCluster = NULL,
  combinePlot = TRUE,
  ...
)

plotGeneDimRed(
  object,
  features,
  useDimRed = NULL,
  log = TRUE,
  scaleFactor = 10000,
  zeroAsNA = TRUE,
  colorPalette = "C",
  ...
)

plotPeakDimRed(
  object,
  features,
  useDimRed = NULL,
  log = TRUE,
  scaleFactor = 10000,
  zeroAsNA = TRUE,
  colorPalette = "C",
  ...
)

plotFactorDimRed(
  object,
  factors,
  useDimRed = NULL,
  trimHigh = 0.03,
  zeroAsNA = TRUE,
  colorPalette = "D",
  ...
)

Arguments

object	A liger object.
colorBy	Available variable name in specified slot to look for color annotation information. See details. Default NULL generates all-black dots.
useDimRed	Name of the variable storing dimensionality reduction result in the cellMeta(object). Default NULL use default dimRed.
slot	Choose the slot to find the colorBy variable. See details. Default "cellMeta".
colorByFunc	Default NULL. A function object that expects a vector/factor/data.frame retrieved by colorBy as the only input, and returns an object of the same size, so that the all color "aes" are replaced by this output. Useful when, for example, users need to scale the gene expression shown on plot.
cellIdx	Character, logical or numeric index that can subscribe cells. Missing or NULL for all cells.
splitBy	Character vector of categorical variable names in cellMeta slot. Split all cells by groupings on this/these variable(s) to produce a scatter plot containing only the cells in each group. Default NULL.
shapeBy	Available variable name in cellMeta slot to look for categorical annotation to be reflected by dot shapes. Default NULL.
titles	Title text. A character scalar or a character vector with as many elements as multiple plots are supposed to be generated. Default NULL.
...	Arguments passed on to .ggScatter, .ggplotLigerTheme dotOrder Controls the order that each dot is added to the plot. Choose from "shuffle", "ascending", or "descending". Default "shuffle", useful when coloring by categories that overlaps (e.g. "dataset"), "ascending" can be useful when coloring by a continuous variable (e.g. gene expression) where high values needs more highlight. NULL use default order. dotSize,dotAlpha Numeric, controls the size or transparency of all dots. Default getOption("ligerDotSize") (1) and 0.9. trimHigh,trimLow Numeric, limit the largest or smallest value of continuous colorBy variable. Default NULL. raster Logical, whether to rasterize the plot. Default NULL automatically rasterize the plot when number of total dots to be plotted exceeds 100,000. labelBy A variable name available in plotDF. If the variable is categorical (a factor), the label position will be the median coordinates of all dots within the same group. Unique labeling in character vector for each dot is also acceptable. Default colorBy. labelText Logical, whether to show text label at the median position of each categorical group specified by colorBy. Default TRUE. Does not work when continuous coloring is specified. labelTextSize Numeric, controls the size of label size when labelText = TRUE. Default 4. seed Random seed for reproducibility. Default 1. title,subtitle,xlab,ylab Main title, subtitle or X/Y axis title text. By default, no main title or subtitle will be set, and X/Y axis title will be the names of variables used for plotting. Use NULL to hide elements. TRUE for xlab or ylab shows default values. legendColorTitle Legend title text for color aesthetics, often used for categorical or continuous coloring of dots. Default NULL shows the original variable name. legendShapeTitle Legend title text for shape aesthetics, often used for shaping dots by categorical variable. Default NULL shows the original variable name. showLegend Whether to show the legend. Default TRUE. legendPosition Text indicating where to place the legend. Choose from "top", "bottom", "left" or "right". Default "right". baseSize One-parameter control of all text sizes. Individual text element sizes can be controlled by other size arguments. "Title" sizes are 2 points larger than "text" sizes when being controlled by this. titleSize,xTitleSize,yTitleSize,legendTitleSize Size of main title, axis titles and legend title. Default NULL controls by baseSize + 2. subtitleSize,xTextSize,yTextSize,legendTextSize Size of subtitle text, axis texts and legend text. Default NULL controls by baseSize. legendDotSize Allow dots in legend region to be large enough to see the colors/shapes clearly. Default 4. panelBorder Whether to show rectangle border of the panel instead of using ggplot classic bottom and left axis lines. Default FALSE. colorLabels Character vector for modifying category names in a color legend. Passed to ggplot2::scale_color_manual(labels). Default NULL uses original levels of the factor. colorValues Character vector of colors for modifying category colors in a color legend. Passed to ggplot2::scale_color_manual(values). Default NULL uses internal selected palette when <= 26 categories are presented, otherwise ggplot hues. legendNRow,legendNCol Integer, when too many categories in one variable, arranges number of rows or columns. Default NULL, automatically split to ceiling(levels(variable)/15) columns. colorDirection Choose 1 or -1. Applied when colorPalette is from Viridis options. Default -1 use darker color for higher value, while 1 reverses this direction. colorLow,colorMid,colorHigh,colorMidPoint All four of these must be specified to customize palette with naColor The color code for NA values. Default "#DEDEDE". scale_colour_gradient2. Default NULL. plotly Whether to use plotly to enable web based interactive browsing for the plot. Requires installation of package "plotly". Default FALSE.
useCluster	Name of variable in cellMeta(object). Default NULL uses default cluster.
combinePlot	Logical, whether to utilize plot_grid to combine multiple plots into one. Default TRUE returns combined ggplot. FALSE returns a list of ggplot.
features, factors	Name of genes or index of factors that need to be visualized.
log	Logical. Whether to log transform the normalized expression of genes. Default TRUE.
scaleFactor	Number to be multiplied with the normalized expression of genes before log transformation. Default 1e4. NULL for not scaling.
zeroAsNA	Logical, whether to swap all zero values to NA so naColor will be used to represent non-expressing features. Default TRUE.
colorPalette	Name of viridis palette. See viridis for options. Default "C" ("plasma") for gene expression and "D" ("viridis") for factor loading.
trimHigh	Number for highest cut-off to limit the outliers. Factor loading above this value will all be trimmed to this value. Default 0.03.

Details

Available option for slot include: "cellMeta", "rawData", "normData", "scaleData", "H.norm" and "H". When "rawData", "normData" or "scaleData", colorBy has to be a character vector of feature names. When "H.norm" or "H", colorBy can be any valid index to select one factor of interests. Note that character index follows "Factor_[k]" format, with replacing [k] with an integer.

When "cellMeta", colorBy has to be an available column name in the table. Note that, for colorBy as well as x, y, shapeBy and splitBy, since a matrix object is feasible in cellMeta table, using a column (e.g. named as "column1" in a certain matrix (e.g. named as "matrixVar") should follow the syntax of "matrixVar.column1". When the matrix does not have a "colname" attribute, the subscription goes with "matrixVar.V1", "matrixVar.V2" and etc. Use "UMAP.1", "UMAP.2", "TSNE.1" or "TSNE.2" for the 2D embeddings generated with rliger package. These are based on the nature of as.data.frame method on a DataFrame object.

Value

A ggplot object when a single plot is intended. A list of ggplot objects, when multiple colorBy variables and/or splitBy are set. When plotly = TRUE, all ggplot objects become plotly (htmlwidget) objects.

ggplot object when only one feature (e.g. cluster variable, gene, factor) is set. List object when multiple of those are specified.

Examples

plotDimRed(pbmcPlot, colorBy = "dataset", slot = "cellMeta",
           labelText = FALSE)
plotDimRed(pbmcPlot, colorBy = "S100A8", slot = "normData",
           dotOrder = "ascending", dotSize = 2)
plotDimRed(pbmcPlot, colorBy = 2, slot = "H.norm",
           dotOrder = "ascending", dotSize = 2, colorPalette = "viridis")
plotClusterDimRed(pbmcPlot)
plotDatasetDimRed(pbmcPlot)
plotByDatasetAndCluster(pbmcPlot)
plotGeneDimRed(pbmcPlot, varFeatures(pbmcPlot)[1])
plotFactorDimRed(pbmcPlot, 2)

rliger documentation built on Aug. 27, 2025, 1:08 a.m.