plotDimRed: 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",
  ...
)

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.

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.

Examples

Run this code

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)

Run the code above in your browser using DataLab