Example

To run a toy example, use the test.example.rds data

# Installing DIALOGUE 
setwd("~/Desktop/") # use the path to where the DIALOGUE package is 
devtools::install("DIALOGUE")
library(DIALOGUE)
# Run a toy example
rA<-readRDS(system.file("Data", "test.example.rds", package = "DIALOGUE"))

rA is a list of three cell types, denoted as A, B, and C.

summary(rA)
  Length Class     Mode
A 1      cell.type S4  
B 1      cell.type S4  
C 1      cell.type S4  

Call DLG.get.param to generate a list of input parameters for DIALOGUE. See ?DLG.get.param for more information about the different input parameters. You can use the default parameters and just define the

k - the number of MCPs to identify results.dir - output directory conf - confounding factors to account for in the HLM step (default is "cellQ") pheno (optional) - the phenotype to examine associations with the MCPs

param<-DLG.get.param(k = 2,results.dir = "~/Desktop/DLG/Results/",
                     n.genes = 100,conf = "cellQ",pheno = "pathology")

Run DIALOGUE to find multicellular programs (MCPs):

> R<-DIALOGUE.run(rA = rA,main = "toyExample",param = param, plot.flag = T)

"#************DIALOGUE Step I: PMD ************#"
"A: Removing 0 of 30 features."
"B: Removing 0 of 30 features."
"C: Removing 0 of 30 features."
"#************DIALOGUE Step II: HLM ************#"
"y ~ (1 | samples) + x + cellQ + tme.qc"
"#************DIALOGUE Step II (multilevel modeling): A vs. B ************#"
"2 MCPs identified for these cell types."
"#************Finalizing the scores************#"

The output will include the MCPs

> summary(R)
               Length Class  Mode     
name            1     -none- character
param          24     -none- list     
cell.types      3     -none- character
k               4     -none- numeric  
emp.p           6     -none- numeric  
MCP.cell.types  2     -none- list     
gene.pval       3     -none- list     
pref            3     -none- list     
scores          3     -none- list     
MCPs.full       5     -none- list     
MCPs            5     -none- list     
phenoZ          8     -none- numeric  

# The gene sets in MCP1 and MCP2
> summary(unlist(R$MCPs,recursive = F))
            Length Class  Mode     
MCP1.A.up   100    -none- character
MCP1.B.up    99    -none- character
MCP1.C.up   100    -none- character
MCP1.A.down  95    -none- character
MCP1.B.down  91    -none- character
MCP1.C.down  94    -none- character
MCP2.A.up    66    -none- character
MCP2.B.up    13    -none- character
MCP2.C.up    58    -none- character
MCP2.A.down 100    -none- character
MCP2.B.down  69    -none- character
MCP2.C.down  97    -none- character

# The genes up-regulated in cell type A in MCP1
> R$MCPs$MCP1$A.down
 [1] "ACTR2"     "ADD3"      "AGR3"      "ATP10B"    "ATP1B1"    "ATP5I"     "ATP8B1"    "B3GALT5"  
 [9] "B3GNT7"    "C14orf2"   "C15orf48"  "C8orf59"   "CAMK2D"    "CAMK2N1"   "CANX"      "CAPZA1"   
[17] "CCDC14"    "CDC42"     "CDH1"      "CERS6"     "CHP1"      "CLTC"      "COX7B"     "COX7C"    
[25] "CTNNB1"    "CTTN"      "DDAH1"     "DDX17"     "DSG2"      "EPB41L4B"  "FABP2"     "FAM120A"  
[33] "FRYL"      "GALNT7"    "GNAQ"      "GOLIM4"    "GTF2H5"    "HIGD1A"    "HNRNPH1"   "INSR"     
[41] "IQGAP1"    "ITGB1"     "LCN2"      "LGR4"      "LINC00657" "LPP"       "MAN2A1"    "MARCKS"   
[49] "MDM4"      "MGST2"     "MT-ATP6"   "MT-CO2"    "MT-ND3"    "MT-ND4L"   "MTRNR2L3"  "N4BP2L2"  
[57] "NCKAP1"    "NDUFB1"    "NHSL1"     "NRIP1"     "PARM1"     "PDCD4"     "PIGR"      "PJA2"     
[65] "PKP2"      "PPP1CB"    "PPP3CA"    "PRAC1"     "PRKACB"    "PTBP3"     "RBM47"     "RPL34"    
[73] "RPL37"     "RPL39"     "RPS29"     "S100A6"    "SEC61G"    "SLC12A2"   "SLC26A2"   "SLC38A1"  
[81] "SLC4A4"    "SPINK1"    "SPINK5"    "SPON1"     "SULT1B1"   "TBL1XR1"   "TM9SF3"    "TRA2A"    
[89] "TSPAN8"    "TSPYL1"    "UHMK1"     "UQCRB"     "USMG5"     "WFDC2"     "XIST"

The MCPs' association with a specific phenotype of interest, given as phenoZ in DIALOGUE.run. The magnitude of the value is -log₁₀(p-value) and its sign denotes whether the association is positive or negative.

> print(round(R$phenoZ,2))
    MCP1  MCP2
A   -3.04  1.39
B   -3.30  1.07
C   -4.43 -1.05
All -3.86  0.86

In this toy example, MCP2 shows a strong inverse association with the phenotype, particularly in cell type A, while MCP1 shows a positive association with the phenotype across all cell types and particularly in cell type C.

A file with the plots will be at "~/Desktop/DLG/Results/DLG.output_toyExample.pdf" and the results will be saved to "~/Desktop/DLG/Results/DLG.output_toyExample.rds".