This tutorial runs HyperCom on 1,000 mouse heart cells and shows how to:
The last section runs each step on its own, for those who want to see how HyperCom works.
HyperCom needs three inputs. Most failed runs come from one of them, so check them first.
| Input | What it must be |
|---|---|
| Counts | A genes x cells matrix (sparse or dense). Row names are gene symbols; column names are cell names. Raw or normalized, never scaled: HyperCom only uses whether each gene is above 0 in each cell. |
| Cell metadata | A data frame with one row per cell; row names are the cell names. A sample column (library or replicate) and, optionally, a group column (condition). |
| Ligand-receptor database | cellchat.hs.lrdb for human (genes like
TGFB1) or cellchat.mm.lrdb for mouse
(Tgfb1). |
Also:
A 1,000-cell subset of the heart failure data of Alexanian et al.,
2021, with log-normalized counts. It comes with the package as
alexanian2021.counts and
alexanian2021.metadata.
## [1] 17083 1000
## [1] "Xkr4" "Sox17" "Mrpl15" "Lypla1" "Tcea1" "Rgs20"
## [1] "AACCGCGTCCAGAGGA-2" "AACTCAGCACGAGGTA-2" "AACTCTTGTGCGAAAC-2"
## [4] "AAGGAGCAGGATCGCA-2" "ACACCAAAGACCCACC-2" "ACACCGGAGCTACCGC-2"
## sample condition celltype UMAP_1 UMAP_2
## AACCGCGTCCAGAGGA-2 2 SHAM Endothelial 1.2676813 -10.036637
## AACTCAGCACGAGGTA-2 2 SHAM Endothelial 1.7707077 -9.448688
## AACTCTTGTGCGAAAC-2 2 SHAM Endothelial 0.2925013 -9.781118
## AAGGAGCAGGATCGCA-2 2 SHAM Endothelial 1.1058826 -10.454998
## ACACCAAAGACCCACC-2 2 SHAM Endothelial -3.3748763 -10.034042
## ACACCGGAGCTACCGC-2 2 SHAM Endothelial 3.9700553 -8.899605
##
## SHAM TAC
## 2 500 0
## 3 0 500
ggplot(cell.meta, aes(x=UMAP_1, y=UMAP_2, colour=celltype)) +
geom_point(size=0.5) +
theme_classic()The data is mouse, so we use the mouse database. Each row is one
interaction: its name, the ligand, then the receptor genes
(NA when the receptor has fewer subunits).
## [1] 2377 6
## interaction ligand r1 r2 r3 r4
## 1 TGFB1_TGFBR1_TGFBR2 Tgfb1 Tgfbr1 Tgfbr2 <NA> <NA>
## 2 TGFB2_TGFBR1_TGFBR2 Tgfb2 Tgfbr1 Tgfbr2 <NA> <NA>
One call runs the whole analysis.
parallel=TRUE uses one thread per physical core
(threads sets the number; the default is 1 thread).significance=TRUE adds p-values; seed
makes them reproducible.outdir <- file.path(tempdir(), "overview")
res <- HyperCom(lrdb=cellchat.mm.lrdb, counts=alexanian2021.counts,
metadata=alexanian2021.metadata, sample="sample",
group="condition", significance=TRUE, seed=1,
parallel=TRUE, outdir=outdir, verbose=FALSE)res holds the results, and they are also saved to
outdir:
| File | Contents | In res |
|---|---|---|
0.counts.rds |
counts of the ligand and receptor genes | |
1.lrs.csv |
interactions whose genes are all expressed | res$lrs |
2.hyperedges.csv |
hyperedges of the hypergraph | |
3.adj.rds |
adjacency matrix | res$adj |
4.infMat.rds |
influence matrix | res$infMat |
5.metadata.csv |
metadata of cells and genes | res$metadata |
6.priority/priority.<weight>.csv |
ranked pairs, one file per weight | res$priority |
Read the CSV files with read.csv and the
.rds files with readRDS (after
library(HyperCom)).
## [1] "0.counts.rds" "1.lrs.csv"
## [3] "2.hyperedges.csv" "3.adj.rds"
## [5] "4.infMat.rds" "5.metadata.csv"
## [7] "6.priority/priority.1.csv"
Same arguments, but HyperCom reads the counts and metadata from the
object. sample, group and keep
name columns of its cell metadata (seurat[[]] or
colData(sce)).
res <- HyperCom_seurat(seurat=seurat_object, lrdb=cellchat.mm.lrdb, sample="sample",
group="condition", parallel=TRUE, outdir="overview")
res <- HyperCom_sce(sce=sce_object, lrdb=cellchat.mm.lrdb, sample="sample",
group="condition", parallel=TRUE, outdir="overview")HyperCom_seurat reads the
counts layer of the RNA assay by default
(change with assay and layer). Works with
Seurat v5 and older. Needs the SeuratObject package.HyperCom_sce reads the
counts assay by default (change with assay).
Row names must be gene symbols. Data stored on disk (DelayedArray,
HDF5Array) is read only for the database genes. Needs the
SingleCellExperiment package from Bioconductor.res$priority has one table per weight, sorted from the
highest priority. A pair ranks high when the cells that express its
genes:
group, concentrate in some groups.With significance=TRUE, the tables also have
p-values:
## interaction priority p p.adj
## 1 THBS1_SDC4 0.3313764 0.000 0.00000000
## 2 PGF_VEGFR1 0.3179562 0.000 0.00000000
## 3 COMP_SDC4 0.2923955 0.001 0.03688496
## 4 FN1_SDC4 0.2717061 0.001 0.03688496
## 5 POSTN_ITGAV_ITGB5 0.2651227 0.001 0.03688496
## 6 CCL4_CCR5 0.2645498 0.001 0.03688496
weights sets how much the fraction of cells counts. The
default, 1, weighs it like the other terms; smaller values favor pairs
specific to fewer cells. Several weights give one table each (see
prioritize_lr below).
Thbs1-Sdc4 is the top pair. score_hypercom scores every
cell for it:
sender, receiver: from 0
to 1, how strongly the cell sends or receives the signal, compared with
the other cells of its sample.dif = receiver - sender;
avg is their mean;
max the larger of the two.hypercom: one score per cell, negative
for senders and positive for receivers.Thbs1_Sdc4 <- score_hypercom(infMat=res$infMat, metadata=res$metadata, ligand="Thbs1",
receptors="Sdc4")
head(Thbs1_Sdc4[, c("cell", "sender", "receiver", "max", "hypercom")])## cell sender receiver max hypercom
## 1 ATTATCCAGCTACCGC-3 0.4554808 0.9505336 0.9505336 0.6882292
## 2 CGTTAGAGTTACGCGC-3 0.4754217 0.9072661 0.9072661 0.6345970
## 3 ACTGTCCCAATAACGA-2 0.4947958 0.9135973 0.9135973 0.6245427
## 4 TCTCTAATCTTTAGTC-2 0.3524036 0.8681149 0.8681149 0.6053723
## 5 CTGAAGTAGTCGTTTG-3 0.3960002 0.8620137 0.8620137 0.6044511
## 6 CATTATCTCTCTGCTG-2 0.3319691 0.8752518 0.8752518 0.6017978
How the scores are made: each pair of cells i and j of a sample gets
a score for how strongly cell i reaches the ligand and the receptor
reaches cell j, relative to how strongly i reaches j. These scores are
percent-ranked together. A cell’s sender score is its
average rank as cell i, and its receiver score its average
rank as cell j. hypercom is the sign of dif
times the percent rank of its size among the cells, times
avg.
On the UMAP, senders are blue and receivers orange. Cells that express no ligand or receptor gene are not in the hypergraph and stay grey.
umap <- data.frame(cell=rownames(cell.meta), UMAP_1=cell.meta$UMAP_1, UMAP_2=cell.meta$UMAP_2)
umap <- left_join(umap, Thbs1_Sdc4[, c("cell", "hypercom")], by=join_by(cell))
ggplot(umap, aes(x=UMAP_1, y=UMAP_2, colour=hypercom)) +
geom_point(size=0.5) +
scale_colour_gradient2(low="#0074a7", mid="grey90", high="#e69c25", na.value="grey70") +
ggtitle("Thbs1-Sdc4") +
theme_classic()Split by condition, TAC has higher densities of both senders and receivers.
Thbs1_Sdc4 <- left_join(Thbs1_Sdc4, res$metadata, by=join_by(cell))
melt.Thbs1_Sdc4 <- pivot_longer(dplyr::select(Thbs1_Sdc4, c(cell, group, sender, receiver)), !c(cell, group), names_to = "type", values_to = "score")
ggplot(melt.Thbs1_Sdc4, aes(x = score, y = type, fill=group)) +
geom_density_ridges(alpha=0.4) +
xlim(0.25, 1) +
xlab("Score") +
ylab("Score Type") +
ggtitle("Thbs1-Sdc4") +
theme_classic()For a receptor complex, give all its subunits; their scores are averaged.
Tgfb1_Tgfbr <- score_hypercom(infMat=res$infMat, metadata=res$metadata, ligand="Tgfb1",
receptors=c("Tgfbr1", "Tgfbr2"))
head(Tgfb1_Tgfbr[, c("cell", "sender", "receiver", "hypercom")])## cell sender receiver hypercom
## 1 TCTGAGAGTCATCGGC-3 0.4840497 0.9397033 0.6990499
## 2 CGACTTCAGGATCGCA-3 0.4438649 0.8966255 0.6568269
## 3 GATGAAAGTTGTCGCG-3 0.4518743 0.8918048 0.6523367
## 4 GAAATGACAATGGACG-3 0.4362486 0.8855002 0.6463206
## 5 TTAGTTCAGGCTACGA-3 0.4291181 0.8830470 0.6436045
## 6 GGATTACCACCTTGTC-3 0.4488283 0.8776201 0.6406520
Time and memory depend on the number of cells per sample (they grow with its square), so more samples of the same size cost little. The data of this tutorial takes seconds. One sample, with p-values, 8 cores:
| Cells in the sample | Time | Peak memory |
|---|---|---|
| 1,000 | 6 s | 0.5 GiB |
| 3,000 | 42 s | 0.8 GiB |
| 10,000 | 8 min | 2.4 GiB |
| 30,000 | 1.3 h | 15 GiB |
| 60,000 | 5.9 h | 57 GiB |
Time also grows with the number of ligand-receptor pairs expressed
(about 700 here). P-values took about 40% of the time at every size from
3,000 cells up (about 60% as long without them); with fewer pairs, they
are a larger share. Measured with HyperCom_seurat() on one
sample of a Xenium 5K human ovarian cancer slide, the CellChat human
database (about 700 pairs expressed), threads=8 on an Intel
Xeon Gold 6426Y node; median of 5 runs (3 at 60,000 cells).
By default the influence matrix is never built in full, so its memory
grows with the number of cells, not its square.
infmat.method="lu" builds it in full and gives exactly the
numbers of HyperCom 0.0.0.9000 (the default agrees with them to about
1e-15), but needs two matrices of all cells and genes squared.
Scoring the pairs takes almost all the time: hours on large data. As
it goes, HyperCom saves the scored pairs in
<outdir>/6.priority/cache. If a run
stops (cluster time limit, crash, closed R session),
run the same call again. The earlier steps repeat
(seconds) and scoring continues from the cache, losing at most the last
batch of pairs. You will see a message like
Continuing from the cache in overview/6.priority/cache: 812 of 2042 pairs already scored.
seed, the run keeps the background pairs it drew before the
stop.infmat.method) is not used. It is moved to
cache.old, with a warning; rename it back to continue the
run it belongs to.cache=FALSE turns it off.prioritize_lr keeps its cache in
<outdir>/cache, and none with
outdir=NULL.On a cluster, a job can therefore ask for less time than the whole run. Submit the same script again until it finishes:
This section runs each step of HyperCom on its own, with
outfile=NULL so nothing is written.
To save memory, keep only the genes of the database that are expressed (above 0). The matrix is also transposed to cells x genes.
## [1] 1000 663
Then keep only the interactions whose genes are all expressed.
## [1] 1042 5
A hyperedge links any number of nodes. HyperCom makes two types:
They are stored as a data frame with an edge and a node column (a node belongs to that edge), each edge with weight 1.
## # A tibble: 2 × 3
## edge node weight
## <chr> <chr> <dbl>
## 1 TGFB1_TGFBR1_TGFBR2 Tgfb1 1
## 2 TGFB1_TGFBR1_TGFBR2 Tgfbr1 1
The adjacency matrix has the cells, ligand genes and receptor genes
as nodes; each entry is the number of hyperedges two nodes share. It is
not stored in full: adj keeps which nodes are in which
hyperedge, which is much smaller, and works like a matrix
(dim(adj), adj[i, j],
as.matrix(adj) for the whole matrix).
## [1] 1663 1663
## node
## node AAAGATGCACAGATTC-3 AAAGATGCAGCTCGCA-3 AAAGATGCAGGTCTCG-3
## Thbs1 1 1 0
## Sdc4 0 0 0
A random walk with restart on the adjacency matrix gives the
influence matrix: entry (i, j) is the share of a walk started at node i
that ends at node j, so each row sums to 1. At every step the walk
returns to its start with the restart probability r, so
about r of each node’s influence stays on itself and the
rest spreads over the nodes it shares hyperedges with.
generate_infMat takes r (default 0.5);
HyperCom always uses 0.5. On this example the ranking
hardly depends on it: r = 0.1 and 0.8 give the same top 20
pairs as 0.5. Like adj, infMat works like a
matrix without being stored in full.
## [1] 1663 1663
## AAAGATGCACAGATTC-3 AAAGATGCAGCTCGCA-3 AAAGATGCAGGTCTCG-3
## Thbs1 0.001564199 0.0015831587 0.0002673712
## Sdc4 0.000335307 0.0003461792 0.0002531521
The matrices now have genes as well as cells, so the metadata gets a
row per gene too, with "gene" in each column. To save
memory, only the cell, sample and group columns are kept;
keep adds others.
node.meta <- generate_metadata(infMat=infMat, metadata=cell.meta,
sample="sample", group="condition",
keep=NULL, outfile=NULL)
head(node.meta)## cell sample group
## 1 AAAGATGCACAGATTC-3 3 TAC
## 2 AAAGATGCAGCTCGCA-3 3 TAC
## 3 AAAGATGCAGGTCTCG-3 3 TAC
## 4 AAAGATGGTGTTTGGT-2 2 SHAM
## 5 AAAGTAGAGGAGTTTA-2 2 SHAM
## 6 AAAGTAGCACATTTCT-2 2 SHAM
prioritize_lr ranks the pairs (section 3). The priority
is the weighted geometric mean of five terms of the cells that express
the pair’s genes: their fraction of all cells, the smallest fraction of
cells expressing one of its genes, the mean of each cell’s larger score
as sender or receiver, how evenly they split into senders and receivers,
and how much they concentrate in some groups. weights is
the weight of the first term; here two weights give two tables.
priority <- prioritize_lr(lrs=lrs, adj=adj, infMat=infMat, metadata=node.meta,
weights=c(1, 0.5), parallel=TRUE, outdir=NULL,
verbose=FALSE)
head(priority[["1"]])## interaction ligand r1 r2 r3 priority
## 1 THBS1_SDC4 Thbs1 Sdc4 <NA> <NA> 0.3313764
## 2 PGF_VEGFR1 Pgf Flt1 <NA> <NA> 0.3179562
## 3 COMP_SDC4 Comp Sdc4 <NA> <NA> 0.2923955
## 4 FN1_SDC4 Fn1 Sdc4 <NA> <NA> 0.2717061
## 5 POSTN_ITGAV_ITGB5 Postn Itgav Itgb5 <NA> 0.2651227
## 6 CCL4_CCR5 Ccl4 Ccr5 <NA> <NA> 0.2645498
## To cite package 'HyperCom' in publications use:
##
## Moy JK, Przytycki PF (2026). "HyperCom: a hypergraph-based method to
## infer cell-resolved cell-cell communication." _bioRxiv_.
## doi:10.64898/2026.09.30.755742
## <https://doi.org/10.64898/2026.09.30.755742>.
## <https://www.biorxiv.org/content/10.64898/2026.09.30.755742v1>.
##
## A BibTeX entry for LaTeX users is
##
## @Article{,
## title = {HyperCom: a hypergraph-based method to infer cell-resolved cell-cell communication},
## author = {Justin K. Moy and Pawel F. Przytycki},
## journal = {bioRxiv},
## year = {2026},
## doi = {10.64898/2026.09.30.755742},
## url = {https://www.biorxiv.org/content/10.64898/2026.09.30.755742v1},
## }
## R version 4.6.2 (2026-10-29)
## Platform: x86_64-pc-linux-gnu
## Running under: Ubuntu 26.04.1 LTS
##
## Matrix products: default
## BLAS: /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3
## LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.32.so; LAPACK version 3.12.0
##
## locale:
## [1] LC_CTYPE=en_US.UTF-8 LC_NUMERIC=C
## [3] LC_TIME=en_US.UTF-8 LC_COLLATE=en_US.UTF-8
## [5] LC_MONETARY=en_US.UTF-8 LC_MESSAGES=en_US.UTF-8
## [7] LC_PAPER=en_US.UTF-8 LC_NAME=C
## [9] LC_ADDRESS=C LC_TELEPHONE=C
## [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C
##
## time zone: Etc/UTC
## tzcode source: system (glibc)
##
## attached base packages:
## [1] stats graphics grDevices utils datasets methods base
##
## other attached packages:
## [1] tidyr_1.3.2 Matrix_1.7-6 ggridges_0.5.7 ggplot2_4.0.4 dplyr_1.2.1
## [6] HyperCom_0.2.2 rmarkdown_2.32
##
## loaded via a namespace (and not attached):
## [1] gtable_0.3.6 jsonlite_2.0.0 compiler_4.6.2 tidyselect_1.2.1
## [5] Rcpp_1.1.2 parallel_4.6.2 jquerylib_0.1.4 scales_1.4.0
## [9] yaml_2.3.12 fastmap_1.2.0 lattice_0.23-1 R6_2.6.1
## [13] labeling_0.4.3 generics_0.1.4 knitr_1.52 tibble_3.3.1
## [17] maketools_1.3.2 bslib_0.12.0 pillar_1.11.1 RColorBrewer_1.1-3
## [21] rlang_1.3.0 utf8_1.2.6 cachem_1.1.0 xfun_0.62
## [25] S7_1.0.0 sass_0.5.0 sys_3.4.3 otel_0.3.0
## [29] cli_3.6.6 withr_3.0.3 magrittr_2.0.5 digest_0.6.39
## [33] grid_4.6.2 lifecycle_1.0.5 vctrs_0.7.3 evaluate_1.0.5
## [37] glue_1.8.1 farver_2.1.2 buildtools_1.0.0 parallelly_1.50.0
## [41] purrr_1.2.2 tools_4.6.2 pkgconfig_2.0.3 htmltools_0.5.9