Plot the percentage/absolute cell count of each cluster grouped by condition

ClusterDistrPlot(
  origin,
  cluster,
  condition = NULL,
  rev = F,
  normalize = rev,
  percent = T,
  plot = T,
  flip = T,
  reverse_order = T,
  stack = T,
  cols = "light",
  border = "white",
  violin = F,
  box = T,
  width = 0.9,
  pt = T,
  pt.style = "quasirandom",
  pt.size = 1,
  pt.alpha = 1,
  style = "outline",
  ncol = NULL,
  nrow = NULL,
  stat.method = "wilcox.test",
  p.adjust.method = "none",
  label = "p.signif",
  hide.ns = TRUE,
  ...
)

Arguments

origin

factor/vector of sample

cluster

factor/vector of cluster

condition

factor/vector of condition, should have the same number of unique values as origin. If provided, will create boxplots instead of bar plots, Default: NULL

rev

If TRUE, plot the proportion of sample in each cluster, Default: F

normalize

Normalize sample size to 100, Default: rev

percent

If FALSE, plot absolute cell number instead of percentage, Default: T

plot

Generate plot (TRUE) or matrix (FALSE), Default: T

flip

If plot bars horizontally (only used when condition is NULL), Default: T

reverse_order

If TRUE, will reverse the default stacking order (only used when condition is NULL), Default: T

stack

If TRUE, plot stacked bars (only used when condition is NULL), Default: T

cols

Colors to use for plotting. Default: "light"

border

Border color for bar plots (only used when condition is NULL), Default: "white"

violin

Indicates whether to generate a violin plot (only used when condition is not NULL), Default: FALSE

box

Indicates whether to depict a box plot (only used when condition is not NULL), Default: TRUE

width

Width parameter. When condition is NULL, controls bar width; when condition is provided, controls box plot width. Default: 0.9

pt

Indicates if points should be plotted (only used when condition is not NULL), Default: TRUE

pt.style

Position adjustment. Default choices: "quasirandom", "jitter" (only used when condition is not NULL)

pt.size

Point size setting (only used when condition is not NULL), Default: 1

pt.alpha

Adjusts the transparency of points (only used when condition is not NULL), Default: 1

style

Plot style: "fill" or "outline" (only used when condition is not NULL). Default: "outline"

ncol

Number of columns for multi-panel plots. Default: NULL

nrow

Number of rows for multi-panel plots. Default: NULL

stat.method

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

p.adjust.method

Method for adjusting p-values, Default: "none"

label

Specifies label type. Options include "p.signif", "p", "p.adj", "p.format", Default: "p.signif"

hide.ns

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

...

Additional arguments passed to VlnPlot2

Value

ggplot object or matrix

Details

This function extends ClusterDistrBar to allow grouping by condition, creating boxplots instead of bar plots. When condition is NULL, it behaves exactly like ClusterDistrBar, supporting all its parameters and returning a stacked bar plot. When condition is provided, it transforms the distribution data into a boxplot format using VlnPlot2, with each box representing the distribution of a cluster's proportion across samples within the same condition. This is particularly useful for comparing cluster distributions between experimental conditions.

All styling parameters from VlnPlot2 are supported, including violin/box display options, point styles, colors, and statistical testing. For detailed formatting options, refer to the VlnPlot2 documentation. Common customizations include:

- Changing point display: pt=TRUE/FALSE, pt.size, pt.alpha, pt.style

- Adjusting plot style: style="fill"/"outline", violin=TRUE/FALSE

- Adding statistical tests: stat.method="wilcox.test"/"t.test", p.adjust.method

- Controlling layout: ncol, nrow for multi-cluster displays

Examples

# Example with condition
ClusterDistrPlot(
  origin = pbmc$sample_id,
  cluster = pbmc$cluster,
  condition = pbmc$condition
)