do_CellularStatesPlot: 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"
)

Value

A ggplot2 object containing a butterfly plot.

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). 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). tools:::Rd_expr_doi("10.1038/nature20123")

Examples

Run this code

# \donttest{
  # 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()`.")
  }
# }

Run the code above in your browser using DataLab