Skip to contents

Plot a Markov Score on a Dimensionality Reduction Embedding

PlotMarkovEmbedding.Rd

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,
  color_values = NULL,
  color_limits = NULL,
  color_breaks = NULL,
  color_oob = scales::censor,
  order_by_score = TRUE,
  seed = 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.

color_values

Numeric vector or NULL. Positions of the colors in color_scale, on a normalized 0–1 scale. Must have one position per color, in strictly increasing order. NULL spaces colors evenly.

color_limits

Numeric vector of length two or NULL. Increasing finite limits for the color scale. NULL uses the converged cells' score range.

color_breaks

Numeric vector or NULL. Optional legend tick positions in score units. NULL uses automatic breaks.

color_oob

Function. Handles scores outside the color limits. Default: scales::censor; use scales::squish to clamp them.

order_by_score

Logical. If TRUE (default), draw converged cells in ascending score order so high scores appear on top. If FALSE, draw them in random order. Use seed for reproducible random ordering.

seed

Integer-valued numeric scalar or NULL. Optional random seed used only when order_by_score = FALSE. When supplied, random ordering uses withr::with_seed(), preserving the caller's random state. NULL (default) uses the current random state; an external set.seed() can also be used.

...

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.

See also

PredictAttractors, PredictPerturbationTime, PredictFates, PredictCommitment, PlotMarkovScatter