CellChat Tutorial: From a Seurat Object to Communication Networks, Pathways and Group Comparisons

Check the version first

CellChat v1, v2 and v3: where copying old tutorials goes wrong

The CellChat repository moved from sqjin/CellChat to jinworks/CellChat. The current GitHub main is 2.2.0.9001 (last commit 2026-03-04), and the latest release tag is v2.1.2. What is labeled "v3" online is the separate SpatialCellChat package for spatial transcriptomics; single-cell data still use CellChat v2.

Record packageVersion("CellChat") and the installation date in the methods section. GitHub main also changes between releases: PR #438, merged on 2026-02-19, changed the parallel behavior, and rankNet was modified on 2026-03-04.

Step 1

Installation: dependencies, common failures in China and fixes

CellChat is installed only from GitHub and contains C++ code, so it needs a compiler. The dependencies that fail most often are NMF (CRAN, requires Biobase), ComplexHeatmap and BiocNeighbors (Bioconductor), and presto (GitHub). With the other dependencies installed from conda, compiling NMF, presto and CellChat took 2.5 minutes in total on this page, without errors. Nature Protocols gives a dual-core CPU and 16 GB of RAM as the minimum.

# Option A: dependencies from conda (tested on this page, macOS arm64, about 4 min + 2.5 min compiling)
micromamba create -y -n cellchat -c conda-forge -c bioconda \
  r-base=4.5 r-seurat r-remotes r-rcppeigen c-compiler cxx-compiler fortran-compiler make \
  r-future r-future.apply r-pbapply r-irlba r-ggalluvial r-svglite r-ggrepel r-circlize \
  bioconductor-complexheatmap bioconductor-biocneighbors bioconductor-biobase \
  r-rspectra r-reticulate r-sna r-fnn r-shape r-ggpubr r-ggnetwork r-plotly r-shiny r-bslib \
  r-collapse r-pkgmaker r-registry r-rngtools r-gridbase r-doparallel r-cowplot r-uwot
micromamba run -n cellchat Rscript -e '
options(repos = c(CRAN = "https://cloud.r-project.org"))
install.packages("NMF")                                        # conda-forge has no r-nmf
remotes::install_github("immunogenomics/presto", upgrade = "never")
remotes::install_github("jinworks/CellChat", upgrade = "never")
packageVersion("CellChat")'

# Option B: an existing R 4.4 or later
# install.packages(c("BiocManager", "remotes", "NMF"))
# BiocManager::install(c("ComplexHeatmap", "BiocNeighbors", "Biobase"))
# remotes::install_github(c("immunogenomics/presto", "jinworks/CellChat"), upgrade = "never")

Step 2

Input: extracting data from a Seurat v5 object and label requirements

CellChat needs two inputs: a log-normalized expression matrix (genes in rows, cells in columns) and a group label for each cell. The code below was checked on Seurat 5.5.1; the comments name the error each line prevents.

library(Seurat)
library(CellChat)

seu <- readRDS("pbmc3k_annot.rds")          # annotated Seurat v5 object
seu <- JoinLayers(seu)                       # join layers first, otherwise only the first layer is read
seu$celltype <- droplevels(factor(seu$celltype))
stopifnot(!anyNA(seu$celltype))              # labels must not contain NA

data.input <- LayerData(seu, assay = "RNA", layer = "data")   # log-normalized values, not counts
stopifnot(min(data.input) >= 0)              # scale.data or integrated cannot be used
meta <- data.frame(
  labels  = seu$celltype,
  samples = factor(seu$orig.ident),          # v2 expects a samples column
  row.names = colnames(seu)
)
# prefix numeric cluster IDs; CellChat rejects the label "0"
# meta$labels <- factor(paste0("C", seu$seurat_clusters))

cellchat <- createCellChat(object = data.input, meta = meta, group.by = "labels")
table(cellchat@idents)

Step 3

CellChatDB: human and mouse versions, what v2 added, which subset to use

CellChatDB sorts ligand-receptor pairs into four categories. The official tutorial uses only Secreted Signaling as an example. The choice of subset changes the number of results more than any algorithm parameter.

Step 4

Core workflow and key parameters

The core workflow below runs on PBMC 3k. The table after the code explains each parameter and how to choose its value; the next section shows the measured effects.

CellChatDB <- CellChatDB.human               # use CellChatDB.mouse for mouse
cellchat@DB <- subsetDB(CellChatDB)          # all protein ligand-receptor pairs, without Non-protein Signaling
# cellchat@DB <- subsetDB(CellChatDB, search = "Secreted Signaling", key = "annotation")

future::plan("sequential")                   # sequential is faster on small datasets
cellchat <- subsetData(cellchat)
cellchat <- identifyOverExpressedGenes(cellchat)          # uses presto for the Wilcoxon test by default
cellchat <- identifyOverExpressedInteractions(cellchat)

cellchat <- computeCommunProb(cellchat,
                              type = "truncatedMean", trim = 0.1,  # trim only takes effect with truncatedMean
                              population.size = FALSE)              # TRUE is an option for unsorted samples
cellchat <- filterCommunication(cellchat, min.cells = 10)
cellchat <- computeCommunProbPathway(cellchat)
cellchat <- aggregateNet(cellchat)

df.net  <- subsetCommunication(cellchat)                      # ligand-receptor level
df.netP <- subsetCommunication(cellchat, slot.name = "netP")  # pathway level
nrow(df.net); cellchat@netP$pathways
saveRDS(cellchat, "cellchat_pbmc3k.rds")

Parameter tests

How parameters change the number of interactions: PBMC 3k measurements

Tested on this page: CellChat 2.2.0.9001, 2,638 cells in 9 groups from the official Seurat PBMC 3k workflow (13 platelets, 32 DCs), nboot = 100. "Interactions" are the rows returned by subsetCommunication (source group–target group–ligand-receptor pair). Nature Protocols compared triMean, trim 0.1 and trim 0.05 on atopic dermatitis skin data (5,011 cells, 12 groups) with the same direction: smaller trim gives more pairs and pathways, mostly weak signals.

Step 5

Interpreting results: number versus strength, and what each plot answers

aggregateNet produces two matrices: net$count is the number of significant ligand-receptor pairs between two groups, and net$weight is the sum of their communication probabilities. Count reflects how many kinds of signals there are, weight reflects the total signal, and their rankings often differ.

groupSize <- as.numeric(table(cellchat@idents))
par(mfrow = c(1, 2), xpd = TRUE)
netVisual_circle(cellchat@net$count,  vertex.weight = groupSize, weight.scale = TRUE,
                 label.edge = FALSE, title.name = "Number of interactions")
netVisual_circle(cellchat@net$weight, vertex.weight = groupSize, weight.scale = TRUE,
                 label.edge = FALSE, title.name = "Interaction strength")

pathways.show <- "MIF"                       # check that it is in cellchat@netP$pathways first
netVisual_aggregate(cellchat, signaling = pathways.show, layout = "chord")
netVisual_heatmap(cellchat, signaling = pathways.show, color.heatmap = "Reds")
netVisual_bubble(cellchat, sources.use = c("CD14 Mono", "FCGR3A Mono"),
                 targets.use = c("CD8 T", "NK", "B"), remove.isolate = FALSE)

cellchat <- netAnalysis_computeCentrality(cellchat, slot.name = "netP")
netAnalysis_signalingRole_scatter(cellchat)
netAnalysis_signalingRole_heatmap(cellchat, pattern = "outgoing") +
  netAnalysis_signalingRole_heatmap(cellchat, pattern = "incoming")

library(NMF); library(ggalluvial)
selectK(cellchat, pattern = "outgoing", k.range = 2:6, nrun = 10)   # the default 2:10 with nrun = 30 is slow
cellchat <- identifyCommunicationPatterns(cellchat, pattern = "outgoing", k = 3)
netAnalysis_river(cellchat, pattern = "outgoing")

Step 6

Group comparison: prerequisites for mergeCellChat and interpreting differential communication

CellChat compares groups by running each group separately and then merging. The prerequisites are: both groups use the same annotation (same column, same names), the same database subset and the same parameters; the cell type sets must match, otherwise run liftCellChat first.

run_cellchat <- function(obj) {
  meta <- data.frame(labels = droplevels(obj$celltype),  # drop types absent from this group
                      samples = factor(obj$sample), row.names = colnames(obj))
  cc <- createCellChat(LayerData(obj, assay = "RNA", layer = "data"), meta = meta, group.by = "labels")
  cc@DB <- subsetDB(CellChatDB.human, search = "Secreted Signaling", key = "annotation")
  cc <- subsetData(cc)
  cc <- identifyOverExpressedGenes(cc)
  cc <- identifyOverExpressedInteractions(cc)
  cc <- computeCommunProb(cc, type = "truncatedMean", trim = 0.1)  # use identical parameters for both groups
  cc <- filterCommunication(cc, min.cells = 10)
  cc <- computeCommunProbPathway(cc)
  cc <- aggregateNet(cc)
  netAnalysis_computeCentrality(cc, slot.name = "netP")
}
# both groups use the same labels (same annotation column, same spelling)
seu$celltype <- factor(seu$celltype)
cc.ctrl <- run_cellchat(subset(seu, stim == "CTRL"))
cc.stim <- run_cellchat(subset(seu, stim == "STIM"))

# if one group lacks a cell type, lift both to the same set of labels
grp <- union(levels(cc.ctrl@idents), levels(cc.stim@idents))
if (!identical(levels(cc.ctrl@idents), levels(cc.stim@idents))) {
  cc.ctrl <- liftCellChat(cc.ctrl, group.new = grp)
  cc.stim <- liftCellChat(cc.stim, group.new = grp)
}
object.list <- list(CTRL = cc.ctrl, STIM = cc.stim)
cellchat <- mergeCellChat(object.list, add.names = names(object.list))

compareInteractions(cellchat, show.legend = FALSE, group = c(1, 2)) +
  compareInteractions(cellchat, show.legend = FALSE, group = c(1, 2), measure = "weight")
netVisual_diffInteraction(cellchat, weight.scale = TRUE, measure = "weight")  # red = stronger in STIM
rankNet(cellchat, mode = "comparison", measure = "weight", stacked = TRUE, do.stat = TRUE)
netVisual_bubble(cellchat, sources.use = "CD14 Mono", comparison = c(1, 2),
                 max.dataset = 2, title.name = "Increased in STIM", angle.x = 45, remove.isolate = TRUE)

Troubleshooting

Common errors and pitfalls

The error messages below were reproduced on this page or come from GitHub issues and the Nature Protocols troubleshooting table, in workflow order.

Parallel runs: on 2,638 cells, future::plan("multisession", workers = 4) made identifyOverExpressedGenes go from 0.1 to 25.1 seconds and computeCommunProb from 5.8 to 26.3 seconds on this page. Several users in GitHub #357 report the same (0.9 to 368 seconds on Ubuntu). PR #438 (merged 2026-02-19) parallelized the permutation loop, and its author reports about 46 hours down to 5.2 hours for 40,000 cells on 64 cores. Use plan("sequential") below about 10,000 cells; for large data, first confirm that main after 2026-02-19 is installed, then use multisession with options(future.globals.maxSize = 4e9). Sources disagree on run time: Nature Protocols reports about 15 minutes of inference on a skin atlas of about 300,000 cells, while several GitHub users report hours for tens of thousands of cells; the differences come from the number of groups, database subset, nboot, version and parallel settings. Another user reports that steps up to computeCommunProb took about 4 hours for 90,000 cells and 6 groups on one core with 500 GB of memory (GitHub #167).

Large data can also be downsampled first: subset(obj, downsample = 500) in Seurat or sketchData in CellChat, sampling large groups and keeping small ones. The list of significant interactions is usually stable after downsampling, while strengths change.

Tool choice

Choosing between CellChat, CellPhoneDB, NicheNet and LIANA+, and the limits of communication inference

Dimitrov et al. (Nature Communications 2022) compared 16 resources and 7 methods and concluded that both the method and the resource strongly change the predictions. Liu et al. (Genome Biology 2022) evaluated 16 methods against spatial transcriptomics; CellChat, CellPhoneDB, NicheNet and ICELLNET performed better overall, and the authors recommend cross-checking with at least two methods.

• CellChat results come from mRNA expression and a prior database. They show that expression permits communication; they do not prove an interaction at the protein level.
• Single-cell data lose spatial position. Two groups expressing a ligand and its receptor are not necessarily adjacent in the tissue; spatial data or in situ experiments fill this gap.
• Pairs outside the database never appear, and CellChatDB favors well-studied signals.
• Strength values depend on parameters and normalization and should be compared only under the same parameters. A paper should report the database subset, type, trim, population.size, min.cells and version.
• Cross-condition analysis in CellChat is mainly pairwise; changes across several conditions or time series have to be organized by the user (a limitation listed in Nature Protocols).
• Common follow-up validation includes RNAscope of ligands or receptors, immunofluorescence co-localization, and receptor blocking or neutralizing antibody experiments.

Tested on this page

Test conditions and summary of results

Tested on this page: macOS arm64 (Apple M2, 8 cores, 16 GB), R 4.5.3, Seurat 5.5.1, CellChat 2.2.0.9001, presto 1.1.0, NMF 0.28, ComplexHeatmap 2.26.1, future 1.76.0. Other jobs were running on the same machine, so times indicate orders of magnitude only.

• Errors reproduced on this page: label 0, NA labels, unused factor levels, split layers, identical factor levels with a missing type in one group, plotting after merging without lifting.
• Silent errors: counts input, scale.data passed as a matrix, and LayerData on split layers returning only the first layer all run without error.
• Spatial transcriptomics (datatype = "spatial", SpatialCellChat), smoothData, CellPhoneDB, NicheNet and LIANA+ were not run here; only function and parameter names were checked against the documentation.

Chinese community

Experience verified in the Chinese community

The following come from Chinese blog posts republished on the Tencent Cloud developer community. Only items with error messages or the author's own runs, and consistent with the official documentation or the tests on this page, are included.

Hand it to an agent

Hand this workflow to an agent

You can describe the analysis in one sentence and let the Scientify scientific agent complete it in a cloud computer.

Example instruction: "Run a CellChat v2 analysis on data/annotated.rds (Seurat v5; the celltype column holds annotations, the condition column holds control and treatment, the sample column holds 6 samples): run the two conditions separately, exclude Non-protein Signaling, use both triMean and truncatedMean 0.1 and compare the results, set min.samples = 2 in filterCommunication; after merging, output the count and strength comparison, increased and decreased pathways, and a bubble plot of up-regulated pairs sent by macrophages, and summarize them in tables."

The agent installs CellChat and its dependencies in the cloud computer and records versions; checks whether layers are split, whether labels contain NA or unused levels, and whether the cell types match between groups, running liftCellChat when needed; runs both parameter sets and lists interactions found under only one of them; and outputs circle plots, bubble plots, signaling role plots and differential tables. The agent reviews the results adversarially, for example checking whether the strength is dominated by a few pathways such as MIF and whether significant interactions come from a single sample. The workspace keeps scripts, parameters, logs and rds files for reproduction, and the task continues after you shut down your computer.

You still need to check yourself whether the annotation is reliable, whether the database subset matches the research question, whether candidate pairs are plausible given the literature and the tissue, and which conclusions need experimental validation.