do_DimPlot: Wrapper for DimPlot.

Description

Wrapper for DimPlot.

Usage

do_DimPlot(
  sample,
  reduction = NULL,
  group.by = NULL,
  split.by = NULL,
  colors.use = NULL,
  shuffle = TRUE,
  order = NULL,
  raster = FALSE,
  pt.size = 1,
  label = FALSE,
  label.color = "black",
  label.fill = "white",
  label.size = 4,
  label.box = TRUE,
  repel = FALSE,
  cells.highlight = NULL,
  idents.highlight = NULL,
  idents.keep = NULL,
  sizes.highlight = 1,
  ncol = NULL,
  plot.title = NULL,
  plot.subtitle = NULL,
  plot.caption = NULL,
  legend.title = NULL,
  legend.position = "bottom",
  legend.title.position = "top",
  legend.ncol = NULL,
  legend.nrow = NULL,
  legend.icon.size = 4,
  legend.byrow = FALSE,
  raster.dpi = 2048,
  dims = c(1, 2),
  font.size = 14,
  font.type = "sans",
  na.value = "grey75",
  plot_cell_borders = TRUE,
  border.size = 2,
  border.color = "black",
  border.density = 1,
  plot_marginal_distributions = FALSE,
  marginal.type = "density",
  marginal.size = 5,
  marginal.group = TRUE,
  plot.axes = FALSE,
  plot_density_contour = FALSE,
  contour.position = "bottom",
  contour.color = "grey90",
  contour.lineend = "butt",
  contour.linejoin = "round",
  contour_expand_axes = 0.25,
  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 DimPlot.

Arguments

sample

Seurat | A Seurat object, generated by CreateSeuratObject.

reduction

character | Reduction to use. Can be the canonical ones such as "umap", "pca", or any custom ones, such as "diffusion". If you are unsure about which reductions you have, use Seurat::Reductions(sample). Defaults to "umap" if present or to the last computed reduction if the argument is not provided.

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.

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.

shuffle

logical | Whether to shuffle the cells or not, so that they are not plotted cluster-wise. Recommended.

order

character | Vector of identities to be plotted. Either one with all identities or just some, which will be plotted last.

raster

logical | Whether to raster the resulting plot. This is recommendable if plotting a lot of cells.

pt.size

numeric | Size of the dots.

label

logical | Whether to plot the cluster labels in the UMAP. The cluster labels will have the same color as the cluster colors.

label.color

character | Color of the labels in the plot.

label.fill

character | Color to fill the labels. Has to be a single color, that will be used for all labels. If NULL, the colors of the clusters will be used instead.

label.size

numeric | Size of the labels in the plot.

label.box

logical | Whether to plot the plot labels as geom_text (FALSE) or geom_label (TRUE).

repel

logical | Whether to repel the text labels.

cells.highlight, idents.highlight

character | Vector of cells/identities to focus into. The identities have to much those in Seurat::Idents(sample) The rest of the cells will be grayed out. Both parameters can be used at the same time.

idents.keep

character | Vector of identities to keep. This will effectively set the rest of the cells that do not match the identities provided to NA, therefore coloring them according to na.value parameter.

sizes.highlight

numeric | Point size of highlighted cells using cells.highlight parameter.

ncol

numeric | Number of columns used in the arrangement of the output plot using "split.by" parameter.

plot.title, plot.subtitle, plot.caption

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

legend.title

character | Title for 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.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.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.

raster.dpi

numeric | Pixel resolution for rasterized plots. Defaults to 1024. Only activates on Seurat versions higher or equal than 4.1.0.

dims

numeric | Vector of 2 numerics indicating the dimensions to plot out of the selected reduction. Defaults to c(1, 2) if not specified.

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.

na.value

character | Color value for NA.

plot_cell_borders

logical | Whether to plot border around cells.

border.size

numeric | Width of the border of the cells.

border.color

character | Color for the border of the heatmap body.

border.density

numeric | Controls the number of cells used when plot_cell_borders = TRUE. Value between 0 and 1. It computes a 2D kernel density and based on this cells that have a density below the specified quantile will be used to generate the cluster contour. The lower this number, the less cells will be selected, thus reducing the overall size of the plot but also potentially preventing all the contours to be properly drawn.

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

logical | Whether to plot axes or not.

plot_density_contour

logical | Whether to plot density contours in the UMAP.

contour.position

character | Whether to plot density contours on top or at the bottom of the visualization layers, thus overlapping the clusters/cells or not.

contour.color

character | Color of the density lines.

contour.lineend

character | Line end style (round, butt, square).

contour.linejoin

character | Line join style (round, mitre, bevel).

contour_expand_axes

numeric | To make the contours fit the plot, the limits of the X and Y axis are expanding a given percentage from the min and max values for each axis. This controls such percentage.

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_DimPlot", 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 DimPlot.
    p <- SCpubr::do_DimPlot(sample = sample)


    # Restrict the amount of identities displayed.
    p <- SCpubr::do_DimPlot(sample = sample,
                            idents.keep = c("1", "3", "5"))

    # Group by another variable rather than `Seurat::Idents(sample)`
    p <- SCpubr::do_DimPlot(sample = sample,
                            group.by = "seurat_clusters")

    # Split the output in as many plots as unique identities.
    p <- SCpubr::do_DimPlot(sample = sample,
                            split.by = "seurat_clusters")

    # Highlight given identities
    p <- SCpubr::do_DimPlot(sample,
                            idents.highlight = c("1", "3"))

  } 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