Plot a Markov Score on a Dimensionality Reduction Embedding

Visualizes a Markov analysis score (from PredictAttractors, PredictPerturbationTime, PredictFates, or PredictCommitment) as a colored scatter plot on any 2D reduction stored in the Seurat object. Optionally marks source and/or sink cell populations with a centroid diamond and greys out unconverged cells so they do not contaminate the color scale.

Usage

PlotMarkovEmbedding(
  seurat_obj,
  feature,
  reduction = "umap",
  source_cells = NULL,
  sink_cells = NULL,
  source_label = "Source",
  sink_label = "Sink",
  centroid_size = 5,
  centroid_color = "black",
  label_centroids = TRUE,
  label_size = 3,
  unconverged_cells = NULL,
  unconverged_color = "grey70",
  color_scale = c("lightgrey", "#2166AC"),
  pt_size = 0.8,
  alpha = 0.8,
  legend_title = NULL,
  title = NULL,
  ...
)

Arguments

seurat_obj: A Seurat object containing the dimensionality reduction and the score in @meta.data.
feature: Character. Metadata column name to color cells by (e.g., "attractor_score", "perturbation_pseudotime", "commitment_score").
reduction: Character. Name of the reduction stored in seurat_obj@reductions. Default: "umap".
source_cells: Character vector or NULL. Cell barcodes belonging to the source population. Their mean embedding coordinates are computed and drawn as a single centroid diamond (shape 18). NULL = no source centroid.
sink_cells: Character vector or NULL. Cell barcodes belonging to the sink population. Their mean embedding coordinates are computed and drawn as a single centroid diamond (shape 18). NULL = no sink centroid.
source_label: Character. Text label shown next to the source centroid via ggrepel::geom_label_repel. Only used when label_centroids = TRUE and source_cells is not NULL. Default: "Source".
sink_label: Character. Text label shown next to the sink centroid via ggrepel::geom_label_repel. Only used when label_centroids = TRUE and sink_cells is not NULL. Default: "Sink".
centroid_size: Numeric. Size of the centroid diamond marker. Default: 5.
centroid_color: Character. Color of the centroid diamond marker and its label. Default: "black".
label_centroids: Logical. If TRUE, add a text label to each centroid using ggrepel::geom_label_repel. Default: TRUE.
label_size: Numeric. Font size for centroid labels. Default: 3.
unconverged_cells: Character vector or NULL. Cell barcodes that hit max_iter in PredictPerturbationTime. These cells are drawn in unconverged_color below all other layers and excluded from the color scale limits. NULL = no special handling.
unconverged_color: Character. Color for unconverged cells. Default: "grey70".
color_scale: Character vector. Two or more colors for the sequential color gradient passed to scale_color_gradientn. Default: c("lightgrey", "#2166AC").
pt_size: Numeric. Point size for the main cell layer. Default: 0.8.
alpha: Numeric. Transparency for the main cell layer. Default: 0.8.
legend_title: Character or NULL. Legend title. If NULL, defaults to feature.
title: Character or NULL. Plot title. If NULL, defaults to feature.
...: Additional arguments (currently unused; reserved for future use).

Value

A ggplot2 object.

Details

Layers are drawn bottom to top: unconverged cells (grey) → converged cells (colored gradient) → source centroid diamond → sink centroid diamond → centroid labels (ggrepel). A single centroid per group is computed from the mean of the source/sink cells' embedding coordinates, so the marker position represents the group center rather than cluttering the plot with one marker per cell.

The color scale limits are computed from converged cells only, so unconverged cells (which often carry a meaningless max_iter value) do not distort the range.

Plot a Markov Score on a Dimensionality Reduction Embedding

Usage

Arguments

Value

Details

See also