Pathway Enrichment & Cell-Cell Interaction Tutorial
Biological pathway enrichment using Enrichr (GO & KEGG) and cell-cell interaction analysis using CellPhoneDB on PBMC 3k data — with a map of when to reach for GSEA / ORA, functional activity scoring, or LIANA instead.
What you'll learn
- Submit per-cluster marker genes to Enrichr and identify enriched GO Biological Process and KEGG pathway terms.
- Use the fan-out pattern: connect three different Pathway Visualization nodes (GO Barplot, KEGG Barplot, GO Dotplot) to a single Pathway Enrichment node without re-computation.
- Run CellPhoneDB to identify statistically significant ligand-receptor interactions between cell-type pairs and visualize them as a heatmap, dotplot, and chord diagram.
Prerequisites
- • Oreumics installed (install guide).
- • PBMC tutorial completed — this tutorial assumes you have a clustered AnnData with DEG Analysis results in uns["rank_genes_groups"].
- • Internet access — Pathway Enrichment queries the Enrichr API at maayanlab.cloud/Enrichr (listed as Enrichr Remote Analysis in the Resource Center, the one resource that is queried rather than installed), which means your gene symbols (never expression values or cells) leave the machine for that one node.
- • Before the CellPhoneDB step: install the CellPhoneDB database once from the Resource Center (v5 recommended). The app bundles the CellPhoneDB code but not its database, and it will not download one mid-run — the node stops with a “resource not ready” message until it is installed.
- • Sample data:
sampledata/scrna/pbmc3k_raw.h5ad— pre-bundled. The three templates on this page ship as Pathway Enrichment Analysis, GO & KEGG Pathway Visualization and Cell-Cell Interaction (CellPhoneDB).
Dataset
Sample file (pre-packaged)
sampledata/scrna/pbmc3k_raw.h5ad— 2,700 cells × 32,738 genes · integer counts · already included in OreumicsWhat it is
Peripheral blood mononuclear cells (PBMCs) from a healthy human donor — the same dataset used in the PBMC scRNA-seq tutorial, with human HGNC gene symbols (which is what both Enrichr and CellPhoneDB expect). You first cluster cells through the standard preprocessing pipeline, then run pathway enrichment on the marker genes per cluster, or a ligand-receptor permutation test between clusters.
Internet required for Pathway Enrichment; a Resource Center install for CellPhoneDB
The Pathway Enrichment node queries the Enrichr API (maayanlab.cloud/Enrichr) while it runs. CellPhoneDB (Template 3) runs offline, but only after its interaction database has been installed once from the Resource Center — pinned by version and checksum, reused by every later run.
Which pathway node do I need?
• Pathway Enrichment (this tutorial) — per-cluster over-representation of the DEG Analysis markers against Enrichr libraries (GO / KEGG …), via gseapy + the Enrichr API. One result per cluster, drawn by Pathway Visualization.
• GSEA / ORA — gseapy on one gene list: preranked GSEA over all genes or ORA over the significant ones. Built for bulk de_results, but it also accepts single-cell rank_genes_groups (pick the group with its cluster parameter). See the Bulk tutorial.
• PROGENy Activity / Hallmark Activity / CollecTRI TF Activity — a different question: infer pathway (14 signalling pathways), program (50 MSigDB Hallmarks) or transcription-factor activity from the expression matrix itself with decoupler, no DEG list involved. Sample-level pseudobulk (sample_key) is the recommended mode; priors are installed once from the Resource Center. Functional Activity reference.
• CellPhoneDB vs. LIANA — both score ligand-receptor interactions between cell groups. CellPhoneDB runs the classic permutation test on its curated human database (mouse not supported — convert to HGNC symbols first). LIANA runs several methods (CellPhoneDB, NATMI, Connectome, logFC …) and aggregates them into one consensus ranking (magnitude_rank / specificity_rank), with a resource_name switch for mouse (mouseconsensus). See the LIANA alternative at the end of Template 3.
Pathway Enrichment Analysis
Run the standard scRNA-seq preprocessing pipeline through clustering and marker ranking, then submit marker genes to Enrichr to identify enriched GO and KEGG pathways per cluster. After clustering, the natural next question is: what biological processes are active in each cluster?
Pipeline (scroll →)
Load the PBMC 3k counts. No other settings are needed — the file already has gene symbols and cell barcodes.
file_pathsampledata/scrna/pbmc3k_raw.h5adWhat you'll see
2,700 cells × 32,738 genes loaded.
Filter out low-quality cells (empty droplets, dying cells) and lowly-detected genes. mode: filter removes cells permanently.
modefiltermin_genes200remove empty dropletsmax_pct_mito20remove dying cellsmito_prefixMT-filter_min_cellstruemin_cells3remove genes seen in <3 cellsWhat you'll see
~2,638 cells and ~13,714 genes remain after filtering.
Scale every cell so that the total count equals target_sum (CP10K), removing library-size differences. save_counts keeps the raw integer counts in layers["counts"].
target_sum10000save_countstrueApply log(x + 1) transformation. Compresses the dynamic range and makes the data more normally distributed — important for statistical tests downstream.
basenullnatural log (default)Select the 2,000 most variable genes across cells. These genes capture the most biological variability and are used for PCA. All downstream dimensionality reduction uses only these genes. This template has no Scale node, so DEG Analysis reads the log-normalized X directly (there is no adata.raw).
n_top_genes2000flavorseuratWhat you'll see
2,000 genes flagged as highly_variable: True in adata.var.
Compute the top 30 principal components using only the HVGs. Captures the major axes of transcriptional variation.
n_comps30use_highly_variabletrueBuild a k-nearest-neighbor graph in PCA space. This graph is shared by UMAP layout and Leiden clustering.
n_neighbors15n_pcs30default 15use_repX_pcaRun Leiden community detection on the kNN graph. Resolution 0.8 produces 8–10 clusters on PBMC 3k, suitable for resolving major immune cell types. Cluster labels are stored in obs.leiden.
methodleidenresolution0.8key_addedleidenWhat you'll see
8–10 clusters labeled 0–7 or 0–9. Expect distinct T cell, B cell, NK, and monocyte clusters.
Rank differentially expressed genes for each cluster vs. all other cells using the Wilcoxon rank-sum test (formerly "Find Markers"). Leave n_genes empty so all genes are ranked and stored in uns["rank_genes_groups"] — Pathway Enrichment applies its own p-value and log-fold-change cutoffs to pick the marker set per cluster.
groupbyleidenmethodwilcoxonreferencerestn_genesnullall genes rankedWhat you'll see
Ranked genes per cluster. Key markers: CD3D/CD3E (T cells), MS4A1/CD79A (B cells), NKG7/GNLY (NK), LYZ/CST3 (monocytes).
For each cluster, take the markers passing pval_threshold and lfc_threshold (at least min_de_genes of them), submit them to the Enrichr API through gseapy, and keep the n_top_terms best terms per gene-set library. Results are stored in uns["pathway_enrichment"]. gene_sets is a comma-separated list of Enrichr library names.
rank_keyrank_genes_groupsgene_setsGO_Biological_Process_2023,KEGG_2021_Humancomma-separated, no spacesorganismHumanpval_threshold0.05lfc_threshold1.0n_top_terms10min_de_genes3What you'll see
uns["pathway_enrichment"] contains enriched terms per cluster per gene set. T cell clusters show T cell activation and adaptive immune terms; monocyte clusters show innate immune and inflammatory terms.
Tip
Requires internet access to query maayanlab.cloud/Enrichr. If the request times out, try running with a single gene_set first. The gene list is the only thing that leaves the machine.
Render a horizontal bar chart of the top enriched GO terms per cluster, colored by adjusted p-value. This is the quickest way to survey the biological identity of each cluster.
plot_typebarplotgene_setGO_Biological_Process_2023n_top_terms5top 5 terms per clusterfigsize_w14figsize_h12What you'll see
Bar chart per cluster. T cell clusters: "T cell activation", "adaptive immune response". Monocyte clusters: "innate immune response", "myeloid cell differentiation". B cell clusters: "B cell receptor signaling". Bar length reflects -log10 adjusted p-value.
GO & KEGG Pathway Visualization
The fan-out pattern connects multiple visualization nodes to the same upstream result node. After Pathway Enrichment completes, connect three separate Pathway Visualization nodes — one per chart — all reading from the same enrichment data. No re-computation is required, and each figure gets its own Visualization Workspace.
Fan-out from Pathway Enrichment
In the canvas: drag three Pathway Visualization nodes onto the board and connect each one from the output handle of the single Pathway Enrichment node.
Top GO Biological Process terms per cluster as horizontal bars. Best for a quick biological summary of each cluster.
plot_typebarplotgene_setGO_Biological_Process_2023n_top_terms8figsize_w14figsize_h10Top KEGG pathway enrichment per cluster as horizontal bars. Monocyte clusters commonly show MAPK signaling, PI3K-Akt, TNF signaling, and complement pathways. T cell clusters show T cell receptor signaling and cytokine-cytokine receptor interaction.
plot_typebarplotgene_setKEGG_2021_Humann_top_terms8figsize_w14figsize_h10A dotplot where dot size encodes the number of overlapping genes and color encodes adjusted p-value. This lets you compare both significance and gene coverage across clusters simultaneously.
plot_typedotplotgene_setGO_Biological_Process_2023n_top_terms5figsize_w16figsize_h10What you'll see
All three plots appear on their node cards at once. Comparing GO and KEGG results for the same cluster helps confirm biological identity — concordance between a GO "cytokine signaling" term and a KEGG "cytokine-cytokine receptor interaction" pathway is strong evidence.
Cell-Cell Interaction (CellPhoneDB)
CellPhoneDB identifies statistically significant ligand-receptor interactions between pairs of cell types by testing co-expression of interaction partners across cluster pairs with a permutation test (cell-type labels shuffled 1,000 times). Run the preprocessing pipeline and extend with CellPhoneDB followed by three CellPhoneDB Plot nodes in a fan-out pattern.
Pipeline (scroll →)
Fan-out from CellPhoneDB (CellPhoneDB Plot nodes)
Key Requirements — database and gene symbols
CellPhoneDB needs (1) its interaction database, installed once from the Resource Center (v5 recommended for its improved scoring) — the node's cpdb_file_path is filled in from that install; (2) human HGNC gene symbols in var_names — mouse data is not supported, convert to human orthologs first; and (3) a cell-type or cluster label column in obs (celltype_key). Cluster numbers work, but annotated names (Edit Clusters, Auto Annotation, CellTypist) make the plots readable.
Normalize to CP10K. The shipped template switches save_counts on so the raw integer counts stay available in layers["counts"] alongside the log-normalized matrix CellPhoneDB scores on.
target_sum10000save_countstrueRun Leiden clustering. CellPhoneDB will use these cluster labels as cell type annotations. Use the same resolution as Template 1 for consistent cluster identities.
methodleidenresolution0.8key_addedleidenRun the CellPhoneDB statistical analysis in-app (mode: run) to identify significant ligand-receptor interactions between all cluster pairs. cpdb_file_path points at the database .zip installed via the Resource Center (auto-filled); iterations sets the permutations, threshold the minimum fraction of expressing cells, pvalue the cutoff the plots use. mode: load is for reading an existing CellPhoneDB CLI output folder (means.txt / pvalues.txt) via output_dir instead of computing.
moderunor load = read existing CLI outputcelltype_keyleidenor any obs column with cell type labelscpdb_file_path<auto-filled from Resource Center>analysis_methodstatisticaliterations1000threshold0.1pvalue0.05What you'll see
uns["cpdb_results"] stores the means and pvalues tables. Each row is a ligand-receptor pair; each column is a cluster-pair combination (e.g., "0|1"). If no interaction is significant the node explains the likely cause (non-human symbols, wrong normalization).
Tip
If you have manually annotated cell types (e.g., obs["cell_type"] = "CD4 T cells"), set celltype_key to that column for more interpretable interaction labels.
CellPhoneDB Plot, plot_type heatmap: a matrix where each cell represents the number of significant interactions between two clusters. High values (dark color) indicate pairs with many active ligand-receptor interactions. symmetrical averages the two directions.
plot_typeheatmapcelltype_keyleidenfigsize_w10figsize_h8What you'll see
Heatmap of interaction counts per cluster pair. In PBMC data, myeloid–lymphoid pairs (monocytes with T cells) commonly carry the most interactions — chemokine, MHC-II and co-stimulatory pairs.
Rows are ligand-receptor pairs; columns are cluster-pair combinations. Dot size encodes significance and color encodes mean expression of the ligand-receptor pair. cell_type1 / cell_type2 are LABEL VALUES (e.g. "T cell"), not obs column names; "." matches all.
plot_typedotplotcelltype_keyleidencell_type1."." matches all cluster typescell_type2.figsize_w14figsize_h10What you'll see
Interactions such as MIF–(CD74+CD44), CXCL/CXCR chemokine pairs and CD80/CD86–CD28 co-stimulation are commonly reported in PBMC data; use the dotplot to see which cluster pairs carry them.
A chord diagram where arcs represent cell types and ribbons represent significant interactions. Ribbon width is proportional to the number of significant interactions. link_direction: 1 draws directed arcs (ligand → receptor), making it easy to see which cell type is the sender vs. the receiver; interaction highlights chosen L-R pairs.
plot_typechordcelltype_keyleidencell_type1.cell_type2.link_direction1directed arcs: ligand → receptorfigsize_w12figsize_h12What you'll see
Thick ribbons between the monocyte and T cell arcs visually confirm strong cross-talk; thinner ribbons between B cells and T cells reflect co-stimulatory interactions.
Alternative: LIANA consensus
Swap the CellPhoneDB node for LIANA (celltype_key: leiden, resource_name: consensus, expr_prop 0.1, n_perms 1000) and its LIANA Plot (dotplot of the top_n interactions ordered by magnitude_rank or specificity_rank, filterable by source_labels / target_labels). LIANA needs log1p-normalised expression in X and its ligand-receptor resource from the Resource Center; the consensus resource is human HGNC, and mouseconsensus covers mouse without ortholog conversion.
Expected Results
- • After QC: ~2,638 cells; 8–10 Leiden clusters at resolution 0.8
- • GO — T cell clusters: T cell activation, adaptive immune response, lymphocyte proliferation
- • GO — Monocyte clusters: innate immune response, myeloid leukocyte activation, response to lipopolysaccharide
- • KEGG — T cell clusters: T cell receptor signaling, cytokine-cytokine receptor interaction, Th1/Th2 differentiation
- • KEGG — Monocyte clusters: MAPK signaling, PI3K-Akt signaling, TNF signaling, complement and coagulation cascades
- • CellPhoneDB heatmap: highest interaction counts between monocyte and T cell clusters
- • Typical interactions: MIF–(CD74+CD44), chemokine CXCL/CXCR pairs, CD80/CD86–CD28 co-stimulation — exact pairs depend on the clustering
Going Further
- Run enrichment on bulk DEG output instead — the Bulk RNA-seq tutorial Template 2 covers the GSEA / ORA node on the airway DESeq2 results.
- Score pathway and TF activity per sample or cell with PROGENy Activity, Hallmark Activity and CollecTRI TF Activity — complementary to marker-list enrichment because a pathway can be active without every member being a DEG.
- For methylation data, use the dedicated Methyl GOmeth node which corrects for CpG density bias — see the Methylation tutorial.
- To connect spatial proximity with signaling, use the spatial Ligand-Receptor node (squidpy ligrec, permutation test between clusters) or Spatial Ligand-Receptor (per-spot bivariate co-localization) on Visium data — see Phase 4 of the Visium tutorial.
Glossary
- Enrichr
- A web service hosted by the Ma'ayan Lab that runs over-representation analysis against 100+ curated gene-set libraries. Oreumics queries it via the gseapy Python wrapper; it is the one resource the Resource Center lists as queried rather than installed.
- ORA vs. GSEA vs. activity
- ORA tests a cut-off gene list for over-representation; GSEA walks the whole ranked list; activity inference (PROGENy / Hallmark / CollecTRI) fits a prior to the expression matrix and needs no gene list at all.
- GO Biological Process
- The Gene Ontology "biological process" namespace — a controlled vocabulary of cellular activities (immune response, cell division, etc.) annotated to genes.
- KEGG
- Kyoto Encyclopedia of Genes and Genomes — a curated set of pathway diagrams (T cell receptor signaling, MAPK signaling, etc.) annotated to gene members.
- CellPhoneDB
- A curated human ligand-receptor database (~2,000–3,000 pairs including heterodimers) plus a permutation test between cell types. Outputs a means matrix and pvalues matrix per cluster pair. Database installed via the Resource Center.
- LIANA
- A framework that runs several ligand-receptor scoring methods and aggregates them (rank_aggregate) into magnitude_rank and specificity_rank — less method-specific bias than any single tool.
- Fan-out pattern
- Connecting multiple downstream visualization nodes to one upstream analysis node so each viz reads the same cached result without recomputing.