This function creates a dimension reduction plot that can handle both discrete and continuous variables seamlessly. It incorporates additional customization options for visual representation and automatically recognizes input variable types to optimize visualization.

DimPlot2(
  seu,
  features = NULL,
  group.by = NULL,
  split.by = NULL,
  cells = NULL,
  slot = "data",
  assay = NULL,
  dims = c(1, 2),
  reduction = NULL,
  priority = c("expr", "none"),
  ncol = NULL,
  nrow = NULL,
  nrow.each = NULL,
  ncol.legend = NULL,
  cols = list(discrete = "auto", continuous = "A"),
  load.cols = TRUE,
  pt.size = NULL,
  shape.by = NULL,
  alpha.by = NULL,
  order = c(discrete = FALSE, continuous = TRUE),
  shuffle = c(discrete = TRUE, continuous = FALSE),
  label = FALSE,
  label.color = NULL,
  box = FALSE,
  index.title = NULL,
  repel = FALSE,
  label.size = 4,
  theme = NULL,
  cells.highlight = NULL,
  cols.highlight = "#DE2D26",
  sizes.highlight = 1,
  na.value = "grey80",
  raster = NULL,
  raster.dpi = NULL,
  combine = TRUE,
  align = "hv"
)

Arguments

seu

Seurat object containing single-cell data for visualization.

features

Variables to be visualized in the plot, accepting both discrete and continuous variables. Default: NULL.

group.by

Alias for `features`. Default: NULL.

split.by

A metadata column name by which to split the plot, creating separate plots for each unique value. This can be useful for visualizing differences across conditions or experiments. Default: NULL.

cells

A vector specifying a subset of cells to include in the plot. Default: all cells are included.

slot

Which data slot to use for pulling expression data. Accepts 'data', 'scale.data', or 'counts'. Default: 'data'.

assay

Specify the assay from which to retrieve data. Default: NULL, which will use the default assay.

dims

A two-length numeric vector specifying which dimensions to use for the x and y axes, typically from a PCA, tSNE, or UMAP reduction. Default: c(1, 2).

reduction

Which dimensionality reduction to use. If not specified, will search in order of 'umap', 'tsne', then 'pca'. Default: NULL.

priority

Specifies which to prioritize when metadata column names conflict with gene names: 'expr' for expression, 'none' for metadata. Default: c("expr", "none").

ncol

Number of columns to display when combining multiple plots into a single patchworked ggplot object. Default: NULL.

nrow

Number of rows to display when combining multiple plots into a single patchworked ggplot object. Default: NULL.

nrow.each

Specifies the number of rows each split plot should have when using the split.by parameter. Default: NULL.

ncol.legend

Integer specifying the number of columns in the plot legend of discrete variables. Default: NULL.

cols

Flexible color settings for the plot, accepting a variety of inputs:

- A vector specifying a global color setting similar to Seurat's `DimPlot`/`FeaturePlot`.

- A list specifying colors for each variable type (discrete/continuous) or for each individual variable. For example, `list(discrete = "auto", continuous = "A")` applies automatic styling from `color_pro()` for discrete variables and `viridis` "A" style for continuous variables. More detailed setups can include `list("cluster" = "pro_blue", "CD14" = c("#EEEEEE", "black"))`.

For continuous variables:

- Predefined color schemes from the `viridis` package ("A", "B", "C", "D", "E").

- Named vector with keys "low", "mid", and "high" for three-point gradients. Example: `c(low = "blue", mid = "white", high = "red")`.

- Two-point gradient with keys "low" and "high". Example: `c(low = "blue", high = "red")`.

- Custom color gradient using a vector of colors.

For discrete variables:

- Seven color_pro styles: "default", "light", "pro_red", "pro_yellow", "pro_green", "pro_blue", "pro_purple".

- Five color_iwh styles: "iwh_default", "iwh_intense", "iwh_pastel", "iwh_all", "iwh_all_hard".

- Brewer color scales as specified by `brewer.pal.info`.

- Any manually specified colors.

Default: list(discrete = "auto", continuous = "A").

load.cols

When TRUE, automatically loads pre-stored color information for variables from `seu@misc[["var_colors"]]`. Default: TRUE.#' @param pt.size Point size for plotting, adjusts the size of each cell in the plot. Default: NULL.

shape.by

Metadata column or expression data used to specify different shapes for cells in the plot, allowing for additional visual distinctions. Default: NULL.

alpha.by

Transparency of points in the plot, which can be helpful in densely plotted areas. Default: NULL.

order

Boolean determining whether to plot cells in order of expression. Can be useful if points representing higher expression levels are being buried. Default: c(discrete = FALSE, continuous = TRUE).

shuffle

Randomly shuffles the order of points to prevent burial under other points. Default: c(discrete = TRUE, continuous = FALSE).

label

Whether to label clusters or other features in the plot. Default: FALSE.

label.color

Customize the color of labels; defaults to the same as cluster colors unless specified, such as "black". Default: NULL.

box

Whether to draw a box around labels to enhance visibility. Default: FALSE.

index.title

Specify a prefix for cluster indices when labels are replaced by numerical indices to simplify the plot. Default: NULL.

repel

Whether to use a repelling algorithm to avoid overlapping text labels. Default: FALSE.

label.size

Size of the text labels used for clusters or features. Default: 4.

theme

Allows customization of ggplot themes, for example, to remove axes or adjust text. Default: NULL.

cells.highlight

A vector of cell names to highlight; simpler input than Seurat's approach, focusing on ease of use. Default: NULL.

cols.highlight

A color or vector of colors to use for highlighting specified cells; will repeat to match the number of groups in cells.highlight. Default: '#DE2D26'.

sizes.highlight

Size of highlighted points, providing emphasis where needed. Default: 1.

na.value

Color to use for NA points when using a custom color scale. Default: 'grey80'.

raster

Whether to convert the plot points to a raster format, which can help with performance on large datasets. Default: NULL.

raster.dpi

The resolution for rasterized plots, useful for maintaining detail in dense plots. Default: NULL.

combine

Whether to combine multiple plots into a single ggplot object using patchwork. Default: TRUE.

align

Specifies how plots should be aligned if combined, accepting 'h' for horizontal, 'v' for vertical, or 'hv' for both. Default: 'hv'.

Value

A ggplot object if `combine` is TRUE; otherwise, a list of ggplot objects, allowing for flexible plot arrangements or combined visualizations.

Details

`DimPlot2` extends the functionality of Seurat's visualization tools by combining the features of `DimPlot` and `FeaturePlot` into a single, more versatile function. It automatically recognizes whether the input features are discrete or continuous, adjusting the visualization accordingly. This makes `DimPlot2` ideal for exploring complex scRNA-seq data without the need to switch between different plotting functions based on variable types. The function also offers advanced customization options for colors, themes, and labeling, making it highly adaptable to various data visualization needs.

Examples

library(Seurat)
library(SeuratExtend)

# Create a basic dimensional reduction plot with default settings
DimPlot2(pbmc)

# Visualize different variables, including both discrete and continuous types
DimPlot2(pbmc, features = c("cluster", "orig.ident", "CD14", "CD3D"))

# Split the visualization by a specific variable for comparative analysis
DimPlot2(pbmc, features = c("cluster", "CD14"), split.by = "orig.ident", ncol = 1)

# Highlight specific cells, such as a particular cluster
b_cells <- colnames(pbmc)[pbmc$cluster == "B cell"]
DimPlot2(pbmc, cells.highlight = b_cells)

# Apply advanced customization for colors and themes
DimPlot2(
  pbmc,
  features = c("cluster", "orig.ident", "CD14", "CD3D"),
  cols = list(
    "cluster" = "pro_blue",
    "CD14" = "D",
    "CD3D" = c("#EEEEEE", "black")
  ),
  theme = NoAxes())

# Enhance the plot with labels and bounding boxes
DimPlot2(pbmc, label = TRUE, box = TRUE, label.color = "black", repel = TRUE, theme = NoLegend())

# Use indices instead of long cluster names to simplify labels in the plot
DimPlot2(pbmc, index.title = "C", box = TRUE, label.color = "black")