Skip to contents

Dataset Overview Wheel

PlotAtlasWheel.Rd

Creates a circular "atlas wheel" that summarizes a large multi-cohort dataset. Each wedge represents one level of group.by (e.g. cancer type, tissue, condition) and is annotated with the names of contributing studies. Summary statistics (total cells, donors, groups, and optionally normal-tissue types) are placed in the center.

Works with both Seurat objects and plain data.frames.

When facet.by is supplied, one wheel is built per level, all assembled side-by-side with patchwork. The filename includes "by_{facet.by}". Outer label margins are auto-expanded based on the longest group-level name.

Usage

PlotAtlasWheel(
  meta,
  group.by,
  study_by = NULL,
  patient_by = NULL,
  facet.by = NULL,
  ncol_facet = NULL,
  exclude_groups = NULL,
  normal_col = NULL,
  normal_val = NULL,
  normal_count_by = NULL,
  title = "Dataset Overview",
  cell_label = "Cells",
  show_stats = TRUE,
  colors = NULL,
  show_circles = TRUE,
  circle_size = 18,
  wedge_alpha = 0.5,
  y_inner = -1,
  y_outer = 10,
  y_text = 7,
  y_label = 11,
  y_circle = 1.5,
  y_min = -15,
  y_center_title = -5.5,
  y_center_stats = -13,
  label_size = 4,
  study_text_size = 2.2,
  study_lineheight = 0.9,
  title_size = 7,
  stats_size = 5,
  title_color = "#1e4e5f",
  output_dir = NULL,
  object_name = "",
  pdf_width = 9,
  pdf_height = 9
)

Arguments

meta

A Seurat object or a plain data.frame/tibble of per-cell (or per-sample) metadata.

group.by

Character. Primary grouping column - one wedge per level (e.g. "CancerType").

study_by

Character or NULL. Column whose values are pasted inside each wedge as a multi-line study label (e.g. "Study"). When NULL, no inner text is drawn.

patient_by

Character or NULL. Column identifying individual donors / patients - used to count unique donors in the summary statistics.

facet.by

Character or NULL. Metadata column to facet by - one wheel per level (e.g. "Tissue"). Default NULL.

ncol_facet

Integer or NULL. Number of wheel columns when facet.by is used. Auto-computed (max 2) if NULL.

exclude_groups

Character vector or NULL. Levels of group.by to exclude from the wheel itself, but whose cells are still counted in the center statistics. Typical use: exclude_groups = "Healthy".

normal_col, normal_val

Character or NULL. Column and value used to identify normal (non-disease) samples (e.g. normal_col = "Health", normal_val = "Healthy").

normal_count_by

Character or NULL. Column to count distinct normal tissue types (e.g. "Organ").

title

Character. Main title text in the center of the wheel. Supports "\n" for line breaks.

cell_label

Character. Descriptor appended to the cell count (e.g. "Myeloid Cells"). Default "Cells".

show_stats

Logical. Show cell / donor / group counts in the center. Default TRUE.

colors

Named character vector mapping group.by levels to colors. Auto-assigned if NULL.

show_circles

Logical. Draw a white placeholder circle at the inner base of each wedge. Default TRUE.

circle_size

Numeric. size of placeholder circles. Default 18.

wedge_alpha

Numeric. Transparency of the wedge fill. Default 0.5.

y_inner

Numeric. Inner y edge of the wedge ring (top of the center hole). Default -1.

y_outer

Numeric. Outer y edge of the wedge ring. Default 10.

y_text

Numeric. y position of the study-name text inside each wedge. Default 7.

y_label

Numeric. y position of the outer group-name labels. Default 11.

y_circle

Numeric. y position of the inner placeholder circles. Default 1.5.

y_min

Numeric. Bottom of the y-axis range. Default -15.

y_center_title

Numeric. y position of the center title annotation. Default -5.5.

y_center_stats

Numeric. y position of the center statistics. Default -13.

label_size

Numeric. Font size of outer group-name labels. Default 4.

study_text_size

Numeric. Font size of study-name text inside wedges. Default 2.2.

study_lineheight

Numeric. Line height for multi-line study labels. Default 0.9.

title_size

Numeric. Font size of the center title. Default 7.

stats_size

Numeric. Font size of the center statistics text. Default 5.

title_color

Character. Color for the center title and circle borders. Default "#1e4e5f".

output_dir

Directory to save a PDF. NULL = no save.

object_name

Label prefix for the output filename.

pdf_width, pdf_height

PDF dimensions per wheel in inches. Default 9 x 9.

Value

A ggplot2 or patchwork object (invisibly).