do_BoxPlot: Generate Box Plots.

Description

Generate Box Plots.

Usage

do_BoxPlot(
  sample,
  feature,
  group.by = NULL,
  split.by = NULL,
  assay = NULL,
  slot = "data",
  font.size = 14,
  font.type = "sans",
  axis.text.x.angle = 45,
  colors.use = NULL,
  colorblind = FALSE,
  na.value = "grey75",
  plot.title = NULL,
  plot.subtitle = NULL,
  plot.caption = NULL,
  xlab = NULL,
  ylab = NULL,
  legend.title = NULL,
  legend.title.position = "top",
  legend.position = "bottom",
  legend.ncol = NULL,
  legend.nrow = NULL,
  legend.byrow = FALSE,
  boxplot.line.color = "black",
  outlier.color = "black",
  outlier.alpha = 0.5,
  boxplot.linewidth = 0.5,
  boxplot.width = NULL,
  plot.grid = TRUE,
  grid.color = "grey75",
  grid.type = "dashed",
  flip = FALSE,
  order = FALSE,
  use_silhouette = FALSE,
  use_test = FALSE,
  comparisons = NULL,
  test = "wilcox.test",
  map_signif_level = c(`***` = 0.001, `**` = 0.01, `*` = 0.05),
  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.

Arguments

sample

Seurat | A Seurat object, generated by CreateSeuratObject.

feature

character | Feature to represent.

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.

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".

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.

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.

colorblind

logical | Whether to use colorblind-friendly colors for categorical variables. In place when colors.use is not used. Allows for a maximum of 85 different classes within a categorical variable.

na.value

character | Color value for NA.

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.

legend.title

character | Title for the legend.

legend.title.position

character | Position for the title of the legend. One of:

top: Top of the legend.
bottom: Bottom of the legend.
left: Left of the legend.
right: Right of the legend.

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.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.

boxplot.line.color

character | Color of the borders of the boxplots if use_silhouette is FALSE.

outlier.color

character | Color of the outlier dots.

outlier.alpha

numeric | Alpha applied to the outliers.

boxplot.linewidth

numeric | Width of the lines in the boxplots. Also controls the lines of the tests applied if use_test is set to true.

boxplot.width

numeric | Width of the boxplots.

plot.grid

logical | Whether to plot grid lines.

grid.color

character | Color of the grid in the plot. In heatmaps, color of the border of the cells.

grid.type

character | One of the possible linetype options:

blank.
solid.
dashed.
dotted.
dotdash.
longdash.
twodash.

flip

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

order

logical | Whether to order the boxplots by average values. Can not be used alongside split.by.

use_silhouette

logical | Whether to color the borders of the boxplots instead of the inside area.

use_test

logical | Whether to apply a statistical test to a given pair of elements. Can not be used alongside split.by.

comparisons

A list of length-2 vectors. The entries in the vector are either the names of 2 values on the x-axis or the 2 integers that correspond to the index of the columns of interest.

test

the name of the statistical test that is applied to the values of the 2 columns (e.g. t.test, wilcox.test etc.). If you implement a custom test make sure that it returns a list that has an entry called p.value.

map_signif_level

Boolean value, if the p-value are directly written as annotation or asterisks are used instead. Alternatively one can provide a named numeric vector to create custom mappings from p-values to annotation: For example: c("***"=0.001, "**"=0.01, "*"=0.05). Alternatively, one can provide a function that takes a numeric argument (the p-value) and returns a string.

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.

Examples

Run this code

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

    # Basic box plot.
    p <- SCpubr::do_BoxPlot(sample = sample,
                            feature = "nCount_RNA")
    p

    # Use silhouette style.
    p <- SCpubr::do_BoxPlot(sample = sample,
                            feature = "nCount_RNA",
                            use_silhouette = TRUE)
    p

    # Order by mean values.
    p <- SCpubr::do_BoxPlot(sample = sample,
                            feature = "nCount_RNA",
                            order = TRUE)
    p

    # Apply second grouping.
    sample$orig.ident <- ifelse(sample$seurat_clusters %in% c("0", "1", "2", "3"), "A", "B")
    p <- SCpubr::do_BoxPlot(sample = sample,
                            feature = "nCount_RNA",
                            split.by = "orig.ident")
    p

    # Apply statistical tests.
    p <- SCpubr::do_BoxPlot(sample = sample,
                            feature = "nCount_RNA",
                            group.by = "orig.ident",
                            use_test = TRUE,
                            comparisons = list(c("A", "B")))
    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