---
title: "Differential Signaling Workflow"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Differential Signaling Workflow}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
echo = TRUE,
message = FALSE,
warning = FALSE,
fig.cap = "",
tidy = TRUE
)
options(timeout = 600)
```
In this tutorial, we will walk through the workflow for performing differential signaling analysis using the dominoSignal package. While the other tutorials focus on signaling networks inferred from a single data set, many studies involve multiple subjects or conditions, requiring the comparison of signaling across these groups. The dominoSignal package implements the Differential Cell Signaling Test (DCST), a framework for identifying receptor, ligand, and transcription factor (TF) linkages that are significantly differentially present across groups of subjects. This method is described in detail in [Differential cell signaling testing for cell-cell communication inference from single-cell data by dominoSignal](https://doi.org/10.1093/bioinformatics/btag089) (2026) published in Bioinformatics. The publication also includes simulation benchmarking and application of the method to pancreatic cancer and immunotherapy data sets. Refer to the publication for full details on the method and biological validation of the workflow.
## Workflow overview
The differential signaling workflow consists of the following steps:
1. Build a `domino()` object per subject to be compared (see the [Getting Started](https://fertiglab.github.io/dominoSignal/articles/dominoSignal.html) tutorial for details on building a `domino()` object).
2. Compile linkages across the subjects into a [linkage_summary object](https://fertiglab.github.io/dominoSignal/reference/linkage_summary-class.html) using the `summarize_linkages()` function.
3. [Optional] Subset the `linkage_summary` object to include only the subjects of interest.
4. Create a table of linkage observations within groups of subjects using the `count_linkage()` function.
5. Test differences in linkage frequency across groups using the `test_differential_linkages()` function, which implements a Fisher's exact test.
6. Visualize the results using the `plot_differential_linkages()` function.
The DCST workflow can be performed with 2 or more groups of subjects. In this tutorial, we will demonstrate the workflow for both a two-group comparison (condition A vs condition B) and a comparison across more than two groups.
## Demonstration data
In this tutorial, we use the `domino()` object built in the [Getting Started](https://fertiglab.github.io/dominoSignal/articles/dominoSignal.html) tutorial. If you have not yet built a `domino()` object, you can do so by following the instructions on that page or use the code below to load the pre-built `domino()` object.
Instructions to load data
```{r setup}
set.seed(42)
library(dominoSignal)
library(dplyr)
library(kableExtra)
# BiocFileCache helps with file management across sessions
bfc <- BiocFileCache::BiocFileCache(ask = FALSE)
data_url <- "https://zenodo.org/records/10951634/files/pbmc_domino_built.rds"
tmp_path <- BiocFileCache::bfcrpath(bfc, data_url)
dom <- readRDS(tmp_path)
```
Creating synthetic replicates
To start, we extract the inputs from the original `domino()` object so we can supply them to the `create_domino()` function for the synthetic subjects.
```{r extract inputs}
rl_map <- dom_database(dom, name_only = FALSE)
features <- dom_tf_activation(dom)
# Access counts slot directly to maintain sparse matrix format
counts <- slot(dom, "counts")
zscores <- dom_zscores(dom)
tf_targets <- dom_linkages(dom, link_type = "tf-target")
clusters <- dom_clusters(dom, labels = TRUE)
```
We can use a helper function to resample the cells and shuffle the cluster labels for a subset of them, and then rebuild the `domino()` object with `create_domino()` and `build_domino()` using the same parameters across all subjects so that they can be compared.^[These parameters are fairly permissive to ensure enough linkages are inferred for demonstration purposes.]
```{r create replicates, results = "hide"}
build_reps <- function(clusters, seed, keep_frac, shuffle_frac) {
# Local seed for reproducibility without affecting global seed
withr::with_seed(seed, {
n_cells <- length(clusters)
keep_cells <- sort(sample.int(n_cells, size = round(n_cells * keep_frac), replace = FALSE))
resampled_clusters <- clusters[keep_cells]
features <- features[ , keep_cells, drop = FALSE]
counts <- counts[ , keep_cells, drop = FALSE]
zscores <- zscores[ , keep_cells, drop = FALSE]
shuffled_idx <- sample(seq_along(resampled_clusters),
size = round(shuffle_frac * length(resampled_clusters)), replace = FALSE
)
resampled_clusters[shuffled_idx] <- sample(resampled_clusters[shuffled_idx])
dom_shuffle <- create_domino(
rl_map = rl_map,
features = features,
counts = counts,
z_scores = zscores,
clusters = resampled_clusters,
tf_targets = tf_targets,
use_complexes = TRUE,
remove_rec_dropout = FALSE,
verbose = FALSE
)
dom_shuffle <- build_domino(
dom = dom_shuffle,
max_tf_pval = 0.05,
max_tf_per_clust = 25,
max_rec_per_tf = 25,
rec_tf_cor_threshold = 0.1,
min_rec_percentage = 0.05
)
})
return(dom_shuffle)
}
params <- data.frame(
set = c(161803, 314159, 6631034, 6021023, 831446, 98067),
keep = c(0.95, 0.95, 0.95, 0.95, 0.9, 0.9),
shuffle = c(0.15, 0.1, 0.15, 0.1, 0.15, 0.1)
)
# This does take a few minutes to run
dom_list <- purrr::pmap(params, function(set, keep, shuffle) {
build_reps(clusters, seed = set, keep_frac = keep, shuffle_frac = shuffle)
})
names(dom_list) <- paste0("P", seq_along(dom_list))
```
We now have six `domino()` objects that we can treat as different subjects (P1-6).
Show table code
```{r eval = FALSE}
kableExtra::kable_styling(
knitr::kable(count_all,
caption = "Total counts of receptor-ligand linkages in CD8 T Cells"
),
bootstrap_options = c("striped", "hover")
)
```
Show table code
```{r eval = FALSE}
kableExtra::kable_styling(
knitr::kable(count_subjects[1:5, ],
caption = "Subset of counts of TF linkages in patients P1 & P2 in CD8 T Cells"
),
bootstrap_options = c("striped", "hover")
)
```
Show table code
```{r eval = FALSE}
kableExtra::kable_styling(
knitr::kable(slice_sample(counts_time_trt, n = 5),
caption = "Counts of TF-Receptor linkages in CD14 Monocytes grouped by time for treatment subjects"
),
bootstrap_options = c("striped", "hover")
)
```
Show table code
```{r eval = FALSE}
kableExtra::kable_styling(
knitr::kable(counts_condition,
caption = "Counts of incoming ligand linkages in naive CD4 T Cells grouped by condition"
),
bootstrap_options = c("striped", "hover")
)
```
Show table code
```{r eval = FALSE}
kableExtra::kable_styling(
knitr::kable(counts_batch,
caption = "Counts of receptor linkages in CD14 Monocytes grouped by batch"
),
bootstrap_options = c("striped", "hover")
)
```
Show table code
```{r eval = FALSE}
kableExtra::kable_styling(
knitr::kable(slice_sample(dcst_time_trt, n = 5),
caption = "DCST of TF-Receptor linkages in CD14 Monocytes grouped by time for treatment subjects"
),
bootstrap_options = c("striped", "hover")
)
```
Show table code
```{r eval = FALSE}
kableExtra::kable_styling(
knitr::kable(slice_sample(dcst_time, n = 5),
caption = "DCST of receptor-ligand linkages in CD8 T Cells grouped by time"
),
bootstrap_options = c("striped", "hover")
)
```
Show table code
```{r eval = FALSE}
kableExtra::kable_styling(
knitr::kable(slice_sample(dcst_batch, n = 5),
caption = "DCST of receptors in naive CD4 T Cells grouped by batch"
),
bootstrap_options = c("striped", "hover")
)
```
Show table code
```{r eval = FALSE}
kableExtra::kable_styling(
knitr::kable(slice_sample(dcst_patient, n = 5),
caption = "DCST of receptor-ligand linkages in naive CD4 T Cells grouped by patient"
),
bootstrap_options = c("striped", "hover")
)
```
Vignette Build Information
Date last built and session information:
```{r}
Sys.Date()
sessionInfo()
```