The hardware and bandwidth for this mirror is donated by METANET, the Webhosting and Full Service-Cloud Provider.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]metanet.ch.

SingleCellComplexHeatMap

A R package for creating complex heatmaps for single cell RNA-seq data that simultaneously display gene expression levels (as color intensity) and expression percentages (as circle sizes).

Features

Installation

# Install from GitHub (when available)
# devtools::install_github("xuecheng328/SingleCellComplexHeatMap")

# For now, install locally
devtools::install_local("/path/to/SingleCellComplexHeatMap")

Function Parameters

Main Function: create_single_cell_complex_heatmap()

Required Parameters

Data Organization Parameters

Order Control Parameters

Color and Style Parameters

Font Parameters

Legend Parameters

Visual Appearance Parameters

Data Parsing Parameters

Color Palette Parameters

Display Control Parameters

Customization Parameters (NEW)

Helper Functions

prepare_expression_matrices()

prepare_expression_matrices(
  seurat_object,           # Required: Seurat object
  features,                # Required: Gene names
  group_by = "seurat_clusters",
  idents = NULL,
  split_pattern = "_",
  time_position = 1,
  celltype_start = 2
)

create_gene_annotations()

create_gene_annotations(
  exp_mat,                 # Required: Expression matrix
  percent_mat,             # Required: Percentage matrix
  gene_classification,     # Required: Gene groups
  color_palette = "Set1",  # ENHANCED: Now supports color vectors
  sort_within_groups = TRUE,
  annotation_title = "Gene Group"  # NEW: Custom title
)

create_cell_annotations()

create_cell_annotations(
  exp_mat,                 # Required: Expression matrix
  percent_mat,             # Required: Percentage matrix
  split_pattern = "_",
  time_position = 1,
  celltype_start = 2,
  time_points_order = NULL,
  cell_types_order = NULL,
  time_color_palette = "Accent",    # ENHANCED: Now supports color vectors
  celltype_color_palette = "Dark2", # ENHANCED: Now supports color vectors
  show_time_annotation = TRUE,
  show_celltype_annotation = TRUE,
  time_point_title = "Time Point",  # NEW: Custom title
  cell_type_title = "Cell Type"     # NEW: Custom title
)

Data Preparation

Required Data Format

Important: This package expects your group identifiers to follow the format "timepoint_celltype" when you want to display both time and cell type information.

library(dplyr)

# Method 1: Create combined group column (recommended for time course + cell type analysis)
seurat_obj@meta.data <- seurat_obj@meta.data %>%
  mutate(group = paste(timepoint, celltype, sep = "_"))

# Example result: "Mock_Epidermis", "24hpi_Guard_cell", etc.

# Method 2: Use existing metadata columns for simpler analysis
# If you only want cell type information:
# group_by = "celltype"
# If you only want cluster information:
# group_by = "seurat_clusters"

Usage Examples

Basic Usage with All Default Parameters

library(SingleCellComplexHeatMap)

# Minimal usage
heatmap <- create_single_cell_complex_heatmap(
  seurat_object = seurat_obj,
  features = gene_list
)

Complete Parameter Customization

# Full customization example
heatmap <- create_single_cell_complex_heatmap(
  seurat_object = seurat_obj,
  features = gene_list,
  gene_classification = gene_groups,
  group_by = "group",
  idents = c(9, 10, 13),
  time_points_order = c("Mock", "24hpi", "48hpi", "72hpi"),
  cell_types_order = c("Epidermis", "Guard_cell", "Mesophyll"),
  color_range = c(-2, 0, 3),
  color_palette = c("blue", "white", "red"),
  max_circle_size = 3,
  row_fontsize = 10,
  col_fontsize = 8,
  col_name_rotation = 45,
  row_title_fontsize = 12,
  col_title_fontsize = 12,
  show_heatmap_legend = TRUE,
  show_percentage_legend = TRUE,
  legend_side = "bottom",
  merge_legends = FALSE,
  percentage_legend_title = "% Expressing Cells",
  percentage_legend_labels = c("0", "20", "40", "60", "80", "100"),
  cell_border_color = "white",
  split_pattern = "_",
  gene_color_palette = "Dark2",
  time_color_palette = "Set3",
  celltype_color_palette = "Paired",
  show_gene_grouping = TRUE,
  show_time_annotation = TRUE,
  show_celltype_annotation = TRUE,
  split_by = "celltype",
  gene_group_title = "Gene Categories",
  time_point_title = "Treatment Time",
  cell_type_title = "Cell Types",
  show_cell_borders = TRUE,
  show_column_annotation = TRUE,
  gene_name_mapping = NULL
)

Different Use Cases

1. Full Analysis (Time + Cell Type + Gene Groups)

# Prepare data with combined group
seurat_obj@meta.data <- seurat_obj@meta.data %>%
  mutate(group = paste(sample, Cell_type, sep = "_"))

gene_groups <- list(
  "Senescence" = c("Gene1", "Gene2", "Gene3"),
  "Stress_Response" = c("Gene4", "Gene5", "Gene6")
)

heatmap <- create_single_cell_complex_heatmap(
  seurat_object = seurat_obj,
  features = c("Gene1", "Gene2", "Gene3", "Gene4", "Gene5", "Gene6"),
  gene_classification = gene_groups,
  group_by = "group",
  time_points_order = c("Mock", "24hpi", "48hpi", "72hpi"),
  cell_types_order = c("Cell_cycle", "Companion_cell", "Epidermis")
)

2. Cell Type Only Analysis

heatmap <- create_single_cell_complex_heatmap(
  seurat_object = seurat_obj,
  features = your_genes,
  group_by = "celltype",  # Use existing celltype column
  show_time_annotation = FALSE,
  split_by = "none"
)

3. Simple Expression Analysis (No Grouping)

heatmap <- create_single_cell_complex_heatmap(
  seurat_object = seurat_obj,
  features = your_genes,
  gene_classification = NULL,  # No gene grouping
  group_by = "seurat_clusters",
  show_time_annotation = FALSE,
  show_celltype_annotation = FALSE,
  split_by = "none"
)

4. Custom Color Schemes

# Using different color palettes
heatmap <- create_single_cell_complex_heatmap(
  seurat_object = seurat_obj,
  features = your_genes,
  gene_classification = gene_groups,
  color_range = c(-1.5, 0, 1.5, 3),  # 4-point color range
  color_palette = c("darkblue", "blue", "white", "red", "darkred"),
  gene_color_palette = "Spectral",
  time_color_palette = "Set2",
  celltype_color_palette = "Pastel1"
)

5. Large Dataset Optimization

# For large datasets, reduce visual complexity
heatmap <- create_single_cell_complex_heatmap(
  seurat_object = seurat_obj,
  features = your_genes,
  max_circle_size = 1.5,  # Smaller circles
  row_fontsize = 6,       # Smaller font
  col_fontsize = 6,
  cell_border_color = NA, # No borders for cleaner look
  merge_legends = TRUE    # Compact legends
)

6. Publication-Ready Styling

# High-quality publication figure
heatmap <- create_single_cell_complex_heatmap(
  seurat_object = seurat_obj,
  features = your_genes,
  gene_classification = gene_groups,
  color_range = c(-2, 0, 2),
  color_palette = c("#2166AC", "#F7F7F7", "#B2182B"),  # Custom colors
  max_circle_size = 2.5,
  row_fontsize = 10,
  col_fontsize = 10,
  row_title_fontsize = 12,
  col_title_fontsize = 12,
  percentage_legend_title = "Fraction of cells",
  percentage_legend_labels = c("0", "0.25", "0.50", "0.75", "1.0"),
  legend_side = "right",
  merge_legends = TRUE,
  gene_group_title = "Functional Categories",
  time_point_title = "Time Points",
  cell_type_title = "Cell Types",
  show_cell_borders = TRUE,
  cell_border_color = "white"
)

Parameters

This section details all parameters for the create_single_cell_complex_heatmap function.

Main Parameters

New Customization Parameters

Data Source Control

Clustering Control

Color Mapping Control

Label and Legend Control

Other Parameters

Available Color Palettes

RColorBrewer Palettes

Custom Color Examples

# Viridis colors
color_palette = viridis::viridis(3)

# Custom RGB colors
color_palette = c("#440154", "#21908C", "#FDE725")

# Named colors
color_palette = c("navy", "white", "firebrick")

Step-by-Step Workflow

# Step 1: Prepare matrices
matrices <- prepare_expression_matrices(
  seurat_object = seurat_obj,
  features = your_genes,
  group_by = "group",
  idents = c(9, 10, 13)  # Specific cell clusters
)

# Step 2: Create gene annotations (if needed)
if (!is.null(gene_groups)) {
  gene_ann <- create_gene_annotations(
    exp_mat = matrices$exp_mat,
    percent_mat = matrices$percent_mat,
    gene_classification = gene_groups
  )
}

# Step 3: Create cell annotations
cell_ann <- create_cell_annotations(
  exp_mat = gene_ann$exp_mat_ordered,
  percent_mat = gene_ann$percent_mat_ordered,
  time_points_order = c("Mock", "24hpi", "48hpi", "72hpi"),
  cell_types_order = c("Epidermis", "Guard_cell", "Mesophyll")
)

Column Naming Convention

For optimal functionality, ensure your column identifiers follow these patterns:

The package automatically parses: - Position 1: Time point - Position 2+: Cell type (can include underscores)

Requirements

License

MIT License - see LICENSE file for details.

Citation

If you use this package in your research, please cite:

SingleCellComplexHeatMap: Complex Heatmaps for Single Cell Expression Data
XueCheng (2024)

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.