While gene expression profiling is commonly used to gain an overview of cellular processes, the identification of upstream processes that drive expression changes remains a challenge. To address this issue, we introduce CARNIVAL (Liu, Trairatphisan, Gjerga et al 2019), a causal network contextualization tool which derives network architectures from gene expression footprints. CARNIVAL (CAusal Reasoning pipeline for Network identification using Integer VALue programming) integrates different sources of prior knowledge including signed and directed protein-protein interactions, transcription factor targets, and pathway signatures.
CARNIVAL refines a quantitative objective function for ILP problem by incorporating TF and pathway activities on a continuous scale. In addition, the CARNIVAL framework allows us to contextualize the network with or without known targets of perturbations. The implementation is separated into two pipelines which will be referred henceforth as Standard CARNIVAL StdCARNIVAL (with known perturbation targets as an input) and Inverse CARNIVAL InvCARNIVAL (without information on targets of perturbation). The differential gene expression is used to infer transcription factor (TF) activities with DoRothEA, which are subsequently discretized in order to formulate ILPconstraints. As a result, CARNIVAL derives a family of highest scoring networks which best explain the inferred TF activities. Continuous pathway and TF activities can be additionally considered in the objective function.
CARNIVAL is an extension of the previously implemented Causal Reasoning method from Melas et al.. The network inference process is swiftly performed with an Integer Linear Programming (ILP) formulation of causal reasoning using three solvers: the R-CRAN lpSolve free software used for solving linear problems; the open-source mixed integer programming solver Cbc (Coin-or branch and cut); or the CPLEX optimizer from IBM which can be obtained for free through the Academic Initiative. To perform the analysis with cplex or cbc, the users will then need to store the binary cbc or cplex executables on any directory they wish. The binary files of cbc can be found by first downloading one of the optimization suites provided here: https://www.coin-or.org/download/binary/OptimizationSuite/, unzip the download and from there save the cbc executable (which can be found on the bin directory) file on any of the direcotries they wish of their machines. As for the cplex, the executable file can be obtained after registration on the ILOG CPLEX Optimization Studio Similar like before, users will have to find the cplex executable binary file and save on a directory of their own wish or keep them on their default installation paths. The path to interactive version of CPLEX is differed based on the operating system. The default installation path for each OS is as follows:
For Mac OS:
For Linux:
For Windows:
Note that the version of CPLEX has to be changed accordingly (the latest current version is CPLEX-Studio129).
The lpSolve solver can be used after downloading and installing the lpSolve R-package. This solver only works for smaller examples and it can give only one optimal solution. For larger real-case examples, the users can use cbc or cplex solvers.
Besides the above mentioned solvers, users need also to install the following R-package dependencies: readr; igraph; readxl; dplyr; lpSolve
In order to visualize the automatically generated CARNIVAL networks, users will also need to download and install the Graph Visualization software graphviz.
In the CARNIVAL package, built-in examples are available as the test cases as follows:
A small toy example where the inputs are known (stdCARNIVAL)
A small toy example where the inputs are not known (invCARNVAL)
Toy example for the stdCARNIVAL pipeline:
library(CARNIVAL)
load(file = system.file("toy_inputs_ex1.RData",
package="CARNIVAL"))
load(file = system.file("toy_measurements_ex1.RData",
package="CARNIVAL"))
load(file = system.file("toy_network_ex1.RData",
package="CARNIVAL"))
# lpSolve
result = runCARNIVAL(inputObj = toy_inputs_ex1, measObj = toy_measurements_ex1,
netObj = toy_network_ex1)
print(result)## $weightedSIF
## Node1 Sign Node2 Weight
## [1,] "I1" "1" "N1" "100"
## [2,] "N1" "1" "M1" "100"
## [3,] "N1" "1" "M2" "100"
##
## $nodesAttributes
## Node ZeroAct UpAct DownAct AvgAct NodeType
## [1,] "I1" "0" "100" "0" "100" "S"
## [2,] "N1" "0" "100" "0" "100" ""
## [3,] "I2" "0" "100" "0" "100" "S"
## [4,] "N2" "100" "0" "0" "0" ""
## [5,] "M1" "0" "100" "0" "100" "T"
## [6,] "M2" "0" "100" "0" "100" "T"
##
## $sifAll
## $sifAll[[1]]
## Node1 Sign Node2
## [1,] "I1" "1" "N1"
## [2,] "N1" "1" "M1"
## [3,] "N1" "1" "M2"
##
##
## $attributesAll
## $attributesAll[[1]]
## Nodes Activity
## [1,] "I1" "1"
## [2,] "N1" "1"
## [3,] "I2" "1"
## [4,] "M1" "1"
## [5,] "M2" "1"Toy example for the invCARNIVAL pipeline:
library(CARNIVAL) # load CARNIVAL library
load(file = system.file("toy_measurements_ex2.RData",
package="CARNIVAL"))
load(file = system.file("toy_network_ex2.RData",
package="CARNIVAL"))
# lpSolve
result = runCARNIVAL(measObj = toy_measurements_ex2, netObj = toy_network_ex2)
print(result)## $weightedSIF
## Node1 Sign Node2 Weight
## [1,] "I2" "1" "N1" "100"
## [2,] "I2" "1" "N2" "100"
## [3,] "N1" "1" "M1" "100"
## [4,] "N1" "1" "M2" "100"
## [5,] "N2" "1" "M2" "100"
## [6,] "N2" "1" "M3" "100"
## [7,] "Perturbation" "1" "I2" "100"
##
## $nodesAttributes
## Node ZeroAct UpAct DownAct AvgAct NodeType
## [1,] "I1" "100" "0" "0" "0" ""
## [2,] "I2" "0" "100" "0" "100" ""
## [3,] "I3" "100" "0" "0" "0" ""
## [4,] "N1" "0" "100" "0" "100" ""
## [5,] "N2" "0" "100" "0" "100" ""
## [6,] "Perturbation" "0" "100" "0" "100" "S"
## [7,] "M1" "0" "100" "0" "100" "T"
## [8,] "M2" "0" "100" "0" "100" "T"
## [9,] "M3" "0" "100" "0" "100" "T"
##
## $sifAll
## $sifAll[[1]]
## Node1 Sign Node2
## [1,] "I2" "1" "N1"
## [2,] "I2" "1" "N2"
## [3,] "N1" "1" "M1"
## [4,] "N1" "1" "M2"
## [5,] "N2" "1" "M2"
## [6,] "N2" "1" "M3"
## [7,] "Perturbation" "1" "I2"
##
##
## $attributesAll
## $attributesAll[[1]]
## Nodes Activity
## [1,] "I2" "1"
## [2,] "N1" "1"
## [3,] "N2" "1"
## [4,] "Perturbation" "1"
## [5,] "M1" "1"
## [6,] "M2" "1"
## [7,] "M3" "1"## R version 4.0.3 (2020-10-10)
## Platform: x86_64-pc-linux-gnu (64-bit)
## Running under: Ubuntu 18.04.5 LTS
##
## Matrix products: default
## BLAS: /home/biocbuild/bbs-3.12-bioc/R/lib/libRblas.so
## LAPACK: /home/biocbuild/bbs-3.12-bioc/R/lib/libRlapack.so
##
## locale:
## [1] LC_CTYPE=en_US.UTF-8 LC_NUMERIC=C
## [3] LC_TIME=en_US.UTF-8 LC_COLLATE=C
## [5] LC_MONETARY=en_US.UTF-8 LC_MESSAGES=en_US.UTF-8
## [7] LC_PAPER=en_US.UTF-8 LC_NAME=C
## [9] LC_ADDRESS=C LC_TELEPHONE=C
## [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C
##
## attached base packages:
## [1] stats graphics grDevices utils datasets methods base
##
## other attached packages:
## [1] CARNIVAL_1.2.0 knitr_1.30
##
## loaded via a namespace (and not attached):
## [1] Biobase_2.50.0 mixtools_1.2.0 httr_1.4.2
## [4] UniProt.ws_2.30.0 bit64_4.0.5 splines_4.0.3
## [7] foreach_1.5.1 assertthat_0.2.1 stats4_4.0.3
## [10] BiocFileCache_1.14.0 RBGL_1.66.0 blob_1.2.1
## [13] yaml_2.2.1 Category_2.56.0 viper_1.24.0
## [16] pillar_1.4.6 RSQLite_2.2.1 lattice_0.20-41
## [19] glue_1.4.2 digest_0.6.27 colorspace_1.4-1
## [22] htmltools_0.5.0 Matrix_1.2-18 GSEABase_1.52.0
## [25] XML_3.99-0.5 lpSolve_5.6.15 pkgconfig_2.0.3
## [28] genefilter_1.72.0 purrr_0.3.4 xtable_1.8-4
## [31] scales_1.1.1 tibble_3.0.4 annotate_1.68.0
## [34] generics_0.0.2 IRanges_2.24.0 ggplot2_3.3.2
## [37] ellipsis_0.3.1 BiocGenerics_0.36.0 cli_2.1.0
## [40] survival_3.2-7 magrittr_1.5 crayon_1.3.4
## [43] ps_1.4.0 memoise_1.1.0 evaluate_0.14
## [46] fansi_0.4.1 doParallel_1.0.16 MASS_7.3-53
## [49] segmented_1.3-0 class_7.3-17 graph_1.68.0
## [52] tools_4.0.3 hms_0.5.3 lifecycle_0.2.0
## [55] stringr_1.4.0 S4Vectors_0.28.0 kernlab_0.9-29
## [58] munsell_0.5.0 AnnotationDbi_1.52.0 compiler_4.0.3
## [61] e1071_1.7-4 rlang_0.4.8 grid_4.0.3
## [64] RCurl_1.98-1.2 rstudioapi_0.11 iterators_1.0.13
## [67] rappdirs_0.3.1 igraph_1.2.6 bitops_1.0-6
## [70] rmarkdown_2.5 gtable_0.3.0 codetools_0.2-16
## [73] DBI_1.1.0 curl_4.3 R6_2.4.1
## [76] dplyr_1.0.2 bit_4.0.4 KernSmooth_2.23-17
## [79] readr_1.4.0 stringi_1.5.3 parallel_4.0.3
## [82] Rcpp_1.0.5 vctrs_0.3.4 dbplyr_1.4.4
## [85] tidyselect_1.1.0 xfun_0.18