Generates advanced violin plots distinct from Seurat's VlnPlot. This improved version offers a more compact design for efficient space utilization, the ability to overlay a boxplot, and convenient inclusion of statistical annotations. The function accommodates input in the form of either a Seurat object or a data frame.

VlnPlot2(object, ...)

# S3 method for Seurat
VlnPlot2(
  seu,
  features,
  group.by = NULL,
  split.by = NULL,
  cells = NULL,
  slot = "data",
  assay = NULL,
  priority = c("expr", "none"),
  cols = "auto",
  load.cols = TRUE,
  ncol = NULL,
  lab_fill = "group",
  scales = "free_y",
  violin = T,
  box = T,
  width = 0.9,
  pt = T,
  hide.outlier = F,
  pt.style = c("jitter", "quasirandom"),
  pt.size = 0.2,
  pt.alpha = 1,
  strip.position = "top",
  stat.method = c("none", "wilcox.test", "t.test"),
  p.adjust.method = "holm",
  label = c("p.signif", "p", "p.adj", "p.format"),
  comparisons = NULL,
  hide.ns = TRUE,
  step.increase = 0.12,
  tip.length = 0.03,
  ...
)

# S3 method for default
VlnPlot2(
  matr,
  f,
  f2 = NULL,
  features = NULL,
  t = F,
  cols = "pro_default",
  ncol = NULL,
  lab_fill = "group",
  scales = "free_y",
  violin = T,
  box = T,
  width = 0.9,
  pt = T,
  hide.outlier = F,
  pt.style = c("jitter", "quasirandom"),
  pt.size = 0.2,
  pt.alpha = 1,
  strip.position = "top",
  stat.method = c("none", "wilcox.test", "t.test"),
  p.adjust.method = "holm",
  label = c("p.signif", "p", "p.adj", "p.format"),
  comparisons = NULL,
  hide.ns = TRUE,
  step.increase = 0.12,
  tip.length = 0.03,
  ...
)

Arguments

object

An object, either a Seurat object or matrix.

...

Further arguments passed to the ggpubr::stat_pvalue_manual().

seu

A Seurat object. Only applicable for the Seurat method.

features

Features to depict, such as gene expression, metrics, PC scores, or any data obtainable via `FetchData()`. Default: NULL (all features in matrix).

group.by

A variable from `meta.data` for grouping or a character vector of equal length as the number of cells. Only applicable for the Seurat method.

split.by

A variable from `meta.data` to bifurcate the violin plots. Only applicable for the Seurat method.

cells

Cell identifiers for use. Defaults to all cells. Only applicable for the Seurat method.

slot

Slot to retrieve feature data from. Only applicable for the Seurat method.

assay

Name of the assay to employ. Defaults to the active assay. Only applicable for the Seurat method.

priority

If set to "expr", extracts data from the expression matrix over `meta.data`. Only applicable for the Seurat method.

cols

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

- 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.

load.cols

When TRUE, automatically loads pre-stored color information for variables from `seu@misc[["var_colors"]]`.

ncol

Specifies the number of columns for display if multiple plots are shown. Default: NULL.

lab_fill

Label for the figure legend. Default: 'group'.

scales

Scales parameter passed to ggplot2::facet_wrap(). Default: 'free_y'.

violin

Indicates whether to generate a violin plot. Default: TRUE.

box

Indicates whether to depict a box plot. Default: TRUE.

width

Width of the box plot. Default: 0.9.

pt

Indicates if points should be plotted. Default: TRUE.

hide.outlier

Conceals outlier points from the box plot. Default: FALSE.

pt.style

Position adjustment. Default choices: "jitter", "quasirandom".

pt.size

Point size setting. Default: 0.2.

pt.alpha

Adjusts the transparency of points. Default: 1.

strip.position

Positions the strip ("top" (default), "bottom", "left", or "right"). Only used when `f2 = NULL`.

stat.method

Determines if pairwise statistics are added to the plot. Either "wilcox.test" or "t.test". Default: "none".

p.adjust.method

Method for adjusting p-values, especially when conducting multiple pairwise tests or dealing with multiple grouping variables. Options include "holm", "hochberg", "hommel", "bonferroni", "BH", "BY", "fdr", and "none". Note: Adjustments are independently conducted for each variable in formulas containing multiple variables. Default: 'holm'.

label

Specifies label type. Options include "p.signif" (showing significance levels), "p.format" (formatted p value), or "p", "p.adj". Default: "p.signif".

comparisons

List of length-2 vectors, each containing either names of two x-axis values or two integers pointing to groups of interest for comparison. Default: all groups.

hide.ns

If TRUE, the 'ns' symbol is concealed when displaying significance levels. Default: TRUE.

step.increase

Numeric vector denoting the increase in fraction of total height for each additional comparison, minimizing overlap. Default: 0.12.

tip.length

Numeric vector indicating the fraction of total height the bar descends to specify the exact column. For a line display instead of a bracket, set to 0. Default: 0.03.

matr

A matrix or data frame with rows as features and columns as cells.

f

A factor or vector indicating the identity of each cell. Should match the column length of `matr`.

f2

A factor or vector akin to `f` for splitting the violin plots. Default: NULL.

t

If the matrix has features in columns and cells in rows, transpose the matrix first. Default: FALSE.

Value

ggplot object

A ggplot object.

Details

This function provides a range of customization options to generate violin plots, with or without additional graphical elements such as boxplots and points. You can specify features to plot, control the appearance of violin plots, boxplots, and points, adjust point position, group data, split violin plots, selectively use cells, control the column layout of multiple plots, and add statistical annotations. For a detailed overview, refer to the provided examples.

Examples

library(Seurat)
library(SeuratExtend)

# Using Seurat object as input:

# Basic violin plot with box plot and points:
genes <- c("CD3D","CD14","CD79A")
VlnPlot2(pbmc, features = genes, ncol = 1)

# Without violin plot, only box plot, and use quasirandom style for point position adjustment:
VlnPlot2(pbmc, features = genes, violin = F, pt.style = "quasirandom", ncol = 1)

# Hide points but display outlier points of the box plot:
VlnPlot2(pbmc, features = genes, pt = FALSE, ncol = 1)

# When hiding points, outliers are shown by default (recommended). However, outliers can be hidden for a cleaner appearance:
VlnPlot2(pbmc, features = genes, pt = FALSE, hide.outlier = T, ncol = 1)

# Group by cluster and split each cluster by samples:
VlnPlot2(pbmc, features = genes, group.by = "cluster", split.by = "orig.ident")

# Display only cells from certain subtypes (e.g. B cell, CD14+ Mono, and CD8 T cell), and arrange plots in 3 columns:
cells <- colnames(pbmc)[pbmc$cluster %in% c("B cell", "Mono CD14", "CD8 T cell")]
VlnPlot2(pbmc, features = genes, group.by = "cluster", cells = cells)

# Add statistical annotations using the Wilcoxon test for pairwise comparisons and hide non-significant results:
VlnPlot2(pbmc, features = genes, group.by = "cluster", cell = cells,
         stat.method = "wilcox.test", hide.ns = TRUE)

# Display statistics comparing only the specified clusters using a t-test:
VlnPlot2(pbmc, features = genes, group.by = "cluster", cell = cells,
         stat.method = "t.test", comparisons = list(c(1,2), c(1,3)), hide.ns = FALSE)

# Using a matrix as input:
# For instance, after performing Geneset Enrichment Analysis (GSEA) using the Hallmark 50 geneset to obtain the AUCell matrix:
pbmc <- GeneSetAnalysis(pbmc, genesets = hall50$human)
matr <- pbmc@misc$AUCell$genesets

# Create violin plots for the first three pathways:
VlnPlot2(matr[1:3,], f = pbmc$cluster, ncol = 1)