do_GeyserPlot {SCpubr}

Generate a Geyser plot.

Description

A Geyser plot is a custom plot in which we plot continuous values on the Y axis grouped by a categorical value in the X. This is plotted as a dot plot, jittered so that the dots span all the way to the other groups. On top of this, the mean and .66 and .95 of the data is plotted, depicting the overall distribution of the dots. The cells can, then, be colored by a continuous variable (same as Y axis or different) or a categorical one (same as X axis or different).

Usage

do_GeyserPlot(
  sample,
  features,
  assay = NULL,
  slot = "data",
  group.by = NULL,
  split.by = NULL,
  enforce_symmetry = FALSE,
  scale_type = "continuous",
  order = TRUE,
  plot_cell_borders = TRUE,
  jitter = 0.45,
  pt.size = 1,
  border.size = 2,
  border.color = "black",
  legend.position = "bottom",
  legend.width = 1,
  legend.length = 20,
  legend.framewidth = 0.5,
  legend.tickwidth = 0.5,
  legend.framecolor = "grey50",
  legend.tickcolor = "white",
  legend.type = "colorbar",
  font.size = 14,
  font.type = "sans",
  axis.text.x.angle = 45,
  viridis.palette = "G",
  viridis.direction = 1,
  colors.use = NULL,
  na.value = "grey75",
  legend.ncol = NULL,
  legend.nrow = NULL,
  legend.icon.size = 4,
  legend.byrow = FALSE,
  legend.title = NULL,
  plot.title = NULL,
  plot.subtitle = NULL,
  plot.caption = NULL,
  xlab = "Groups",
  ylab = feature,
  flip = FALSE,
  min.cutoff = rep(NA, length(features)),
  max.cutoff = rep(NA, length(features)),
  number.breaks = 5,
  diverging.palette = "RdBu",
  diverging.direction = -1,
  sequential.palette = "YlGnBu",
  sequential.direction = -1,
  use_viridis = TRUE,
  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.

features

character | Features to represent.

assay

character | Assay to use. Defaults to the current assay.

slot

character | Data slot to use. Only one of: counts, data, scale.data. Defaults to "data".

group.by

character | Metadata variable to group the output by. Has to be a character of factor column.

split.by

character | Secondary metadata variable to further group (split) the output by. Has to be a character of factor column.

enforce_symmetry

logical | Return a symmetrical plot axes-wise or continuous color scale-wise, when applicable.

scale_type

character | Type of color scale to use. One of:

• categorical: Use a categorical color scale based on the values of "group.by".

• continuous: Use a continuous color scale based on the values of "feature".

order

logical | Whether to order the groups by the median of the data (highest to lowest).

plot_cell_borders

logical | Whether to plot border around cells.

jitter

numeric | Amount of jitter in the plot along the X axis. The lower the value, the more compacted the dots are.

pt.size

numeric | Size of the dots.

border.size

numeric | Width of the border of the cells.

border.color

character | Color for the border of the heatmap body.

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.length, legend.width

numeric | Length and width of the legend. Will adjust automatically depending on legend side.

legend.framewidth, legend.tickwidth

numeric | Width of the lines of the box in the legend.

legend.framecolor

character | Color of the lines of the box in the legend.

legend.tickcolor

character | Color of the ticks of the box in the legend.

legend.type

character | Type of legend to display. One of:

• normal: Default legend displayed by ggplot2.

• colorbar: Redefined colorbar legend, using guide_colorbar.

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.

axis.text.x.angle

numeric | Degree to rotate the X labels. One of: 0, 45, 90.

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.

colors.use

character | Named vector of colors to use. Has to match the unique values of group.by when scale_type is set to categorical.

na.value

character | Color value for NA.

legend.ncol

numeric | Number of columns in the legend.

legend.nrow

numeric | Number of rows in the legend.

legend.icon.size

numeric | Size of the icons in legend.

legend.byrow

logical | Whether the legend is filled by row or not.

legend.title

character | Title for the legend.

plot.title, plot.subtitle, plot.caption

character | Title, subtitle or caption to use in the plot.

xlab, ylab

character | Titles for the X and Y axis.

flip

logical | Whether to invert the axis of the displayed plot.

min.cutoff, max.cutoff

numeric | Set the min/max ends of the color scale. Any cell/group with a value lower than min.cutoff will turn into min.cutoff and any cell with a value higher than max.cutoff will turn into max.cutoff. In FeaturePlots, provide as many values as features. Use NAs to skip a feature.

number.breaks

numeric | Controls the number of breaks in continuous color scales of ggplot2-based plots.

diverging.palette

character | Type of symmetrical color palette to use. Out of the diverging palettes defined in brewer.pal.

diverging.direction

numeric | Either 1 or -1. Direction of the divering palette. This basically flips the two ends.

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.

use_viridis

logical | Whether to use viridis color scales.

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

Special thanks to Christina Blume for coming up with the name of the plot.

Value

Either a plot of a list of plots, depending on the number of features provided.

Examples

  # Check Suggests.
  value <- SCpubr:::check_suggests(function_name = "do_GeyserPlot", 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"))

    # Geyser plot with categorical color scale.
    p <- SCpubr::do_GeyserPlot(sample = sample,
                              features = "nCount_RNA",
                              scale_type = "categorical")
    p

    # Geyser plot with continuous color scale.
    p <- SCpubr::do_GeyserPlot(sample = sample,
                              features = "nCount_RNA",
                              scale_type = "continuous")


    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()`.")
  }