CellStatPlot.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cellstatplot.R
\name{CellStatPlot}
\alias{CellStatPlot}
\title{Cell statistics plot}
\usage{
CellStatPlot(
  object,
  ident = NULL,
  group_by = NULL,
  group_by_sep = "_",
  split_by = NULL,
  split_by_sep = "_",
  facet_by = NULL,
  rows = NULL,
  columns_split_by = NULL,
  frac = c("none", "group", "ident", "cluster", "all"),
  rows_name = NULL,
  name = NULL,
  plot_type = c("bar", "circos", "pie", "pies", "ring", "donut", "trend", "area",
    "sankey", "alluvial", "heatmap", "radar", "spider", "violin", "box"),
  swap = FALSE,
  ylab = NULL,
  ...
)
}
\arguments{
\item{object}{A Seurat object}

\item{ident}{The column with the cell identities. i.e. clusters. Default: NULL
If NULL, the active identity of the Seurat object and the name "Identity" will be used.
For 'pies', this will be used as the \code{pie_group_by}.
For 'heatmap' plot, this will be used as the rows of the heatmap.}

\item{group_by}{The column name in the meta data to group the cells. Default: NULL
This should work as the columns of the plot_type: heatmap.
For violin/box plot, at most 2 \code{group_by} columns are allowed and they will not be concatenated.
The first one is used to break down the values in groups, and the second one works as the \code{group_by}
argument in \link[plotthis:boxviolinplot]{plotthis::ViolinPlot}/\link[plotthis:boxviolinplot]{plotthis::BoxPlot}.}

\item{group_by_sep}{The separator to use when combining multiple columns in \code{group_by}. Default: "_"
For 'sankey'/'heatmap' plot, multiple columns will not be combined, and each of them will be used as a node.}

\item{split_by}{The column name in the meta data to split the cells. Default: NULL
Each split will be plotted in a separate plot.}

\item{split_by_sep}{The separator to use when combining multiple columns in \code{split_by}. Default: "_"}

\item{facet_by}{The column name in the meta data to facet the plots. Default: NULL
Not available for 'circos', 'sankey', and 'heatmap' plots.}

\item{rows}{The column names in the data used as the rows of the 'pies' (heatmap with cell_type = 'pie').
Default: NULL. Only available for 'pies' plot.
The values don't matter, and they only indicate the cells overlapping with the columns and distributed in different \code{ident} values.}

\item{columns_split_by}{The column name in the meta data to split the columns of the 'pies'/'heatmap' plot. Default: NULL}

\item{frac}{The way of calculating the fraction. Default is "none".
Possible values are "group", "ident", "cluster", "all", "none".
Note that the fractions are calculated in each split and facet group if \code{split_by} and \code{facet_by} are specified.
\itemize{
\item group: calculate the fraction in each group.
The total fraction of the cells of idents in each group will be 1.
When \code{group-by} is not specified, it will be the same as \code{all}.
\item ident: calculate the fraction in each ident.
The total fraction of the cells of groups in each ident will be 1.
Only works when \code{group-by} is specified.
\item cluster: alias of \code{ident}.
\item all: calculate the fraction against all cells.
\item none: do not calculate the fraction, use the number of cells instead.
}}

\item{rows_name}{The name of the rows in the 'pies'/'heatmap' plot. Default is NULL.}

\item{name}{The name of the 'pies'/'heatmap' plot, shown as the name of the main legend. Default is NULL.}

\item{plot_type}{The type of plot to use. Default is "bar".
Possible values are "bar", "circos", "pie", "pies", "ring"/"donut", "trend", "area", "heatmap", "sankey"/"alluvial", "radar" and "spider".
'pie' vs 'pies': 'pie' plot will plot a single pie chart for each group, while 'pies' plot will plot multiple pie charts for each group and split.
'pies' basically is a heatmap with 'cell_type = "pie"'.}

\item{swap}{Whether to swap the cluster and group, that is,
using group as the x-axis and cluster to fill the plot.
For circos plot, when transposed, the arrows will be drawn from the idents (by \code{ident}) to the
the groups (by \code{group_by}).
Only works when \code{group_by} is specified.
For 'pies' plot, this will swap the group_by and ident.
For 'heatmap' plot, this will swap the group_by and columns_split_by.
Note that this is different from \code{flip}. \code{flip} is used to transpose the plot. But \code{swap} is used to swap the x and group_by during plotting.}

\item{ylab}{The y-axis label. Default is NULL.}

\item{...}{Other arguments passed to the specific plot function.
\itemize{
\item For \code{bar} plot, see \code{\link[plotthis:barplot]{plotthis::BarPlot()}}.
\item For \code{circos} plot, see \code{\link[plotthis:chordplot]{plotthis::CircosPlot()}}.
\item For \code{pie} chart, see \code{\link[plotthis:PieChart]{plotthis::PieChart()}}.
\item For \code{pies} plot, see \code{\link[plotthis:Heatmap]{plotthis::Heatmap()}}.
\item For \code{heatmap} plot, see \code{\link[plotthis:Heatmap]{plotthis::Heatmap()}}.
\item For \code{ring}/\code{donut} plot, see \code{\link[plotthis:RingPlot]{plotthis::RingPlot()}}.
\item For \code{trend} plot, see \code{\link[plotthis:TrendPlot]{plotthis::TrendPlot()}}.
\item For \code{area} plot, see \code{\link[plotthis:AreaPlot]{plotthis::AreaPlot()}}.
\item For \code{sankey}/\code{alluvial} plot, see \code{\link[plotthis:sankeyplot]{plotthis::SankeyPlot()}}.
\item For \code{radar} plot, see \code{\link[plotthis:radarplot]{plotthis::RadarPlot()}}.
\item For \code{spider} plot, see \code{\link[plotthis:radarplot]{plotthis::SpiderPlot()}}.
\item For \code{violin} plot, see \code{\link[plotthis:boxviolinplot]{plotthis::ViolinPlot()}}.
\item For \code{box} plot, see \code{\link[plotthis:boxviolinplot]{plotthis::BoxPlot()}}.
}}
}
\value{
A ggplot object or a list if \code{combine} is FALSE
}
\description{
Plot the statistics of the cells.
}
\examples{
\donttest{
# library(patchwork)
data(ifnb_sub)

# Bar plot
p1 <- CellStatPlot(ifnb_sub)
p2 <- CellStatPlot(ifnb_sub, group_by = "stim")
p3 <- CellStatPlot(ifnb_sub, group_by = "stim", palette = "Set2")
p4 <- CellStatPlot(ifnb_sub, group_by = "stim", position = "stack")
(p1 | p2) / (p3 | p4)

# Fraction of cells
p1 <- CellStatPlot(ifnb_sub, group_by = "stim", frac = "group",
                   ident = "seurat_annotations", x_text_angle = 60)
p2 <- CellStatPlot(ifnb_sub, group_by = "stim", frac = "group")
p3 <- CellStatPlot(ifnb_sub, group_by = "stim", frac = "ident",
                   position = "stack", alpha = .6)
p4 <- CellStatPlot(ifnb_sub, group_by = "stim", frac = "group",
                   swap = TRUE, position = "stack")
(p1 | p2) / (p3 | p4)

# Splitting/Facetting the plot
CellStatPlot(ifnb_sub, split_by = "stim")
CellStatPlot(ifnb_sub, facet_by = "stim")
CellStatPlot(ifnb_sub, facet_by = "stim", facet_nrow = 2)

# Circos plot
CellStatPlot(ifnb_sub, group_by = "stim", plot_type = "circos")
CellStatPlot(ifnb_sub, group_by = "stim", ident = "seurat_annotations",
             plot_type = "circos", labels_rot = TRUE)

# Pie plot
CellStatPlot(ifnb_sub, plot_type = "pie")
CellStatPlot(ifnb_sub, plot_type = "pie", split_by = "stim")

# Ring plot
CellStatPlot(ifnb_sub, plot_type = "ring", group_by = "stim",
             palette = "Spectral")

# Trend plot
CellStatPlot(ifnb_sub, plot_type = "trend", frac = "group",
             x_text_angle = 90, group_by = c("stim", "seurat_annotations"))

# Sankey plot
CellStatPlot(ifnb_sub, plot_type = "sankey", group_by = c("seurat_clusters", "stim"),
             links_alpha = .6)
CellStatPlot(ifnb_sub, plot_type = "sankey", links_alpha = .6,
             group_by = c("stim", "seurat_annotations", "orig.ident"))
CellStatPlot(ifnb_sub, plot_type = "sankey", links_alpha = .6,
             group_by = c("seurat_clusters", "stim", "seurat_annotations", "orig.ident"))

# Area plot
CellStatPlot(ifnb_sub, plot_type = "area", frac = "group", x_text_angle = 90,
             group_by = "seurat_annotations", split_by = "stim")

# Pies
ifnb_sub$r1 <- sample(c(1, NA), ncol(ifnb_sub), replace = TRUE)
ifnb_sub$r2 <- sample(c(1, NA), ncol(ifnb_sub), replace = TRUE)
ifnb_sub$r3 <- sample(c(1, NA), ncol(ifnb_sub), replace = TRUE)
CellStatPlot(ifnb_sub, plot_type = "pies", group_by = "stim",
   rows = c("r1", "r2", "r3"), show_row_names = TRUE,
   show_column_names = TRUE, column_names_side = "top", cluster_columns = FALSE,
   row_names_side = "left", pie_size = sqrt)

# Heatmap
CellStatPlot(ifnb_sub, plot_type = "heatmap", group_by = "stim", palette = "Blues")
CellStatPlot(ifnb_sub, plot_type = "heatmap", group_by = "stim",
   frac = "group", columns_split_by = "seurat_annotations", swap = TRUE)

# Radar plot/Spider plot
pr <- CellStatPlot(ifnb_sub, plot_type = "radar", group_by = "stim")
ps <- CellStatPlot(ifnb_sub, plot_type = "spider", group_by = "stim")
pr | ps

# Box/Violin plot
ifnb_sub$group <- sample(paste0("g", 1:10), nrow(ifnb_sub), replace = TRUE)
CellStatPlot(ifnb_sub, group_by = c("group", "stim"), frac = "group",
   plot_type = "violin", add_box = TRUE, ident = "seurat_annotations",
   x_text_angle = 60, comparisons = TRUE, aspect.ratio = 0.8)
}
}