CRI iAtlas-App

The CRI iAtlas app is an interactive web portal that provides multiple analysis modules to visualize and explore immune response characterizations across cancer types. The app is hosted on shinyapps.io at https://isb-cgc.shinyapps.io/iatlas-app/ and can also be accessed via the main CRI iAtlas page at http://www.cri-iatlas.org/.

The portal is built entirely in R and Shiny using the RStudio development environment. Layout and interactivity within the portal are achieved by heavy use of the following packages:

• shinydashboard
• plotly
• crosstalk

Install

Requirements

• R: https://www.r-project.org/ - v4.2+

• RStudio: https://rstudio.com/products/rstudio/download

MacOS Install instructions

Install package manager:

• HomeBrew (the instructions below are for HomeBrew)
• or MacPorts, which is very similar to use for installing packages

Then in the terminal, run:

• xcode-select --install
• brew install cairo
• brew install R or install R .pkg from https://cran.r-project.org/bin/macosx/
• download and install RStudio: https://rstudio.com/products/rstudio/download

Initialize R Packages and run App

To run the app locally:

1. Clone this repository

2. Open iatlas-app.Rproj

3. Follow the instructions in your console

4. Restart R (ctrl+shift+F10)

5. Run the command shiny::runApp() in your console

Branches: Staging & Master

We recommend the following workflow. When you are starting a new feature or project:

Create a Working Branch

Checkout and get the latest from staging:

git checkout staging
git pull

Create your new branch:

git checkout -b feature/my-new-feature
# 'git checkout -b' is the same as:
# > git branch feature/my-new-feature
# > git checkout feature/my-new-feature

Do your work and periodically commit your changes:

git add .
git commit -m "my message"
git push

Keep up to date with changes on staging by others:

git checkout staging
git pull
git checkout feature/my-new-feature
git merge staging

Testing the pull request.

When you are ready to deploy your code to staging, you'll need to create a pull request. First, push your branch to Github:

git push

Then go to the repository on Github, go to your branch, and create a pull-request into the staging branch.

• https://github.com/CRI-iAtlas/iatlas-app

GitLab CI/CD will will run the test-suite on the pull-request, and automatically deploy your changes to the testing server. Note: It can take 10-15 minutes to update.

If the tests pass and the app is able to be deployed then it will be reviewed and deployed to staging.

• Testing App: https://isb-cgc.shinyapps.io/iatlas-testing
• Staging App: https://isb-cgc.shinyapps.io/iatlas-staging

Installing and Upgrading Packages

This project uses renv to manage packages. The definitive list of required packages and versions is stored in the renv.lock file.

When adding any new dependencies to the application, they may be added using (where "useful_package" is the name of the package to add):

# install a package
renv::install("useful_package")

# update the renv.lock file
renv::snapshot()

Git works well with renv. Once you validate the package should be kept, git add renv.lock to the repo and everyone else will automatically install it when they git-pull and re-open their R session or run renv::restore().

If you decide you don't want to include the package, just git checkout renv.lock to reset your dependencies to the point before you made changes.

To remove an installed package, run (where "useful_package" is the name of the package to remove):

renv::remove("useful_package")
renv::snapshot()

And git-commit it once you are sure you want to keep the changes.

Upgrading Packages

You can use renv::upgrade("package-name") to upgrade a package, but it'll always update to the very latest uniless you manually tell it otherwise.

Installing Packages and RsConnect

This application is deployed using rsconnect::deployApp(). As of the current version (0.8.16-9000), rsconnect does not support using the renv.lock file to determin which packages to deploy. Instead, it uses its own till (rsconnect::appDependencies) to detect your app's dependencies from the R source files and the DESCRIPTION file. The good news is it will generally get the correct version, since it'll use the current version you have installed and renv manages that tightly. The bad news is sometimes it won't detect you need a package. Here's how you solve that problem:

• If a package is missing after you push to the staging branch and check the staging server, add that the package name to the Imports: section of the DESCRIPTION file.

Deployment

Only deploy to branch specific apps, not to testing, staging or the main app. The first time you deploy, go through the Deployment-Setup instructions. Afterwards, you can deploy with one line.

Deployment Setup (First-Time-Only)

You'll need to set up your credentials for shinyapps.io. You can get your codes from:

• https://www.shinyapps.io/admin/#/tokens

Paste and evaluate your tokens in the RStudio console. They look like this:

# shinyapps.io example credentials
rsconnect::setAccountInfo(
  name='isb-cgc',
  token='xxx',
  secret='yyy'
)

Deploy

rsconnect::deployApp(appName = "iatlas-branchxxx-app")

Methods

While many of the results presented in tables and plots are taken directly from Immune Response Working Group (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:

Correlation — Spearman's rank-order correlation

stats::cor(x, y, method = "spearman", use = "pairwise.complete.obs")

Concordance Index (CI)

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:

concordanceIndex::concordanceIndex(predictions, observations)

... where predictions and observations are numerical vectors of the same length.

Common Errors

When running shiny::runApp()for the first time in a session, you may run into the following error:

Warning in file(con, "r") :
  cannot open file '/footer.html': No such file or directory
Warning: Error in file: cannot open the connection
  75: file
  74: readLines
  73: shiny::includeHTML

Can be resolved by running devtools::load_all(".") and then shiny::runApp().