Interacting with domino Objects

In this tutorial, we will go into more detail on the structure of a domino() object and the ways in which to access the data stored within. We will be using 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.

Object contents

There is a great deal of information stored with the domino() object class. The domino() object is an S4 class object that contains a variety of information about the data set used to build the object, the calculated values, and the linkages between receptors, ligands, and transcription factors. The object is structured as follows (with some examples of the information stored within each slot):

Input Data
- Information about the database used to construct the rl_map
- Inputted counts matrix
- Inputted z-scored counts matrix
- Inputted cluster labels
- Inputted transcription factor (TF) activity scores
Calculated values
- P-values for differential activity of TFs in each cluster
- Correlation values between receptor expression and TF activity
- Receptor-TF correlations with receptor complexes summarized as the median of their component genes
Linkages
- Complexes show the component genes of any complexes in the rl_map
- Receptor-ligand linkages as determined from the rl_map
- TF-target linkages as determined from the SCENIC analysis (or other regulon inference method)
- TFs that are active in each cluster
- TFs that are correlated with receptors
- TFs that are correlated with receptors in each cluster
- Receptors which are active in each cluster
- Ligands that may activate a receptor in a given cluster (so-called incoming ligands; these may include ligands from outside the data set)
Signaling matrices
- For each cluster, incoming ligands and the clusters within the data set that they are coming from
- A summary of signaling between all clusters
Miscellaneous Information
- Create information, which includes the parameters and package version used to create the object in create_domino()
- Build information, which includes the parameters and package versionused to build the object in build_domino()
- The processed rl_map used in building the object
- The percent expression of receptors within each cluster

For commonly accessed information (the number of cells, clusters, and some build information), the show and print methods for domino() objects can be used.

dom
#> A domino object of 2607 cells
#>                 Contains signaling between 9 clusters
#>                 Built with a maximum of 25 TFs per cluster
#>                 and a maximum of 25 receptors per TF

print(dom)
#> A domino object of 2607 cells
#>                 Contains signaling between 9 clusters
#>                 Built with a maximum of 25 TFs per cluster
#>                 and a maximum of 25 receptors per TF

Access functions

To facilitate access to the information stored in the domino() object, we have provided a collection of functions to retrieve specific items. These functions begin with “dom_” and can be listed using ls().

ls("package:dominoSignal", pattern = "^dom_")
#>  [1] "dom_clusters"      "dom_correlations"  "dom_counts"       
#>  [4] "dom_database"      "dom_de"            "dom_info"         
#>  [7] "dom_linkages"      "dom_network_items" "dom_signaling"    
#> [10] "dom_signalling"    "dom_tf_activation" "dom_to_df"        
#> [13] "dom_zscores"

Input data

When creating a domino() object with the create_domino() function, several inputs are required which are then stored in the domino() object itself. These include cluster labels, the counts matrix, z-scored expression matrix, TF activity scores, and the receptor-ligand database used in create_rl_map_cellphonedb().

For example, to access the cluster names in the domino() object:

dom_clusters(dom)
#> [1] "B_cell"            "CD14_monocyte"     "CD16_monocyte"    
#> [4] "CD8_T_cell"        "dendritic_cell"    "memory_CD4_T_cell"
#> [7] "naive_CD4_T_cell"  "NK_cell"           "Platelet"

Setting an argument labels = TRUE will return the vector of cluster labels for each cell rather than the unique cluster names.

To access the counts:

count_matrix <- dom_counts(dom)

Show table code

kableExtra::kable_styling(knitr::kable(count_matrix[1:5, 1:5], caption = "Subset of counts matrix from domino object."),
    bootstrap_options = c("striped", "hover"))

Subset of counts matrix from domino object.
	AAACATACAACCAC-1	AAACATTGAGCTAC-1	AAACATTGATCAGC-1	AAACCGTGCTTCCG-1	AAACCGTGTATGCG-1
AL627309.1	0	0	0	0	0
AP006222.2	0	0	0	0	0
RP11-206L10.2	0	0	0	0	0
RP11-206L10.9	0	0	0	0	0
FAM87B	0	0	0	0	0

Or z-scored expression:

z_matrix <- dom_zscores(dom)

Show table code

kableExtra::kable_styling(knitr::kable(z_matrix[1:5, 1:5], caption = "Subset of z-scored counts matrix from domino object."),
    bootstrap_options = c("striped", "hover"))

Subset of z-scored counts matrix from domino object.
	AAACATACAACCAC-1	AAACATTGAGCTAC-1	AAACATTGATCAGC-1	AAACCGTGCTTCCG-1	AAACCGTGTATGCG-1
AL627309.1	-0.0581122	-0.0581122	-0.0581122	-0.0581122	-0.0581122
AP006222.2	-0.0335151	-0.0335151	-0.0335151	-0.0335151	-0.0335151
RP11-206L10.2	-0.0399375	-0.0399375	-0.0399375	-0.0399375	-0.0399375
RP11-206L10.9	-0.0337574	-0.0337574	-0.0337574	-0.0337574	-0.0337574
FAM87B	-0.0274227	-0.0274227	-0.0274227	-0.0274227	-0.0274227

The TF activity scores can be similarly accessed:

activity_matrix <- dom_tf_activation(dom)

Show table code

kableExtra::kable_styling(knitr::kable(activity_matrix[1:5, 1:5], caption = "Subset of transcription factor activity matrix from domino object."),
    bootstrap_options = c("striped", "hover"))

Subset of transcription factor activity matrix from domino object.
	AAACATACAACCAC-1	AAACATTGAGCTAC-1	AAACATTGATCAGC-1	AAACCGTGCTTCCG-1	AAACCGTGTATGCG-1
ARNTL	0.0446386	0.0413253	0.0441566	0.0437952	0.1087952
ATF3	0.0582029	0.0870623	0.0509289	0.1172953	0.0638104
ATF4	0.0295733	0.0437047	0.0542889	0.0427879	0.0436855
ATF6	0.0000000	0.0211198	0.1151665	0.0850461	0.0460666
BCL3	0.0000000	0.0000000	0.0000000	0.0000000	0.0000000

Information about the database referenced for receptor-ligand pairs and composition of protein complexes can be extracted from the dom_database() function. By default, the function returns the name(s) of the database(s) used:

dom_database(dom)
#> [1] "CellPhoneDB_v4.0"

If you would like to view the entire receptor-ligand map, set name_only = FALSE:

db_matrix <- dom_database(dom, name_only = FALSE)

Show table code

kableExtra::kable_styling(knitr::kable(db_matrix[1:5, 1:5], caption = "Subset of full receptor-ligand map from domino object."),
    bootstrap_options = c("striped", "hover"))

Subset of full receptor-ligand map from domino object.
	int_pair	name_A	uniprot_A	gene_A	type_A
4	RAreceptor_RXRG & atRetinoicAcid_byALDH1A3	RAreceptor_RXRG	P48443,P29373	RXRG,CRABP2	R
5	RAreceptor_RXRG & atRetinoicAcid_byALDH1A2	RAreceptor_RXRG	P48443,P29373	RXRG,CRABP2	R
6	RAreceptor_RXRG & atRetinoicAcid_byALDH1A1	RAreceptor_RXRG	P48443,P29373	RXRG,CRABP2	R
7	RAreceptor_RXRB & atRetinoicAcid_byALDH1A3	RAreceptor_RXRB	P28702,P29373	RXRB,CRABP2	R
8	RAreceptor_RXRB & atRetinoicAcid_byALDH1A2	RAreceptor_RXRB	P28702,P29373	RXRB,CRABP2	R

Calculations

By default, active TFs in each cluster are determined by conducting Wilcoxon rank-sum tests for each TF where the TF activity scores amongst all cells in a cluster are tested against the activity scores of all cells outside of the cluster. The p-values for the one-sided test for greater activity within the cluster compared to other cells can be accessed with the dom_de() function.

de_matrix <- dom_de(dom)

Show table code

kableExtra::kable_styling(knitr::kable(de_matrix[1:5, 1:5], caption = "Subset of differential expression p-values for TFs."),
    bootstrap_options = c("striped", "hover"))

Subset of differential expression p-values for TFs.
	B_cell	CD14_monocyte	CD16_monocyte	CD8_T_cell	dendritic_cell
ARNTL	0.0000019	1	0.9947780	0.9865518	0.8359381
ATF3	0.0006972	0	0.0000000	1.0000000	0.0000000
ATF4	0.8399818	1	1.0000000	0.9631934	0.1748338
ATF6	0.5988625	1	0.9893142	0.0365779	0.9549489
BCL3	0.9299696	0	0.6007326	0.1482247	0.0757460

Linkages between receptors and TFs are assessed by Spearman correlation between TF activity scores and scaled expression of receptor-encoding genes across all cells in the data set. Spearman coefficients can be accessed with the dom_correlations() function. The default (type = "rl") will return the correlation of each receptor gene with each TF. Setting type= "complex" will return receptor-TF correlations in which receptor complexes are summarized as the median of their component genes (the values used by build_domino()).

cor_matrix <- dom_correlations(dom)

Show table code

kableExtra::kable_styling(knitr::kable(cor_matrix[1:5, 1:5], caption = "Correlation matrix from domino object."),
    bootstrap_options = c("striped", "hover"))

Correlation matrix from domino object.
	ARNTL	ATF3	ATF4	ATF6	BCL3
TNFRSF18	0.0057014	-0.0297120	0.0043825	0.0063055	-0.0029035
TNFRSF4	0.0373481	-0.1012705	0.0344042	0.0508720	0.0282500
TNFRSF14	-0.0356892	0.0541435	0.0015811	0.0093978	0.0206700
TNFRSF25	0.0310362	-0.1171502	0.0701541	0.0458227	0.0047186
TNFRSF1B	-0.0933019	0.2690328	-0.0625319	-0.0457366	0.0239629

Linkages

Linkages between ligands, receptors, and TFs can be accessed in several different ways, depending on the specific link and the scope desired. The dom_linkages() function has three arguments - the first, like all of our access functions, is for the domino() object. The second, link_type, is used to specify which linkages are desired (options are complexes, receptor-ligand, tf-target, or tf-receptor). The third argument, by_cluster, determines whether the linkages returned are arranged by cluster (though this does change the available linkage types to tf-receptor, receptor, or incoming-ligand). For example, to access the complexes used across the dataset:

complex_links <- dom_linkages(dom, link_type = "complexes")
# Look for components of IL7 receptor complex
complex_links$IL7_receptor
#> [1] "IL7R"  "IL2RG"

To view incoming ligands to each cluster:

incoming_links <- dom_linkages(dom, link_type = "incoming-ligand", by_cluster = TRUE)
# Check incoming signals to dendritic cells
incoming_links$dendritic_cell
#>  [1] "COPA"                  "MIF"                   "APP"                  
#>  [4] "FAM19A4"               "TAFA4"                 "ANXA1"                
#>  [7] "CD99"                  "integrin_aVb3_complex" "integrin_a4b1_complex"
#> [10] "BMP8B"                 "PLAU"                  "CSF3"                 
#> [13] "CXCL9"                 "HLA-F"                 "CD1D"                 
#> [16] "INS"                   "IL34"                  "CSF1"                 
#> [19] "CSF2"                  "CTLA4"                 "CD28"                 
#> [22] "GRN"                   "TNF"                   "LTA"                  
#> [25] "CXCL12"                "CXCL14"                "CD58"

If, for some reason, you find yourself in need of the entire linkage structure (not recommended), it can be accessed through its slot name; domino() objects are S4 objects.

all_linkages <- slot(dom, "linkages")
# Names of all sub-structures:
names(all_linkages)
#> [1] "complexes"          "rec_lig"            "tf_targets"        
#> [4] "clust_tf"           "tf_rec"             "clust_tf_rec"      
#> [7] "clust_rec"          "clust_incoming_lig"

Alternately, to obtain a simplified list of receptors, ligands, and/or features in the domino() object, use the dom_network_items() function. To pull all transcription factors associated with the dendritic cell cluster:

dc_tfs <- dom_network_items(dom, "dendritic_cell", which_return = "features")
head(dc_tfs)
#> [1] "ATF3"  "CEBPD" "FOSB"  "STAT6" "KLF4"  "CEBPA"

Signaling Matrices

The mean z-scored expression of ligands, by sending cluster, that target each receiving cluster’s active receptors can be accessed in matrix form.

signal_matrix <- dom_signaling(dom)

Show table code

kableExtra::kable_styling(knitr::kable(signal_matrix, caption = "Cluster signaling matrix of averaged z_scored expression."),
    bootstrap_options = c("striped", "hover"))

Cluster signaling matrix of averaged z_scored expression.
	L_B_cell	L_CD14_monocyte	L_CD16_monocyte	L_CD8_T_cell	L_dendritic_cell	L_memory_CD4_T_cell	L_naive_CD4_T_cell	L_NK_cell	L_Platelet
R_B_cell	0.0494729	0.1976263	0.1686996	0.0000000	0.3040989	0.2459618	0.1367747	0.0000000	4.013299
R_CD14_monocyte	0.8060665	2.5378490	1.4429140	1.1787148	3.4961650	2.2611486	1.2608492	1.4485708	10.559449
R_CD16_monocyte	0.8060665	2.5378490	1.1473216	1.1787148	3.4961650	2.2611486	0.8757246	1.4055805	7.258572
R_CD8_T_cell	0.3759111	0.0000000	0.1263349	0.2120444	0.0000000	0.2772703	0.0000000	0.1604005	0.000000
R_dendritic_cell	0.3176857	2.5041485	0.7368126	1.3152485	3.4961650	2.3809976	0.3061580	1.5659811	7.258572
R_memory_CD4_T_cell	0.3759111	0.0000000	0.1263349	0.2120444	0.0000000	0.3801282	0.0000000	0.1604005	0.000000
R_naive_CD4_T_cell	0.3759111	0.0000000	0.1263349	0.2120444	0.0000000	0.3801282	0.0000000	0.1604005	0.000000
R_NK_cell	0.2930600	1.5760509	0.6086536	0.2556741	1.5025648	0.7620921	0.1772729	0.1604005	4.013299
R_Platelet	0.0000000	0.0000000	0.0000000	0.0000000	0.0000000	0.0000000	0.0000000	0.0000000	0.000000

To view signaling to a specific cluster from the other clusters, set the cluster argument to the cluster name.

dc_matrix <- dom_signaling(dom, "dendritic_cell")

Show table code

kableExtra::kable_styling(knitr::kable(dc_matrix, caption = "Cluster signaling matrix for dendritic cell cluster."),
    bootstrap_options = c("striped", "hover"))

Cluster signaling matrix for dendritic cell cluster.
	L_B_cell	L_CD14_monocyte	L_CD16_monocyte	L_CD8_T_cell	L_dendritic_cell	L_memory_CD4_T_cell	L_naive_CD4_T_cell	L_NK_cell	L_Platelet
COPA	0.0000000	0.1352458	0.1686996	0.0000000	0.1706852	0.0243003	0.0000000	0.0000000	0.1634935
MIF	0.0000000	0.0000000	0.0000000	0.0000000	0.0810828	0.1637432	0.1367747	0.0000000	0.0000000
APP	0.0494729	0.0623805	0.0000000	0.0000000	0.0523309	0.0579182	0.0000000	0.0000000	3.8498060
ANXA1	0.0000000	0.1864958	0.0000000	0.1682595	0.6876552	0.5065038	0.0000000	0.3542401	0.0000000
CD99	0.0000000	0.0626658	0.0000000	0.4718174	0.0000000	0.1952307	0.0000000	0.7924524	1.9983051
integrin_a4b1_complex	0.0775377	0.0000000	0.0274081	0.0128595	0.0933263	0.1408531	0.0000000	0.0000000	1.2469674
BMP8B	0.1291568	0.0000000	0.0000000	0.0000000	0.0000000	0.0000000	0.0000000	0.0000000	0.0000000
PLAU	0.0000000	0.0455798	0.0000000	0.0711901	0.0000000	0.0000000	0.0000000	0.0000000	0.0000000
CXCL9	0.0000000	0.0663249	0.0000000	0.0000000	0.0000000	0.0582573	0.0000000	0.0000000	0.0000000
HLA-F	0.0000000	0.0000000	0.0000000	0.2918047	0.0000000	0.0000000	0.0000000	0.2588880	0.0000000
CD1D	0.0615183	0.5670314	0.1007509	0.0000000	1.2126187	0.0000000	0.0000000	0.0000000	0.0000000
CSF1	0.0000000	0.0000000	0.0000000	0.0067252	0.0000000	0.1724684	0.0000000	0.0000000	0.0000000
CTLA4	0.0000000	0.0000000	0.0000000	0.0369179	0.0000000	0.2085753	0.0000000	0.0000000	0.0000000
CD28	0.0000000	0.0000000	0.0000000	0.0000000	0.0000000	0.2771802	0.1288850	0.0000000	0.0000000
GRN	0.0000000	1.3784246	0.2818176	0.0000000	1.1878101	0.0000000	0.0000000	0.0000000	0.0000000
TNF	0.0000000	0.0000000	0.0318015	0.1191403	0.0106558	0.1381279	0.0000000	0.0000000	0.0000000
LTA	0.0000000	0.0000000	0.0000000	0.0000000	0.0000000	0.1828448	0.0404983	0.0000000	0.0000000
CXCL12	0.0000000	0.0000000	0.0000000	0.0000000	0.0000000	0.1028579	0.0000000	0.0000000	0.0000000
CD58	0.0000000	0.0000000	0.1263349	0.1365337	0.0000000	0.1521363	0.0000000	0.1604005	0.0000000

Build information

To keep track of the options set when running create_domino() and build_domino(), they are stored within the domino() object itself. To view these options, use the dom_info() function. Objects created with dominoSignal version 1.7.1 or newer also record the package versions used to create and build them. This example object was generated before that, so the package versions are NULL (as are the build_domino() parameters, which were also added in version 1.7.1).

dom_info(dom)
#> $create
#> [1] TRUE
#> 
#> $build
#> [1] TRUE
#> 
#> $create_variables
#> NULL
#> 
#> $build_variables
#>     max_tf_per_clust          min_tf_pval       max_rec_per_tf 
#>               25.000                0.001               25.000 
#> rec_tf_cor_threshold   min_rec_percentage 
#>                0.250                0.100 
#> 
#> $create_version
#> NULL
#> 
#> $build_version
#> NULL

Building the object again (with different parameters) results in a domino() object with the new parameters.

dom <- build_domino(dom, max_tf_per_clust = Inf, max_tf_pval = 0.05, max_rec_per_tf = 50,
    rec_tf_cor_threshold = 0.1, min_rec_percentage = 0.05)
dom_info(dom)
#> $create
#> [1] TRUE
#> 
#> $build
#> [1] TRUE
#> 
#> $create_variables
#> NULL
#> 
#> $build_variables
#>     max_tf_per_clust          max_tf_pval       max_rec_per_tf 
#>                  Inf                 0.05                50.00 
#> rec_tf_cor_threshold   min_rec_percentage 
#>                 0.10                 0.05 
#> 
#> $create_version
#> NULL
#> 
#> $build_version
#> [1] "1.7.1"

Interacting with domino Objects

Object contents

Access functions

Input data

Calculations

Linkages

Signaling Matrices

Build information

Related articles