Merge pull request #198 from CRI-iAtlas/develop

1.3

CONTRIBUTING.md

@@ -0,0 +1,96 @@
+# Contributing to CRI-iAtlas
+
+Welcome, and thanks for your interest in contributing to the Cancer Research Institute (CRI) iAtlas!
+
+If you would like to contribute code changes please follow these steps:
+
+1. Search the issues list in the repo. Consider opening an issue related to the suggested feature.
+2. Create a personal fork and commit new code development to personal branches in that fork.
+3. Propose changes via pull request of personal branches.
+
+
+In case the intended contribution consists of a new module, please refer to the following steps to include shortcuts of new modules in the Explore Section of CRI-iAtlas.
+
+## Procedures for Starting a New iAtlas Module
+
+Procedures to include a new module in the initial page of the Explore Section of the current version of the portal CRI-iAtlas (February 2020). 
+
+This procedure lists the files that need to be updated or started, as well as the functions to call, when applicable. There is no reference to a specific line to update, as this can change over time. It is recommended to look for the section of the code with the settings of current modules - for example, in step 4.1., at the `server.R` file, look for `callModule` code for the existing modules, and include new code in this section.
+
+### Steps
+Can be carried out in another order but all pieces need to be in place for full functionality.
+
+#### 1. Create file with new module and save it in the modules folder : `modules/myshinynewmodule.R`.
+
+#### 2. Edit `configuration.yaml`.
+
+Add the new module name in the `module_files` list: `modules/myshinynewmodule.R`
+
+IMPORTANT: if you create a script with functions, save it in the `functions` folder and add the file names in the `function_files` list in `configuration.yaml`
+
+#### 3. In your module script `myshinynewmodule.R`, define the name of the UI and server function. 
+
+In this example, the names will be: 
+
+```
+newmodule_UI <-function(id){}
+
+newmodule <- function(input, output, session){}
+```
+Please note that this function can take more arguments.
+
+#### 4. Edit top level `server.R`.
+
+Include a `callModule` for your module server function:
+
+```
+callModule(newmodule, moduleN, …)
+```
+
+Give module a number such as `moduleN`. Check if moduleN is unique.
+
+Add the following in the `observeEvent` section:
+```
+    observeEvent(input$link_to_moduleN, {
+      shinydashboard::updateTabItems(session, "explorertabs", "new_module")
+    })
+```
+Observe that in 4.2., "new_module” is distinct from newmodule defined in #3.
+
+#### 5. Now it is time to include access to your new module in the initial page of the portal. To do so, edit `pages/explorepage.R`.
+
+Add the following in the `tabItem` section found near bottom of this script:
+
+```
+tabItem(
+        tabName = "new_module",
+        newmodule_UI("moduleN")
+      )
+```
+
+Add link to the left navigation bar (into code near the top of this script):
+
+```
+ menuSubItem(
+                 "Test Module", #text to display
+                 tabName = "new_module",
+                 icon = icon("cog") #can be different for other sections
+      )
+```
+
+Edit main section to include the new module in the initial Explore page:
+```
+fluidRow(
+            imgLinkBox(
+              width = 6,
+              title = "New Module",
+              linkId = "link_to_moduleN",
+              imgSrc = "images/myimage.png", # if including images, read next step.
+              boxText = "Short description of the module",
+              linkText = "Open Module"
+)
+```
+You may have to adjust layout after step 5.3.
+
+Include a png if you like. Save the image at `www/images/myimage.png`.
+

README.md

@@ -22,15 +22,20 @@ The portal is built entirely in **R** and **Shiny** using the **RStudio** develo
 
 ### MacOS Install instructions
 
-Install brew: https://brew.sh/
+- Download and install gfortran: https://github.com/fxcoudert/gfortran-for-macOS/releases
+or https://cran.r-project.org/bin/macosx/tools/
 
-Then:
+- Download and install R-3.6.2.pkg: https://cran.r-project.org/bin/macosx/
 
-- brew install R
-- brew install cairo
-- download and install RStudio: https://rstudio.com/products/rstudio/download
+- Download and install X11 via XQuartz: https://www.xquartz.org/
 
-### Initialize R Packages, Database and run App
+- Install cairo via Homebrew: `brew install cairo` (https://formulae.brew.sh/formula/cairo ; requires brew: https://brew.sh/ )
+
+- Download and install RStudio: https://rstudio.com/products/rstudio/download
+
+Please see the section "[Common Installation Errors (MacOS)](#Common-Installation-Errors-(MacOS))" at the end of this README for common issues encountered during installation. 
+
+### Initialize R Packages and run App
 
 To run the app locally:
 
@@ -44,16 +49,19 @@ To run the app locally:
    renv::restore()
    ```
 
-   This may take some time to complete - get something nice to drink :)
+   This may take some time to complete - walk away from your computer, rest your eyes, and catch up on those stretching exercises you are meant to be doing :)
 
 1. Start the app by running:
 
    ```R
    shiny::runApp()
    ```
 
+
 ## Development
 
+Please consult the [Contributing Guide](https://github.com/CRI-iAtlas/shiny-iatlas/blob/develop/CONTRIBUTING.md) for pointers on how to get started on a new module.
+
 When adding any new dependencies to the application, they may be added using (where "useful_package" is the name of the package to add):
 
 ```R
@@ -70,7 +78,7 @@ renv::snapshot()
 
 This will ensure the new package is added to the renv.lock file.
 
-To remove an installed package, run (where "useful_package" is the name of the package to remove):
+To remove an installed package, run (where "no_longer_useful_package" is the name of the package to remove):
 
 ```R
 renv::remove("no_longer_useful_package")
@@ -80,7 +88,7 @@ For more on package management with renv, please see [https://rstudio.github.io/
 
 ## Deployment
 
-The first time you deploy, go through the Deployment-Setup instructions below. Afterwards, you can just deploy as needed.
+The first time you deploy, go through the Deployment Setup instructions below. Afterwards, you can just deploy as per sub-section Deploy.
 
 ### Deployment Setup (First-Time-Only)
 
@@ -108,8 +116,12 @@ rsconnect::deployApp()
 
 ## Data
 
-Input data for the Shiny-iAtlas portal were accessed from multiple remote sources, including **Synapse**, the **ISB Cancer Genomics Cloud**, and **Google Drive**. For convenience, we have created locally cached versions of dataframe objects as **`feather`** files in the `data` folder:
+Input data for the Shiny-iAtlas portal are to a large extent obtained from the [Immune Landscape of Cancer](https://www.cell.com/immunity/abstract/S1074-7613(18)30121-3) study. These data can be accessed via the [Immunity journal publication page ](https://www.cell.com/immunity/abstract/S1074-7613(18)30121-3), the [manuscript page at NCI's Genomic Data Commons](https://gdc.cancer.gov/about-data/publications/panimmune) and on [iAtlas pages on Synapse](https://www.synapse.org/#!Synapse:syn21247064). This includes the main feature matrix and various feature and group annotations.  Additionally some input files of results were pre-computed specifically for use by this app.
+
+Some of the key input data can be found as dataframe objects in **`feather`** files within the `data` folder:
 
+- `cell_image_id_annotations.feather`
+- `driver_mutations.feather`
 - `feature_df.feather`
 - `feature_method_df.feather`
 - `fmx_df.feather`
@@ -122,21 +134,59 @@ Input data for the Shiny-iAtlas portal were accessed from multiple remote source
 
 ## Methods
 
-While many of the results presented in tables and plots are taken directly from IRWG data (including the main **feature matrix** and various feature and group annotations), we compute some values internally. Unless otherwise noted, the following methods/tools were used to compute summary statistics:
+Methods employed by the app are described in [Immune Landscape of Cancer](https://www.cell.com/immunity/abstract/S1074-7613(18)30121-3) study and can also be found in Methods descriptions displayed in the app (for example as seen in Data Description module).
+
+### Concordance Index (CI)
 
-### Correlation — Spearman's rank-order correlation
+Concordance indexes for survival endpoints with respect to different immune readouts are computed using a custom package developed by Tai-Hsien Ou Yang. The **[concordanceIndex](https://github.com/th86/concordanceIndex)** package includes a single eponymous function that can be used as follows:
 
 ```R
-stats::cor(x, y, method = "spearman", use = "pairwise.complete.obs")
+concordanceIndex::concordanceIndex(predictions, observations)
 ```
 
-### Concordance Index (CI)
+where `predictions` and `observations` are numerical vectors of identical length.
+
+### Immune Subtype Classifier
+
+The iAtlas Immune Subtype Classifier tool uses the **[ImmuneSubtypeClassifier](https://github.com/CRI-iAtlas/ImmuneSubtypeClassifier)** R package, developed by David L. Gibbs, for classification of immune subtypes, in cancer, using gene expression data.
 
-Concordance indexes for survival endpoints with respect to different immune readouts were computed using a custom package developed by Tai-Hsien Ou Yang at Columbia University. The **concordanceIndex** package includes a single synonymous function that can be used as follows:
+### Common Installation Errors (MacOS)
 
+When running `renv::restore()`, you may run into the following errors:
+
+#### Error when installing `Cairo`:
 ```R
-concordanceIndex::concordanceIndex(predictions, observations)
+checking for pkg-config... no
+configure: CAIRO_LIBS is unset, attempting to guess it.
+configure: CAIRO_CFLAGS=-I/usr/local/include/cairo
+checking if R was compiled with the RConn patch... no
+checking cairo.h usability... yes
+checking cairo.h presence... yes
+checking for cairo.h... yes
+checking for PNG support in Cairo... yes
+checking for ATS font support in Cairo... no
+configure: CAIRO_LIBS=-L/usr/local/lib -lcairo
+checking for library containing deflate... -lz
+checking whether Cairo programs can be compiled... yes
+checking whether cairo_image_surface_get_format is declared... no
+checking for FreeType support in cairo... yes
+checking whether FreeType needs additional flags... yes
+checking whether fontconfig/freetype2 location can be guessed... possibly
+checking whether additional flags work... no
+configure: error: Cannot use cairo-ft backend, although cairo claims it is working. Please check your caito installation and/or update cairo if necessary or set CAIRO_CFLAGS/CAIRO_LIBS accordingly.
+ERROR: configuration failed for package ‘Cairo’
+* removing ‘/Users/ychae/Documents/iAtlas/shiny-iatlas/renv/staging/1/Cairo’
+Error: install of package 'Cairo' failed
 ```
+ There are several possible reasons for this:
+- Make sure that you have XQuartz installed. If you've recently updated your MacOS, you will need to reinstall XQuartz.
+- You might be missing `pkg-config`. You can install this by opening a Terminal window and running `brew install pkg-config`.
 
-... where `predictions` and `observations` are numerical vectors of the same length.
+#### Error when installing `RPostgres [1.1.1]:
+```R
+Installing RPostgres [1.1.1] ...
+	FAILED
+Error installing package 'RPostgres':
+```
+Can be resolved by opening a Terminal window and running `brew install libpq`. You may also need to set `PKG_CONFIG_PATH="/usr/local/opt/libpq/lib/pkgconfig"`.
 

configuration.yaml

@@ -13,6 +13,9 @@ module_files:
   - "modules/subtypeclassifiermodule.R"
   - "modules/submodules.R"
   - "modules/distribution_plot_module.R"
+  - "modules/cytokinenetwork.R"
+  - "modules/cellimagemodule.R"
+  - "modules/cnvmodule.R"
 
 function_files:
   - "functions/load_data.R"
@@ -32,6 +35,8 @@ function_files:
   - "functions/tablef_fun.R"
   - "functions/imageplot.R"
   - "functions/event_data_utils.R"
+  - "functions/extracellnet_utils.R"
+  - "functions/cellimage_utils.R"
 
 page_files:
   - "pages/aboutpage.R"

data/MethodsText/Methods_AbundantConcordantNetwork.txt

@@ -0,0 +1,12 @@
+**Title:** The Cell-to-Cell Communication Network
+
+**Descriptions:** A network of documented ligand-receptor, cell-receptor, and cell-ligand pairs (Ramilowski et al., 2015 - https://www.nature.com/articles/ncomms8866) was retrieved from the FANTOM5 resource at (http://fantom.gsc.riken.jp/5/suppl/Ramilowski_et_al_2015/).
+
+CIBERSORT cell types are more granular than the immune cells in FANTOM5 and were therefore summed to yield estimates for FANTOM5 immune cell abundances, as defined above in ‘‘Immune cellular fraction estimates’’ Aggregate 2. For example, FANTOM5 CD19 B cell estimates are the combination of CIBERSORT naive and memory B cells. This network was augmented with additional known interactions of immumodulators, and only ligand-receptor edges that contained at least one cell or one immune modulator were retained, yielding a ‘scaffold’ of possible interactions.
+
+From the scaffold of possible interactions, interactions were identified that could be playing a role within the TME in each subtype or group as follows. Cellular fractions were binned into tertiles (low, medium, high), as were gene expression values for ligands and receptors, yielding ternary values for all ‘nodes’ in the network. The binning was performed over all TCGA samples. In subsequent processing, nodes and edges were treated uniformly in processing, without regard to type (cell,ligand,receptor). From the scaffold, interactions predicted to take place in the TME were identified first by a criterion for the nodes to be included (‘present’ in the network), then by a criterion for inclusion of edges, potential interactions. Nodes selection is based on the abundance threshold. For instance, for an abundance threshold of 66%, the node is entered into the subtype-network if at least 66% of samples within a subtype map to mid or high value bins. An edge present in the scaffold network between any two nodes is then evaluated for inclusion. A contingency table is populated for the ternary values of the two nodes, over all samples in the subtype, and a concordance versus discordance ratio (‘‘concordance score’’) is calculated for the edge in terms of the values of ((high,high)+ (low,low))/(1+(low,high)+(high,low)). Edges are included in the network based on their concordance value. A concordance threshold of 2, for example, selects edges that have both nodes simultaneously highly or lowly expressed (concordant) at least twice as frequent than samples with one node highly expressed and the other lowly expressed (discordant). On the other hand, an edge with a concordance threshold of 0.5 is considered discordant, ie, the frequency of samples with one node highly expressed and the other lowly expressed (discordant) is twice than samples with both nodes simultaneously highly or lowly expressed (concordant). 
+
+
+[Reference List](https://www.cell.com/immunity/references/S1074-7613\(18\)30121-3)
+
+**Contributors:** David L. Gibbs, Vesteinn Thorsson, Ilya Shmulevich

data/MethodsText/Methods_CellImage.txt

@@ -0,0 +1,11 @@
+**Title:** Cell, ligand and receptor abundance
+
+**Description:** To generate the cellular image for display, the figure was drawn in Adobe Illustrator, exported to SVG and transformed into “Cairo” graphic SVG format for import into R as a grid object (using the R package grImport2).  The proteins and cells shown in the image were then made available for display as a node-edge network.  In the node-edge network directionality of network edges follows that of the related iAtlas module devoted to showing extracellular networks of the tumor microenvironment.
+
+To yield values for display, the gene expression values for each protein shown were first binned into  tertiles (low, medium, high). The binning was performed over all TCGA samples.  The ‘abundance’ was computed as the fraction of samples within a the selected subtype that map to the mid and high value bins.  The abundance can thus range from 0 to 1.  Identical binning was performed to yield cell abundance within the subtype.
+
+Some details of the value estimation prior to binning are as follows. Immune cell abundance was estimated with CIBERSORT. The T Cell estimate corresponds to the CD8  T Cell estimate from CIBERSORT; Macrophage level is given by the sum of M0, M1, M2 macrophages according to CIBERSORT;  Dendritic cells are a combination of CIBERSORT resting and activated Dendritic cells.   The Tumor Cells estimate are estimated by TCGA tumor purity.  The  T cell receptor (TCR) value was approximated by the T Cell estimate.  MHC Class I values (MHC) were set to the expression of the single HLA gene HLA-A, and MHC Class II (MHC-II) approximated by the expression of HLA-DPA1. In the network diagram, the TCR and peptide-mediated binding interactions are not shown. ICOSLG codes for the protein ICOSL.
+
+**Acknowledgment:** The iAtlas team is grateful to Allison Kudla of the Institute for Systems Biology for producing the cell image file and for being patient with multiple requests for modifications.  The figure was adapted from *CTLA-4 and PD-1/PD-L1 blockade: new immunotherapeutic modalities with durable clinical benefit in melanoma patients* PA Ott, FS Hodi, and C Robert;  Clin Cancer Res. 2013 Oct 1;19(19):5300-9; doi: 10.1158/1078-0432.CCR-13-0143.
+
+**Contributors:** Vesteinn Thorsson, Carolina Heimann, Allison Kudla, David L. Gibbs, Ilya Shmulevich  

data/cell_image_object_ids.txt

@@ -0,0 +1,44 @@
+T_cell
+T_cell_nucleus
+Dendritic_cell
+Dendritic_cell_nucleus
+Tissue_macrophage
+Tissue_macrophage_nucleus
+Tumor
+Tumor_nucleus
+ICOS
+PD-L2
+PD-L2
+PD-L1
+PD-L1
+PD-L1
+CD28
+CTLA-4
+CD40L
+CD40
+ICOSL
+CD86
+CD80
+PD-1
+PD-1
+PD-1
+PD-1
+PD-1
+Four.1BB
+Four.1BBL
+OX40L
+OX40
+GITRL
+GITR
+TCR
+TCR
+TCR
+MHC
+MHC
+MHC
+MHC-II
+LAG-3
+TIM-3
+Galectin_9
+TIGIT
+CD155

data/javascript/extracellular_network_styles.js

@@ -0,0 +1,57 @@
+[ {
+
+    "selector" : "node",
+    "css" : {
+      "color" : "rgb(0,0,0)",
+      "width" : 75.0,
+      "background-opacity" : 1.0,
+      "shape" : "roundrectangle",
+      "border-opacity" : 1.0,
+      "border-color" : "rgb(204,204,204)",
+      "height" : 35.0,
+      "text-opacity" : 1.0,
+      "font-family" : "Helvetica",
+      "font-weight" : "normal",
+      "text-valign" : "center",
+      "text-halign" : "center",
+      "font-size" : 12,
+      "border-width" : 0.0,
+      "background-color" : "rgb(137,208,245)",
+      "content" : "data(FriendlyName)"
+    }
+  }, {
+    "selector" : "node[Type = 'Ligand']",
+    "css" : {
+      "background-color" : "rgb(255,255,204)"
+    }
+  }, {
+    "selector" : "node[Type = 'Receptor']",
+    "css" : {
+      "background-color" : "rgb(255,204,204)"
+    }
+  }, {
+    "selector" : "node[Type = 'Cell']",
+    "css" : {
+      "background-color" : "rgb(204,255,204)"
+    }
+  }, {
+    "selector" : "node:selected",
+    "css" : {
+      "background-color" : "rgb(255,255,0)"
+    }
+  }, {
+    "selector" : "edge",
+    "css" : {
+      "line-color": "black",
+        "target-arrow-shape": "triangle",
+        "target-arrow-color": "black",
+        "width": 0.5,
+        "curve-style": "bezier"
+    }
+  }, {
+    "selector" : "edge:selected",
+    "css" : {
+      "line-color" : "rgb(255,0,0)"
+    }
+
+} ]