Plotting Functions and Options

dominoSignal provides several functions for visualizing analysis results. Here, we go over the available plotting functions, their options, and ways to customize them.

Setup and data load

set.seed(42)
library(dominoSignal)

In this tutorial, we will use the domino() object we built on the Getting Started page. If you have not yet built a domino() object, you can do so by following the instructions on that page.

Instructions to load data 
# BiocFileCache helps with managing files 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)

Heatmaps

Correlations between receptors and transcription factors

cor_heatmap() can be used to show the correlations calculated between receptors and transcription factors (TFs).

cor_heatmap(dom, title = "PBMC R-TF Correlations", column_names_gp = grid::gpar(fontsize = 8))

Heatmap of correlation values between receptors and transcription factors across the set.

In addition to displaying the scores for the correlations, this function can also be used to identify correlations above a certain value (using the bool and bool_thresh arguments) or to identify the combinations of receptors and TFs that are connected (with argument mark_connections).

cor_heatmap(dom, bool = TRUE, bool_thresh = 0.25)
cor_heatmap(dom, bool = FALSE, mark_connections = TRUE)

Heatmap of correlations shown as true or false with threshold of 0.25 and heatmap of correlations with xs shown over receptors and transcription factors that are linked.Heatmap of correlations shown as true or false with threshold of 0.25 and heatmap of correlations with xs shown over receptors and transcription factors that are linked.

If only a subset of receptors or TFs are of interest, a vector of either (or both) can be passed to the function.

receptors <- c("CSF1R", "CSF3R", "CCR7", "FCER2")
tfs <- c("PAX5", "JUNB", "FOXJ3", "FOSB")
cor_heatmap(dom, feats = tfs, recs = receptors)

A subsetted heatmap showing the correlation between specific transcription factors and receptors of interest.

The heatmap functions in dominoSignal are based on ComplexHeatmap::Heatmap() and will also accept additional arguments meant for that function. For example, while an argument for clustering rows or columns of the heatmap is not explicitly stated, they can still be passed to ComplexHeatmap::Heatmap() through cor_heatmap(). To set column_title directly, set title = FALSE.

cor_heatmap(dom, title = FALSE, cluster_rows = FALSE, cluster_columns = FALSE, column_title = "Heatmap Without Clustering",
    column_names_gp = grid::gpar(fontsize = 4))

A correlation heatmap that has not been clustered and does not display a dendrogram as a result.

Heatmap of Transcription Factor Activation Scores

feat_heatmap() is used to show the activity of the TFs in the signaling network.

feat_heatmap(dom, use_raster = FALSE, row_names_gp = grid::gpar(fontsize = 4))

A heatmap showing transcription factor activation levels by cells which are arranged by cluster.

It functions similarly to cor_heatmap(), with arguments to select a specific vector of features, to use a boolean view with a threshold, and to pass other arguments to ComplexHeatmap::Heatmap(). Specific to this function are arguments for setting the range of values to be visualized and an argument to choose to normalize the scores to the max value.

feat_heatmap(dom, min_thresh = 0.1, max_thresh = 0.6, norm = TRUE, bool = FALSE,
    use_raster = FALSE)
feat_heatmap(dom, bool = TRUE, use_raster = FALSE)

A heatmap showing activation of transcription factors with a minimum activity of 0.1 and maximum activity of 0.6 with values normalized to the maximum score, and a binary heatmap showing transcription factor activation with the default threshold of 0.2.A heatmap showing activation of transcription factors with a minimum activity of 0.1 and maximum activity of 0.6 with values normalized to the maximum score, and a binary heatmap showing transcription factor activation with the default threshold of 0.2.

Heatmap of incoming signaling for a cluster

incoming_signaling_heatmap() can be used to visualize the mean expression, by sending cluster, of the ligands capable of activating the TFs enriched in the cluster. For example, to view the incoming signaling of the CD8 T cells:

incoming_signaling_heatmap(dom, "CD8_T_cell")

Heatmap of ligand expression by sending cluster targeting CD8 T cells.

We can also select for specific clusters of interest that are signaling to the CD8 T cells. If we are only interested in viewing the monocyte signaling:

incoming_signaling_heatmap(dom, "CD8_T_cell", clusts = c("CD14_monocyte", "CD16_monocyte"))

Heatmap of ligand expression subset to sending clusters CD14 monocytes and CD16 monocytes targeting CD8 T cells.

As with our other heatmap functions, options are available for a minimum threshold, maximum threshold, whether to scale the values after thresholding, whether to normalize the matrix, and the ability to pass further arguments to ComplexHeatmap::Heatmap().

Heatmap of signaling between clusters

signaling_heatmap() makes a heatmap showing the signaling strength of ligands from each cluster to receptors of each cluster based on mean expression.

signaling_heatmap(dom)

Heatmap of collective signaling between receiving clusters and sending clusters.

As with other functions, specific clusters can be selected, thresholds can be set, and normalization methods can be selected as well.

signaling_heatmap(dom, scale = "sqrt")
signaling_heatmap(dom, normalize = "rec_norm")

A heatmap of collective signaling with a square root transformation and a heatmap of collective signaling normalized to the maximum value of received signaling.A heatmap of collective signaling with a square root transformation and a heatmap of collective signaling normalized to the maximum value of received signaling.

Network plots

Network showing L-R-TF signaling between clusters

gene_network() makes a network plot to display signaling in selected clusters such that ligands, receptors and features associated with those clusters are displayed as nodes with edges as linkages. To look at signaling to the CD16 Monocytes from the CD14 Monocytes:

gene_network(dom, clust = "CD16_monocyte", OutgoingSignalingClust = "CD14_monocyte")

Network plot with columns for ligand, receptor, and transcription factor showing linkages from the CD14 monocyte cluster to the CD16 monocyte cluster.

Options to modify this plot include adjusting scaling for the ligands and different layouts (some of which are more legible than others).

gene_network(dom, clust = "CD16_monocyte", OutgoingSignalingClust = "CD14_monocyte",
    lig_scale = 25, layout = "sphere")

Network plot for CD14 monocytes to CD16 monocyte with ligand values scaled up and a spherical network layout.

Additionally, colors can be given for select genes (for example, to highlight a specific signaling path).

gene_network(dom, clust = "CD16_monocyte", OutgoingSignalingClust = "CD14_monocyte",
    cols = c(CD1D = "violet", LILRB2 = "violet", FOSB = "violet"), lig_scale = 10)

Network plot from CD14 monocytes to CD16 monocytes in three column layout where ligand CD1D, receptor LILRB2, and transcription factor FOSB have been highlighted in violet and ligand nodes are scaled up.

Network showing interaction strength across data

signaling_network() can be used to create a network plot such that nodes are clusters and the edges indicate signaling from one cluster to another.

signaling_network(dom)

Network plot with circular layout with nodes corresponding to clusters and edges showing connections between clusters. The edges from the platelet population dominate the plot.

In addition to changes such as scaling, thresholds, or layouts, this plot can be modified by selecting incoming or outgoing clusters (or both!). An example to view signaling from the CD14 Monocytes to other clusters:

signaling_network(dom, showOutgoingSignalingClusts = "CD14_monocyte", scale = "none",
    normalize = "none", layout = "fr", scale_by = "none", edge_weight = 2, vert_scale = 10)

Network plot for signaling from the CD14 monocytes which are plotted in the center with edges connecting to the other clusters which are positioned around the central node.

As the edges in these plots do not show arrows to represent directionality, the showOutgoingSignalingClusts and showIncomingSignalingClusts arguments can be used to specify which clusters are sending or receiving signaling to resolve any ambiguity.

Other types of plots

Chord diagrams connecting ligands and receptors

circos_ligand_receptor() creates a chord plot showing ligands that can activate a specific receptor, displaying mean cluster expression of the ligand with the width of the chord.

circos_ligand_receptor(dom, receptor = "CD74")

Circos plot with outer arcs corresponding to sending clusters and inner arcs corresponding to ligands connecting to receptor CD74.

This function can be given cluster colors to match other plots you may make with your data. In addition, the plot can be adjusted by changing the threshold of ligand expression required for a linkage to be visualized or selecting clusters of interest.

cols <- c("red", "orange", "green", "blue", "pink", "purple", "slategrey", "firebrick",
    "hotpink")
names(cols) <- dom_clusters(dom, labels = FALSE)
circos_ligand_receptor(dom, receptor = "CD74", cell_colors = cols)

Circos plot identical to the one above, except that the outer cluster arcs have been assigned specific colors.

Scatter plot to visualize correlation

cor_scatter() can be used to plot each cell based on activation of the selected TF and expression of the receptor. This produces a scatter plot as well as a line of best fit to look at receptor-TF correlation.

cor_scatter(dom, "FOSB", "CD74")

Scatter plot of receptor expression by transcription factor activation with a line of best fit displayed over the points.

Do keep in mind that there is an argument for remove_rec_dropout that should match the parameter that was used when the domino() object was created. By default, the function checks to see if the parameter was used when the domino() object was created and will use that setting for the plot (for older objects that may not store those parameters, it will default to FALSE). If you want to override that setting, you can do so by specifying the argument in the function call.