do_CellularStatesPlot: Cellular States plot.

In SCpubr: Generate Publication Ready Visualizations of Single Cell Transcriptomics Data

Cellular States plot.

Description

This plot aims to show the relationships between distinct enrichment scores. If 3 variables are provided, the relationship is between the Y axis and the dual X axis. If 4 variables are provided, each corner of the plot represents how enriched the cells are in that given list. How to interpret this? In a 3-variable plot, the Y axis just means one variable. The higher the cells are in the Y axis the more enriched they are in that given variable. The X axis is a dual parameter one. Cells falling into each extreme of the axis are highly enriched for either x1 or x2, while cells falling in between are not enriched for any of the two. In a 4-variable plot, each corner shows the enrichment for one of the 4 given features. Cells will tend to locate in either of the four corners, but there will be cases of cells locating mid-way between two given corners (enriched in both features) or in the middle of the plot (not enriched for any).

Usage

do_CellularStatesPlot(
  sample,
  input_gene_list,
  x1,
  y1,
  x2 = NULL,
  y2 = NULL,
  group.by = NULL,
  colors.use = NULL,
  legend.position = "bottom",
  legend.icon.size = 4,
  legend.ncol = NULL,
  legend.nrow = NULL,
  legend.byrow = FALSE,
  plot.title = NULL,
  plot.subtitle = NULL,
  plot.caption = NULL,
  font.size = 14,
  font.type = "sans",
  xlab = NULL,
  ylab = NULL,
  axis.ticks = TRUE,
  axis.text = TRUE,
  verbose = FALSE,
  enforce_symmetry = FALSE,
  plot_marginal_distributions = FALSE,
  marginal.type = "density",
  marginal.size = 5,
  marginal.group = TRUE,
  plot_cell_borders = TRUE,
  plot_enrichment_scores = FALSE,
  border.size = 2,
  border.color = "black",
  pt.size = 2,
  raster = FALSE,
  raster.dpi = 1024,
  plot_features = FALSE,
  features = NULL,
  use_viridis = TRUE,
  viridis.palette = "G",
  viridis.direction = 1,
  sequential.palette = "YlGnBu",
  sequential.direction = -1,
  nbin = 24,
  ctrl = 100,
  number.breaks = 5,
  plot.title.face = "bold",
  plot.subtitle.face = "plain",
  plot.caption.face = "italic",
  axis.title.face = "bold",
  axis.text.face = "plain",
  legend.title.face = "bold",
  legend.text.face = "plain"
)

Arguments

sample	Seurat | A Seurat object, generated by CreateSeuratObject.
input_gene_list	named_list | Named list of lists of genes to be used as input.
x1	character | A name of a list from input_gene_list. First feature in the X axis. Will go on the right side of the X axis if y2 is not provided and top-right quadrant if provided.
y1	character | A name of a list from input_gene_list. First feature on the Y axis. Will become the Y axis if y2 is not provided and bottom-right quadrant if provided.
x2	character | A name of a list from input_gene_list. Second feature on the X axis. Will go on the left side of the X axis if y2 is not provided and top-left quadrant if provided.
y2	character | A name of a list from input_gene_list. Second feature on the Y axis. Will become the bottom-left quadrant if provided.
group.by	character | Metadata variable to group the output by. Has to be a character of factor column.
colors.use	named_vector | Named vector of valid color representations (either name of HEX codes) with as many named colors as unique values of group.by. If group.by is not provided, defaults to the unique values of Idents. If not provided, a color scale will be set by default.
legend.position	character | Position of the legend in the plot. One of: top: Top of the figure. bottom: Bottom of the figure. left: Left of the figure. right: Right of the figure. none: No legend is displayed.
legend.icon.size	numeric | Size of the icons in legend.
legend.ncol	numeric | Number of columns in the legend.
legend.nrow	numeric | Number of rows in the legend.
legend.byrow	logical | Whether the legend is filled by row or not.
plot.title, plot.subtitle, plot.caption	character | Title, subtitle or caption to use in the plot.
font.size	numeric | Overall font size of the plot. All plot elements will have a size relationship with this font size.
font.type	character | Base font family for the plot. One of: mono: Mono spaced font. serif: Serif font family. sans: Default font family.
xlab, ylab	character | Titles for the X and Y axis.
axis.ticks	logical | Whether to show axis ticks.
axis.text	logical | Whether to show axis text.
verbose	logical | Whether to show extra comments, warnings,etc.
enforce_symmetry	logical | Whether to enforce the plot to follow a symmetry (3 variables, the X axis has 0 as center, 4 variables, all axis have the same range and the plot is squared).
plot_marginal_distributions	logical | Whether to plot marginal distributions on the figure or not.
marginal.type	character | One of: density: Compute density plots on the margins. histogram: Compute histograms on the margins. boxplot: Compute boxplot on the margins. violin: Compute violin plots on the margins. densigram: Compute densigram plots on the margins.
marginal.size	numeric | Size ratio between the main and marginal plots. A value of 5 means that the main plot is 5 times bigger than the marginal plots.
marginal.group	logical | Whether to group the marginal distribution by group.by or current identities.
plot_cell_borders	logical | Whether to plot border around cells.
plot_enrichment_scores	logical | Whether to report enrichment scores for the input lists as plots.
border.size	numeric | Width of the border of the cells.
border.color	character | Color for the border of the heatmap body.
pt.size	numeric | Size of the dots.
raster	logical | Whether to raster the resulting plot. This is recommendable if plotting a lot of cells.
raster.dpi	numeric | Pixel resolution for rasterized plots. Defaults to 1024. Only activates on Seurat versions higher or equal than 4.1.0.
plot_features	logical | Whether to also report any other feature onto the primary plot.
features	character | Additional features to plot.
use_viridis	logical | Whether to use viridis color scales.
viridis.palette	character | A capital letter from A to H or the scale name as in scale_fill_viridis.
viridis.direction	numeric | Either 1 or -1. Controls how the gradient of viridis scale is formed.
sequential.palette	character | Type of sequential color palette to use. Out of the sequential palettes defined in brewer.pal.
sequential.direction	numeric | Direction of the sequential color scale. Either 1 or -1.
nbin	numeric | Number of bins to use in AddModuleScore.
ctrl	numeric | Number of genes in the control set to use in AddModuleScore.
number.breaks	numeric | Controls the number of breaks in continuous color scales of ggplot2-based plots.
plot.title.face, plot.subtitle.face, plot.caption.face, axis.title.face, axis.text.face, legend.title.face, legend.text.face	character | Controls the style of the font for the corresponding theme element. One of: plain: For normal text. italic: For text in itallic. bold: For text in bold. bold.italic: For text both in itallic and bold.

Details

This plots are based on the following publications:

• Neftel, C. et al. An Integrative Model of Cellular States, Plasticity, and Genetics for Glioblastoma. Cell 178, 835-849.e21 (2019). \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1016/j.cell.2019.06.024")}

• Tirosh, I., Venteicher, A., Hebert, C. et al. Single-cell RNA-seq supports a developmental hierarchy in human oligodendroglioma. Nature 539, 309–313 (2016). \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1038/nature20123")}

Value

A ggplot2 object containing a butterfly plot.

Examples

  # Check Suggests.
  value <- SCpubr:::check_suggests(function_name = "do_CellularStatesPlot", passive = TRUE)

  if (isTRUE(value)){
    # Consult the full documentation in https://enblacar.github.io/SCpubr-book/

    # Define your Seurat object.
    sample <- readRDS(system.file("extdata/seurat_dataset_example.rds", package = "SCpubr"))

    # Define some gene sets to query. It has to be a named list.
    gene_set <- list("A" = rownames(sample)[1:10],
                     "B" = rownames(sample)[11:20],
                     "C" = rownames(sample)[21:30],
                     "D" = rownames(sample)[31:40])

    # Using two variables: A scatter plot X vs Y.
    p <- SCpubr::do_CellularStatesPlot(sample = sample,
                                       input_gene_list = gene_set,
                                       x1 = "A",
                                       y1 = "B",
                                       nbin = 1,
                                       ctrl = 10)
    p


    # Using three variables. Figure from: https://www.nature.com/articles/nature20123.
    p <- SCpubr::do_CellularStatesPlot(sample = sample,
                                       input_gene_list = gene_set,
                                       x1 = "A",
                                       y1 = "B",
                                       x2 = "C",
                                       nbin = 1,
                                       ctrl = 10)
    p


    # Using four variables. Figure from: https://pubmed.ncbi.nlm.nih.gov/31327527/
    p <- SCpubr::do_CellularStatesPlot(sample = sample,
                                       input_gene_list = gene_set,
                                       x1 = "A",
                                       y1 = "C",
                                       x2 = "B",
                                       y2 = "D",
                                       nbin = 1,
                                       ctrl = 10)
    p
  } else if (base::isFALSE(value)){
    message("This function can not be used without its suggested packages.")
    message("Check out which ones are needed using `SCpubr::state_dependencies()`.")
  }

SCpubr documentation built on Oct. 11, 2023, 5:15 p.m.