Cell-Cell Communication Analysis (CellChat)

Cell-Cell Communication Analysis (CellChat v2)

When to Use This Skill

✅ Use when:

• You have an annotated scRNA-seq dataset (Seurat object with cell type labels)
• You want to identify ligand-receptor interactions between cell types
• You want to visualize communication networks (chord diagrams, bubble plots)
• You want to find dominant sender/receiver cell populations
• Chains from scrnaseq-seurat-core-analysis output (seurat_processed.rds)

❌ Don't use when:

• Data is not annotated (run scrnaseq-seurat-core-analysis first)
• You need spatial cell-cell communication (CellChat v2 supports this but requires spatial coordinates)
• You want gene regulatory networks (use grn-pyscenic instead)
• You have bulk RNA-seq data

Installation

⚠️ CellChat must be installed from GitHub (not CRAN). Use the jinworks repository (active), not sqjin (archived).

Inputs

Required:

• Seurat object (.rds) with:
  • Normalized expression data (@assays$RNA@data)
  • Cell type annotations in metadata (e.g., celltype column)
  • Minimum 3 cell types, ≥10 cells per type recommended

Accepted sources:

• seurat_processed.rds from scrnaseq-seurat-core-analysis (chains directly)
• Any annotated Seurat v5 object
• Example PBMC data (auto-loaded if no file provided)

Outputs

CSV tables:

• significant_interactions.csv — All significant L-R pairs with source, target, pathway, probability
• pathway_summary.csv — Pathway-level communication summary
• interaction_count_matrix.csv — Cell type × cell type interaction counts
• interaction_strength_matrix.csv — Cell type × cell type communication weights
• signaling_roles.csv — Centrality scores (sender, receiver, mediator, influencer per pathway)
• top_interactions.csv — Top 20 interactions ranked by probability

Visualizations (PNG + SVG):

• interaction_count_network — Circle plot of interaction counts
• interaction_strength_network — Circle plot of communication strength
• chord_aggregated — Chord diagram of the full communication network
• bubble_ligand_receptor — Bubble plot of L-R pairs by cell type pairs
• signaling_outgoing_heatmap — Outgoing signaling patterns by cell type
• signaling_incoming_heatmap — Incoming signaling patterns by cell type
• signaling_role_scatter — Dominant senders vs receivers scatter

Analysis objects (RDS):

• cellchat_object.rds — Complete CellChat object for downstream use
  • Load with: cellchat <- readRDS('cellchat_object.rds')
  • Required for: multi-condition comparison, pathway-specific deep dives

Reports:

• analysis_report.md — Markdown report (always generated)
• analysis_report.pdf — PDF report (requires rmarkdown + LaTeX)

Clarification Questions

🚨 ALWAYS ask Question 1 FIRST. Do not proceed before the user answers.

1. Input Files (ASK THIS FIRST):

• Do you have an annotated Seurat object (.rds) from scRNA-seq analysis?
  • If yes: provide the path to the .rds file
  • Expected: Seurat v5 object with cell type labels in metadata
• Or use example data? — PBMC 3k dataset (human immune cells, 2,638 cells, 8 cell types)
  • Uses source("scripts/load_data.R"); seurat_obj <- load_example_pbmc()

🚨 IF EXAMPLE DATA SELECTED: Parameters are pre-defined. Skip to Question 4 (or proceed directly to Step 1). Do NOT ask questions 2-3.

2. Species (own data only):

• a) Human (CellChatDB.human) — default
• b) Mouse (CellChatDB.mouse)

3. Cell Type Column (own data only):

• Which metadata column contains cell type annotations?
  • Common: celltype, singler_labels, cell_type, predicted.celltype.l2
  • Check with: colnames(seurat_obj@meta.data)

4. Analysis Scope (structured — works for demo and own data):

• a) All signaling types (Secreted + ECM-Receptor + Cell-Cell Contact) — ✅ recommended
• b) Secreted signaling only
• c) Cell-Cell Contact only

Standard Workflow

Note: Run from the OmicsClaw root directory and add the workflow scripts to sys.path:

import sys; import os; sys.path.insert(0, os.path.abspath('knowledge_base/scripts/cell-cell-communication'))

🚨 MANDATORY: USE SCRIPTS EXACTLY AS SHOWN — DO NOT WRITE INLINE CODE 🚨

Step 1 — Load data:

source("scripts/load_data.R")
seurat_obj <- load_cellchat_data()  # example PBMC data
# OR: seurat_obj <- load_cellchat_data("path/to/seurat_processed.rds")

Step 2 — Run CellChat analysis:

source("scripts/run_cellchat.R")
cellchat <- run_cellchat_analysis(seurat_obj, species = "human", group.by = "celltype")

DO NOT write inline CellChat code. Just source the script and call the function.

Step 3 — Generate visualizations:

source("scripts/cellchat_plots.R")
generate_all_plots(cellchat, output_dir = "results")

🚨 DO NOT write inline plotting code. Just use the script. 🚨

Step 4 — Export results:

source("scripts/export_results.R")
export_all(cellchat, seurat_obj = seurat_obj, output_dir = "results")

DO NOT write custom export code. Use export_all().

✅ VERIFICATION — You should see:

• After Step 1: "✓ Data loaded successfully! [N] cells, [M] cell types"
• After Step 2: "✓ CellChat analysis completed! [N] significant interactions across [M] pathways"
• After Step 3: "✓ All plots generated successfully! [6] visualizations saved"
• After Step 4: "=== Export Complete ==="

❌ IF YOU DON'T SEE THESE: You wrote inline code. Stop and use source().

⚠️ CRITICAL — DO NOT:

• ❌ Write inline CellChat code → STOP: Use source("scripts/run_cellchat.R")
• ❌ Write inline plotting code → STOP: Use generate_all_plots()
• ❌ Write custom export code → STOP: Use export_all()
• ❌ Try to install system-level dependencies → CellChat handles its own deps

⚠️ IF SCRIPTS FAIL — Script Failure Hierarchy:

1. Fix and Retry (90%) — Install missing package, re-run script
2. Modify Script (5%) — Edit the script file itself, document changes
3. Use as Reference (4%) — Read script, adapt approach, cite source
4. Write from Scratch (1%) — Only if genuinely impossible, explain why

NEVER skip directly to writing inline code without trying the script first.

Common Issues

Suggested Next Steps

After cell-cell communication analysis, consider:

1. Multi-condition comparison — Compare communication between disease vs healthy, treated vs untreated
   • See references/cellchat-guide.md for mergeCellChat() workflow
2. Pathway deep dive — Examine specific pathways (e.g., TNF, MHC-II) with hierarchy plots
3. Gene regulatory networks — Use grn-pyscenic to find transcription factors driving the communication
4. Functional enrichment — Run pathway analysis on sender/receiver gene sets

Related Skills

References

• Jin S, et al. Inference and analysis of cell-cell communication using CellChat. Nature Communications. 2021;12:1088.
• Jin S, et al. CellChat for systematic analysis of cell-cell communication from single-cell and spatially resolved transcriptomics. Nature Protocols. 2024.
• CellChat v2 GitHub (active)
• CellChat tutorials
• Detailed patterns: references/cellchat-guide.md
• Visualization options: references/visualization-guide.md