You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Welcome, and thanks for your interest in contributing to the Cancer Research Institute (CRI) iAtlas!
4
+
5
+
If you would like to contribute code changes please follow these steps:
6
+
7
+
1. Search the issues list in the repo. Consider opening an issue related to the suggested feature.
8
+
2. Create a personal fork and commit new code development to personal branches in that fork.
9
+
3. Propose changes via pull request of personal branches.
10
+
11
+
12
+
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.
13
+
14
+
## Procedures for Starting a New iAtlas Module
15
+
16
+
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).
17
+
18
+
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.
19
+
20
+
### Steps
21
+
Can be carried out in another order but all pieces need to be in place for full functionality.
22
+
23
+
#### 1. Create file with new module and save it in the modules folder : `modules/myshinynewmodule.R`.
24
+
25
+
#### 2. Edit `configuration.yaml`.
26
+
27
+
Add the new module name in the `module_files` list: `modules/myshinynewmodule.R`
28
+
29
+
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`
30
+
31
+
#### 3. In your module script `myshinynewmodule.R`, define the name of the UI and server function.
32
+
33
+
In this example, the names will be:
34
+
35
+
```
36
+
newmodule_UI <-function(id){}
37
+
38
+
newmodule <- function(input, output, session){}
39
+
```
40
+
Please note that this function can take more arguments.
41
+
42
+
#### 4. Edit top level `server.R`.
43
+
44
+
Include a `callModule` for your module server function:
45
+
46
+
```
47
+
callModule(newmodule, moduleN, …)
48
+
```
49
+
50
+
Give module a number such as `moduleN`. Check if moduleN is unique.
- Download and install RStudio: https://rstudio.com/products/rstudio/download
35
+
36
+
Please see the section "[Common Installation Errors (MacOS)](#Common-Installation-Errors-(MacOS))" at the end of this README for common issues encountered during installation.
37
+
38
+
### Initialize R Packages and run App
34
39
35
40
To run the app locally:
36
41
@@ -44,16 +49,19 @@ To run the app locally:
44
49
renv::restore()
45
50
```
46
51
47
-
This may take some time to complete - get something nice to drink :)
52
+
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 :)
48
53
49
54
1. Start the app by running:
50
55
51
56
```R
52
57
shiny::runApp()
53
58
```
54
59
60
+
55
61
## Development
56
62
63
+
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.
64
+
57
65
When adding any new dependencies to the application, they may be added using (where "useful_package" is the name of the package to add):
58
66
59
67
```R
@@ -70,7 +78,7 @@ renv::snapshot()
70
78
71
79
This will ensure the new package is added to the renv.lock file.
72
80
73
-
To remove an installed package, run (where "useful_package" is the name of the package to remove):
81
+
To remove an installed package, run (where "no_longer_useful_package" is the name of the package to remove):
74
82
75
83
```R
76
84
renv::remove("no_longer_useful_package")
@@ -80,7 +88,7 @@ For more on package management with renv, please see [https://rstudio.github.io/
80
88
81
89
## Deployment
82
90
83
-
The first time you deploy, go through the Deployment-Setup instructions below. Afterwards, you can just deploy as needed.
91
+
The first time you deploy, go through the DeploymentSetup instructions below. Afterwards, you can just deploy as per sub-section Deploy.
84
92
85
93
### Deployment Setup (First-Time-Only)
86
94
@@ -108,8 +116,12 @@ rsconnect::deployApp()
108
116
109
117
## Data
110
118
111
-
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:
119
+
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.
120
+
121
+
Some of the key input data can be found as dataframe objects in **`feather`** files within the `data` folder:
112
122
123
+
-`cell_image_id_annotations.feather`
124
+
-`driver_mutations.feather`
113
125
-`feature_df.feather`
114
126
-`feature_method_df.feather`
115
127
-`fmx_df.feather`
@@ -122,21 +134,59 @@ Input data for the Shiny-iAtlas portal were accessed from multiple remote source
122
134
123
135
## Methods
124
136
125
-
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:
137
+
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 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:
128
142
129
143
```R
130
-
stats::cor(x, y, method="spearman", use="pairwise.complete.obs")
where `predictions` and `observations` are numerical vectors of identical length.
148
+
149
+
### Immune Subtype Classifier
150
+
151
+
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.
134
152
135
-
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:
153
+
### Common Installation Errors (MacOS)
136
154
155
+
When running `renv::restore()`, you may run into the following errors:
- Make sure that you have XQuartz installed. If you've recently updated your MacOS, you will need to reinstall XQuartz.
183
+
- You might be missing `pkg-config`. You can install this by opening a Terminal window and running `brew install pkg-config`.
140
184
141
-
... where `predictions` and `observations` are numerical vectors of the same length.
185
+
#### Error when installing `RPostgres [1.1.1]:
186
+
```R
187
+
InstallingRPostgres [1.1.1] ...
188
+
FAILED
189
+
Errorinstallingpackage'RPostgres':
190
+
```
191
+
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"`.
**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/).
4
+
5
+
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.
6
+
7
+
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).
**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.
4
+
5
+
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.
6
+
7
+
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.
8
+
9
+
**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.
10
+
11
+
**Contributors:** Vesteinn Thorsson, Carolina Heimann, Allison Kudla, David L. Gibbs, Ilya Shmulevich
0 commit comments