-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.Rmd
186 lines (112 loc) · 8.71 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
---
output: github_document
#output: html_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# GraphR overview
<center><img src="GraphR_Method_plot.jpg" width="600" ></center>
The GraphR (Graphical Regression) is a flexible approach which incorporates sample heterogenity and enables covariate-dependent graphs. Our regression-based method provides a functional mapping from the covariate space to precision matrix for different types of heterogeneous graphical model settings. GraphR imposes sparsity in both edge and covariate selection and computationally efficient via use of variational Bayes algorithms. The method is versatile to incorporate different type of covariates such as <br>
(I) **binary** (control and disease specific graphs), <br>
(II) **categorical** (category specific graphs such as cancer subtypes), <br>
(III) **univariate continuous** (time varying graphs for single cell data), <br>
(IV) **categorical + univariate continuous** (graphs changing over category such as cancer sub-types and continuous scale as biomarkers), <br>
(V) **multivariate continuous** (spatial transcriptomics co-expression networks). <br>
GraphR is implemented as an open-source R package and Shiny app.
## Installation
You can install the released version of GraphR from (https://github.com/bayesrx/GraphR) with:
``` {r , eval=FALSE}
devtools::install_github("bayesrx/GraphR")
library(GraphR)
```
## Functions
### GraphR_est() function
The **GraphR_est()** function can be used to estimate the graphical regression coefficients and inclusion probabilities of external covariates for the GraphR models. It is suggested to maintain $n/pq >1$ and efficacy of the method increase with high values of $n/pq$ ratio. For priors, we assume $\pi \sim Beta(a_\pi, b_\pi)$ and $\tau \sim \Gamma(a_\tau, b_\tau)$.
The **mandatory inputs** of estimation function are given below.
+ **Features (nodes)**: Nodes of the graphs among which edges are built (e.g. a gene expression matrix of dimensions $n \times p$). **Please standardize features before plugging into the function or set standardize_feature = TRUE in the function**.
+ **Cont_external and dis_external (continuous and discrete external covariates)**: An $n \times q_1$ and an $n \times q_2$ matrices of continuous and discrete external covariates respectively. $q_1 + q_2 =q$. **Please standardize continuous external covariates before plug into the estimation function or set standardize_external = TRUE in the function.**
The **optional inputs** of estimation function are given below.
+ **$\boldsymbol a_{\boldsymbol \pi}$, $\boldsymbol b_{\boldsymbol \pi}$**: Hyper-parameters from $\pi \sim Beta(a_\pi, b_\pi)$. By default $a_\pi = 1, b_\pi = 4$.
+ **$\boldsymbol a_{\boldsymbol \tau}$, $\boldsymbol b_{\boldsymbol \tau}$**: Hyper-parameters from $\tau \sim Gamma(a_\tau, b_\tau)$. By default $a_\tau = 0.005, b_\tau = 0.005$.
+ **Standardize_feature, standardize_external**: Standardize features or continuous external covariates. Default as FALSE.
+ **Max\_iter**: Maximum number of iterations. Default as 2,000.
+ **Max\_tol**: Maximum tolerance. Default as 0.001.
**Outputs** of the **GraphR_est()** function are provided below.
+ **Beta (the graphical regression coefficients)**: A $p \times p \times q$ array of coefficients for external covariates. The $[i,j,k]$ element represents the effect of k-th external covariates on regression of j-th node on i-th node.
+ **Phi (posterior inclusion probability)**: A $p \times p \times q$ array storing posterior inclusion probability (PIP) of external covariates. The \eqn{[i,j,k]} elements represents the PIP of k-th external covariates on regression of j-th node on i-th node.
+ **Omega_diag (diagonal elements of precision matrix)**: A p vector with i-th element representing the inverse variance of error.
### GraphR_pred() function
The **GraphR_pred()** function can be used to predict partial correlation between two nodes and the corresponding inclusion probabilities from the results of GraphR model alongwith Bayesian FDR-adjusted p-values.
The **mandatory inputs** of prediction function are given below.
+ **New_df**: A matrix of new external covariates based on which predictions are made. **Note: Please ensure that the order and scale of new external covariates are same as those used in the estimation.**
The **optional inputs** of prediction function are given below.
+ **GraphR_est_res**: Results from `GraphR_est` function. If graphR_est_res = NULL, then the following three inputs: (1) beta; (2) phi; (3) omega_diag are needed.
+ **Beta**: A $p \times p \times q$ array storing coefficients of external covariates. The $[i,j,k]$ elements represents the effect of k-th external covariates on regression of j-th node on i-th node.
+ **Omega_diag**: A p vector with i-th element representing the inverse variance of error.
+ **Pip**: A $p \times p \times q$ array storing posterior inclusion probability (PIP) of external covariates. The $[i,j,k]$ elements represents the PIP of k-th external covariates on regression of j-th node on i-th node.
The **output** contains following information.
+ **Feature_id1**, **feature_id2**: Indices of features or nodes.
+ **Pr_inclusion**: Posterior inclusion probability of connections between two nodes based on "And" rules.
+ **Correlation**: Partial correlation between two nodes. Values with maximum magnitudes are provided.
+ **FDR_p**: Bayesian FDR-adjusted p values.
### GraphR_visualization() function
The **GraphR_visualization()** function provides a circular network based on
a given new external covariates vector and thresholds for FDR-p values and magnitudes of partial correlations.
The **mandatory inputs** of prediction function are given below.
+ **New_vec**: A vector of new external covariates based on which plot is made. **Note: Please ensure that the order and scale of new external covariates are same as those used in the estimation.**
The **optional inputs** of prediction function are given below.
+ **GraphR_est_res**: Results from `GraphR_est` function. If graphR_est_res = NULL, then the following three inputs: (1) beta; (2) phi; (3) omega_diag are needed.
+ **Beta**: A $p \times p \times q$ array storing coefficients of external covariates. The $[i,j,k]$ elements represents the effect of k-th external covariates on regression of j-th node on i-th node.
+ **Omega_diag**: A p vector with i-th element representing the inverse variance of error.
+ **Pip**: A $p \times p \times q$ array storing posterior inclusion probability (PIP) of external covariates. The $[i,j,k]$ elements represents the PIP of k-th external covariates on regression of j-th node on i-th node.
+ **Fdr_thre**: A numeric value. Threshold for Bayesian FDR adjusted q-values.
+ **Magnitude_thre**: A numeric value. Threshold for the magnitude of partial correlations.
+ **scale_size_node**, **scale_size_edge**: Numeric values. Adjust the size of nodes or edges in plots.
The **output** provides a circular network plot. Node sizes represent connectivity degrees of the corresponding features while edge widths are proportional to the partial correlation between two features. Sign of the partial correlations are represented by the color.
## Example
An example code with one of the existing datasets to demonstrate how to run the functions and obtain inference.
```{r, dpi=300, fig.width=7, fig.height=7}
set.seed(100)
library(GraphR)
data("Pam50")
features <- as.matrix(apply(Pam50$features,2,scale))
features[c(1:5),c(1:5)]
external <- as.matrix(Pam50$external)
external[c(1:5),]
system.time(res <- GraphR_est(
features,
external,
a_pi = 1,
b_pi = 4,
a_tau = 0.005,
b_tau = 0.005,
max_iter = 2000,
max_tol = 0.001
))
####### prediction
new_df <- diag(3)
colnames(new_df) <- colnames(external)
system.time(pred <- GraphR_pred(new_df, res))
head(pred)
####### visualization
new_vec <- c(1,0,0)
GraphR_visualization(new_vec, graphR_est_res = res,
fdr_thre = 0.01, magnitude_thre = 0.4,
scale_size_node =2, scale_size_edge =1)
```
## Shiny App and Tutorial website
[Shiny App](https://bayesrx.shinyapps.io/GraphR/)
## Paper
Liying Chen*, Satwik Acharyya*, Chunyu Luo, Yang Ni, Veerabhadran Baladandayuthapani (2024). GraphR: a probabilistic modeling framework for genomic networks incorporating sample heterogeneity.
## Supplementary file
[Supplementary](https://bookdown.org/bayesrx/graphr_supplementary/)
## Points to note
+ We recommend to standardize continuous external covariates while plugging into the functions.
+ It is suggested to maintain $n/pq > 1$ and efficacy of the method increase with high values of $n/pq$ ratio.