Merge branch 'master' into master_bioconductor

# Conflicts:
#	DESCRIPTION

.gitignore

@@ -0,0 +1,7 @@
+.Rproj.user
+.Rhistory
+.RData
+.Ruserdata
+
+*.Rproj
+.Rbuildignore

DESCRIPTION

@@ -1,13 +1,34 @@
 Package: CARNIVAL
 Title: A CAusal Reasoning tool for Network Identification (from gene expression data) using Integer VALue programming
 Version: 1.1.0
-Author: Enio Gjerga <[email protected]>
-	 Panuwat Trairatphisan
-	 Anika Liu
-	 Alberto Valdeolivas
-	 Nikolas Peschke
-Maintainer: Enio Gjerga <[email protected]>
-Description: An upgraded causal reasoning tool from Melas et al in R with updated assignments of TFs' weights from PROGENy scores. 
+Authors@R: c(
+    person(given = "Enio",
+           family = "Gjerga",
+           role = c("aut"),
+           email = "[email protected]",
+           comment = c(ORCID = "0000-0002-3060-5786")),
+    person(given = "Panuwat",
+           family = "Trairatphisan",
+           role = "aut"),
+    person(given = "Anika",
+           family = "Liu",
+           role = "ctb"),
+    person(given = "Alberto",
+           family = "Valdeolivas",
+           role = "ctb"),
+    person(given = "Nikolas",
+           family = "Peschke",
+           role = "ctb"),
+    person(given = "Aurelien",
+           family = "Dugourd",
+           role = "ctb"),
+    person(given = "Olga",
+           family = "Ivanova",
+           role = "cre",
+           email = "[email protected]",
+					 comment = c(ORCID = "0000-0002-9111-4593"))
+           )
+Description: An upgraded causal reasoning tool from Melas et al in R with updated assignments of TFs' weights from PROGENy scores.
              Optimization parameters can be freely adjusted and multiple solutions can be obtained and aggregated.
 URL: https://github.com/saezlab/CARNIVAL
 BugReports: https://github.com/saezlab/CARNIVAL/issues
@@ -24,7 +45,7 @@ Imports:
     lpSolve,
     igraph
 biocViews: Transcriptomics, GeneExpression, Network
-License: Apache License (== 3.0) | file LICENSE
+License: GPL-3 + file LICENSE
 LazyData: true
 Encoding: UTF-8
 Suggests:

NEWS.md

@@ -0,0 +1,8 @@
+# CARNIVAL 1.0.0
+* Official release with Bioconductor 3.11
+
+# CARNIVAL 0.99.44
+* Deployment of GitHub page
+
+# CARNIVAL 0.99.0 
+* Initial submission to Bioconductor

R/checkMeasObj.R

@@ -15,6 +15,24 @@ checkMeasObj <- function(measObj = measObj, netObj = netObj){
       stop("Measurement object should either be of matrix or data.frame class")
     } else {
       if(ncol(measObj)>0){
+
+        colnames(measObj) <- gsub(pattern = "-", replacement = "_", 
+                            x = colnames(measObj), fixed = TRUE)
+        colnames(measObj) <- gsub(pattern = "+", replacement = "_", 
+                            x = colnames(measObj), fixed = TRUE)
+        colnames(measObj) <- gsub(pattern = "*", replacement = "_", 
+                            x = colnames(measObj), fixed = TRUE)
+        colnames(measObj) <- gsub(pattern = "/", replacement = "_", 
+                            x = colnames(measObj), fixed = TRUE)
+        colnames(measObj) <- gsub(pattern = "<", replacement = "_", 
+                            x = colnames(measObj), fixed = TRUE)
+        colnames(measObj) <- gsub(pattern = ">", replacement = "_", 
+                            x = colnames(measObj), fixed = TRUE)
+        colnames(measObj) <- gsub(pattern = "=", replacement = "_", 
+                            x = colnames(measObj), fixed = TRUE)
+        colnames(measObj) <- gsub(pattern = " ", replacement = "_", 
+                            x = colnames(measObj), fixed = TRUE)
+
         mSpecies = colnames(measObj)
 
         idx = which(mSpecies%in%nSpecies)
@@ -39,23 +57,6 @@ checkMeasObj <- function(measObj = measObj, netObj = netObj){
     }
   }
 
-  colnames(measObj) <- gsub(pattern = "-", replacement = "_", 
-                            x = colnames(measObj), fixed = TRUE)
-  colnames(measObj) <- gsub(pattern = "+", replacement = "_", 
-                            x = colnames(measObj), fixed = TRUE)
-  colnames(measObj) <- gsub(pattern = "*", replacement = "_", 
-                            x = colnames(measObj), fixed = TRUE)
-  colnames(measObj) <- gsub(pattern = "/", replacement = "_", 
-                            x = colnames(measObj), fixed = TRUE)
-  colnames(measObj) <- gsub(pattern = "<", replacement = "_", 
-                            x = colnames(measObj), fixed = TRUE)
-  colnames(measObj) <- gsub(pattern = ">", replacement = "_", 
-                            x = colnames(measObj), fixed = TRUE)
-  colnames(measObj) <- gsub(pattern = "=", replacement = "_", 
-                            x = colnames(measObj), fixed = TRUE)
-  colnames(measObj) <- gsub(pattern = " ", replacement = "_", 
-                            x = colnames(measObj), fixed = TRUE)
-
   return(measObj)
 
-}
+}

R/write_constraints_6.R

@@ -72,7 +72,7 @@ write_constraints_6 <- function(variables=variables,
 
   idx1 <- which(rowSums(adj)==0)
   idx2 <- setdiff(seq_len(nrow(adj)), idx1)
-
+  cc1 = NULL
   if(length(idx1)>0){
 
     cc1 <-
@@ -82,7 +82,7 @@ write_constraints_6 <- function(variables=variables,
             rownames(adj)[idx1],
             " in experiment ", ii))], " <= 0")
 
-  }
+  }else cc1 <- NULL
 
   cc2 <- rep("", length(idx2))
   for(i in seq_len(length(idx2))){

R/write_constraints_7.R

@@ -69,7 +69,7 @@ write_constraints_7 <- function(variables=variables,
 
   idx1 <- which(rowSums(adj)==0)
   idx2 <- setdiff(seq_len(nrow(adj)), idx1)
-
+  cc1 <- rep("", length(idx1))
   if (length(idx1)>0) {
     cc1 <-
       paste0(

R/write_constraints_8.R

@@ -91,6 +91,7 @@ write_constraints_8 <- function(variables=variables,
   ## constraints8 <- c(constraints8, cc)
 
   ##
+  cc4 = c()
   if (length(
     setdiff(
       as.character(pknList[, 1]), 

R/write_objective_function_all.R

@@ -219,7 +219,7 @@ write_objective_function_all <- function(dataMatrix = dataMatrix,
 
     if(!is.null(measWeights)){
 
-      mm <- as.matrix(measWeights[i, ])
+      mm <- as.matrix(measWeights[i, ,drop=FALSE])
 
     } else {
 
@@ -250,4 +250,4 @@ write_objective_function_all <- function(dataMatrix = dataMatrix,
 
   return(OF)
 
-}
+}

README.md

@@ -1,14 +1,26 @@
-# CARNIVAL
+# CARNIVAL <img src="man/figures/logo.png" align="right" height="139">
 
-CARNIVAL is an R-package providing a framework to perform causal reasoning to infer a subset of signalling network from transcriptomics data. This work was originally based on [Melas et al.](https://pubs.rsc.org/en/content/articlehtml/2015/ib/c4ib00294f) with a number improved functionalities comparing to the original version.
-Transcription factors’ (TFs) activities and pathway scores from gene expressions can be inferred with our in-house tools [DoRothEA](https://github.com/saezlab/DoRothEA) & [PROGENy](https://github.com/saezlab/progeny), respectively.
-TFs’ activities and signed directed protein-protein interaction networks +/- drug targets and pathway scores are then used to derive a series of linear constraints to generate integer linear programming (ILP) problems. 
-An ILP solver (CPLEX) is subsequently applied to identify the sub-network topology with minimised discrepancies on fitting error and model size.
+<!-- badges: start -->
+<!-- badges: end -->
 
-More detailed descriptions of CARNIVAL, benchmarking and applicational studies can be found on it's dedicated [web-page](https://saezlab.github.io/CARNIVAL/) and in [Liu, Trairatphisan, Gjerga et al.](https://www.nature.com/articles/s41540-019-0118-z):
+## Overview
+CARNIVAL (**CA**usal **R**easoning for **N**etwork identification using **I**nteger **VAL**ue programming) is a method for the identification of upstream reguatory signalling pathways from downstream gene expression (GEX).
 
-> Liu A*, Trairatphisan P*, Gjerga E*, Didangelos A, Barratt J, Saez-Rodriguez J. (2019). From expression footprints to causal pathways: contextualizing large signaling networks with CARNIVAL. *npj Systems Biology and Applications*, https://doi.org/10.1038/s41540-019-0118-z (*equal contributions).
+This is a tool currently being developed by the [saezlab](http://saezlab.org/) members and is an extension of the previously implemented Causal Reasoning ([*Melas et al.*](http://pubs.rsc.org/en/content/articlehtml/2015/ib/c4ib00294f)) method. More detailed information on the CARNIVAL pipeline as well as benchmarking and applicational studies are available on following paper.
 
+> Liu A., Trairatphisan P., Gjerga E. et al. [From expression footprints to causal pathways: contextualizing large signaling networks with CARNIVAL](https://www.nature.com/articles/s41540-019-0118-z) _npj Systems Biology and Applications_ volume 5, Article number: 40 (2019) (equal contributions).
+
+The aim of the CARNIVAL pipeline is to identify a subset of interactions from a prior knowledge network that represent potential regulated pathways linking known or potential targets of perturbation towards active transcription factors derived from GEX data. The pipeline includes a number improved functionalities comparing to the original version and consists of the following processes: 
+
+ * 1) Transcription factors’ (TFs) activities and pathway scores from gene expressions can be inferred with our in-house tools DoRothEA & PROGENy, respectively. 
+
+ * 2) TFs’ activities and signed directed protein-protein interaction networks with or without the provided target of perturbations and pathway scores are then used to derive a series of linear constraints to generate integer linear programming (ILP) problems. 
+
+ * 3) An ILP solver (IBM ILOG CPLEX) is subsequently applied to identify the sub-network topology with minimised fitting error and model size.
+
+Applications of CARNIVAL include the identification of drug’s modes of action and of deregulated processes in diseases (even if the molecular targets remain unknown) by deciphering the alterations of main signalling pathways as well as alternative pathways and off-target effects.
+
+<img src="man/figures/graphical_abstract.png" align="center" width="800">
 
 ## Getting Started
 
@@ -18,45 +30,61 @@ A tutorial for preparing CARNIVAL input files starting from differentially gene
 
 CARNIVAL requires the interactive version of IBM Cplex or CBC-COIN solver as the network optimiser. The IBM ILOG Cplex is freely available through Academic Initiative [here](https://www.ibm.com/products/ilog-cplex-optimization-studio?S_PKG=CoG&cm_mmc=Search_Google-_-Data+Science_Data+Science-_-WW_IDA-_-+IBM++CPLEX_Broad_CoG&cm_mmca1=000000RE&cm_mmca2=10000668&cm_mmca7=9041989&cm_mmca8=kwd-412296208719&cm_mmca9=_k_Cj0KCQiAr93gBRDSARIsADvHiOpDUEHgUuzu8fJvf3vmO5rI0axgtaleqdmwk6JRPIDeNcIjgIHMhZIaAiwWEALw_wcB_k_&cm_mmca10=267798126431&cm_mmca11=b&mkwid=_k_Cj0KCQiAr93gBRDSARIsADvHiOpDUEHgUuzu8fJvf3vmO5rI0axgtaleqdmwk6JRPIDeNcIjgIHMhZIaAiwWEALw_wcB_k_|470|135655&cvosrc=ppc.google.%2Bibm%20%2Bcplex&cvo_campaign=000000RE&cvo_crid=267798126431&Matchtype=b&gclid=Cj0KCQiAr93gBRDSARIsADvHiOpDUEHgUuzu8fJvf3vmO5rI0axgtaleqdmwk6JRPIDeNcIjgIHMhZIaAiwWEALw_wcB). The [CBC](https://projects.coin-or.org/Cbc) solver is open source and freely available for any user. Alternatively for smaller cases, users can rely on the freely available [lpSolve R-package](https://cran.r-project.org/web/packages/lpSolve/index.html).
 
-### Installing
+### Installation
 
-CARNIVAL is currently available for the installation as an R-package from our GitHub page
+```r
+# install from bioconductor
+if (!requireNamespace("BiocManager", quietly = TRUE))
+    install.packages("BiocManager")
 
-```R
-# Install CARNIVAL from Github using devtools
-# install.packages('devtools') # in case devtools hasn't been installed
-library(devtools)
-install_github('saezlab/CARNIVAL', build_vignettes = TRUE)
-# or download the source file from GitHub and install from source
-install.packages('path_to_extracted_CARNIVAL_directory', repos = NULL, type="source")
+BiocManager::install("CARNIVAL")
+
+# install the development version from GitHub
+# install.packages("devtools")
+devtools::install_github("saezlab/CARNIVAL")
 ```
 
+### Inputs and Outputs of CARNIVAL
+
+The input for CARNIVAL consists of:
+
+ * A prior knowledge network (PKN) comprises a list of signed and directed interactions between signalling proteins. (Required)
+
+ * Inferred transcription factor activities which can be inferred from GEX data using [DoRothEA](https://github.com/saezlab/dorothea). (Required)
+
+ * A list of target of perturbations (drugs, diseases, etc.) with or without their effects on signalling proteins. (Optional) 
+
+ * Inferred pathway scores representing signalling pathway activities from GEX data using [PROGENy](https://github.com/saezlab/progeny) (Optional)
+
+The outcome of CARNIVAL includes the list of identified networks that fitted to the provided experimental data as well as the predicted activities of signalling proteins in the networks whether they are up- or down-regulated.
+
 ## Running CARNIVAL
 
 To obtain the list of tutorials/vignettes of the CARNIVAL package, user can start with typing the following commmand on R-console:
 
-```R
+```r
 vignette("CARNIVAL-vignette")
 ```
 
-## License
-
-Distributed under the GNU GPLv3 License. See accompanying file [LICENSE.txt](https://github.com/saezlab/CARNIVAL/blob/master/LICENSE.txt) or copy at [http://www.gnu.org/licenses/gpl-3.0.html](http://www.gnu.org/licenses/gpl-3.0.html).
-
 ## References
 
 [Melas et al.](https://pubs.rsc.org/en/content/articlehtml/2015/ib/c4ib00294f):
 
 > Melas IN, Sakellaropoulos T, Iorio F, Alexopoulos L, Loh WY, Lauffenburger DA, Saez-Rodriguez J, Bai JPF. (2015). Identification of drug-specific pathways based on gene expression data: application to drug induced lung injury. *Integrative Biology*, Issue 7, Pages 904-920, https://doi.org/10.1039/C4IB00294F.
 
-[DoRothEA v2 - Garcia-Alonso et al.](https://www.biorxiv.org/content/early/2018/06/03/337915):
+[DoRothEA - Garcia-Alonso et al.](https://github.com/saezlab/dorothea):
 
-> Garcia-Alonso L, Ibrahim MM, Turei D, Saez-Rodriguez J. (2018). Benchmark and integration of resources for the estimation of human transcription factor activities. *bioRXiv*, https://doi.org/10.1101/337915.
+> Garcia-Alonso L, Holland CH, Ibrahim MM, Turei D, Saez-Rodriguez J. (2018). Benchmark and integration of resources for the estimation of human transcription factor activities. *Genome Research* 2019. 29: 1363-1375, https://doi.org/10.1101/gr.240663.118
 
-[PROGENy - Schubert et al.](https://www.nature.com/articles/s41467-017-02391-6):
+[PROGENy - Schubert et al.](https://github.com/saezlab/progeny):
 
 > Schubert M, Klinger B, Klünemann M, Sieber A, Uhlitz F, Sauer S, Garnett MJ, Blüthgen N, Saez-Rodriguez J. (2018). Perturbation-response genes reveal signaling footprints in cancer gene expression. *Nature Communication*, Issue 9, Nr. 20. https://doi.org/10.1038/s41467-017-02391-6.
 
+## Studies where CARNIVAL was used
+
+> Buhl E.M. et al. [Dysregulated mesenchymal PDGFR‐β drives kidney fibrosis](https://www.embopress.org/doi/10.15252/emmm.201911021) _EMBO Mol Med (2020)e11021 doi: 10.15252/emmm.201911021_
+
+> Binenbaum I. et. al. [Bioinformatic framework for analysis of transcription factor changes as the molecular link between replicative cellular senescence signaling pathways and carcinogenesis](https://link.springer.com/content/pdf/10.1007/s10522-020-09866-y.pdf) _Biogerontology doi: 10.1007/s10522-020-09866-y_
 
 ## Acknowledgement
 

_pkgdown.yml

@@ -0,0 +1,13 @@
+destination: docs
+navbar:
+  structure:
+    left: [home, intro, reference, articles, tutorials, news]
+    right: [github, twitter, homepage]
+  components:
+     twitter:
+       icon: "fab fa-twitter fa-lg"
+       href: https://twitter.com/saezlab
+     homepage:
+       icon: "fas fa-university"
+       href: http://www.saezlab.org
+