/DNA_Rchitect

A Shiny App for visualizing genomic data

Primary LanguageJavaScriptMIT LicenseMIT

DNA Rchitect

Welcome to the github repository for DNA Rchitect, a Shiny App for visualizing genomic data.

Start using the web version of this application, or download the source code and run locally.

Please cite if used for publication: DNA Rchitect: an R based visualizer for network analysis of chromatin interaction data. RN Ramirez, K Bedirian, SM Gray, A Diallo. Bioinformatics, 2019. PMID: 31373608 DOI: 10.1093/bioinformatics/btz608.

Table of Contents

Introduction
Installation instructions
Web version
Supported browsers
Header requirements
Tutorial
Errors and Troubleshooting

  1. Incorrect headers
  2. HiC Plotting Error
  3. Grayed out page
  4. Maximum upload size exceeded
  5. Shiny deploy error

Sample data
Adding gene annotation for a new species
References
MIT License

Introduction

DNA Rchitect is a Shiny App for visualizing genomic data (HiC, mRNA, ChIP, ATAC etc) in bed, bedgraph, and bedpe formats. HiC (bedpe format) data is visualized with both bezier curves coupled with network statistics and graphs (using an R port of igraph). Shiny Apps are interactive web applications built with R using the shiny R package. Shiny apps are built with R wrappers for HTML, CSS, and JS to run R code in a web browser through a dynamic and reactive user interface that is powered by an underlying NodeJS engine. These apps can be locally hosted from an R session or hosted in the cloud through a ShinyServer.

Installation instructions

System requirements and instructions for locally installing and running this app through RStudio are provided here. Note that an internet connection is still required to run the locally installed app. Detailed installation instructions are as follows:

  1. You must have RStudio and R installed on your computer. Instructions for installing R and Rstuio can be found here
  2. Download this github repository by clicking on the green Clone or Download button on the right side of the main repository page. The downloaded folder will include the App, a folder with sample data, and a PDF tutorial for using the App. More help on how to clone or download a github repository is provided here.
  3. Navigate to the App folder on your computer and open the file:DNARchitect.R in RStudio
  4. Click 'Run App'
  5. If your data files are >1000 MB, increase the default maximum file size as explained in Maximum upload size exceeded

Web version

A web version of the App is available for use in the cloud. Note that the web version has a hard maximum of 8 GB of RAM per instance. If you exceed 8 GB of RAM during your analysis, the web version of the app will be shutdown by the server. If you are analyzing large data files (especially if the sum of your uploaded file sizes exceeds 4 GB), we recommend installing and running a local version of the app through RStudio, as described in installation instructions. The web version of the App will shutdown after 15 minutes of inactivity and all uploaded data and analysis will be deleted. The web version does not store your data for use at a later time -- you must upload your files with each new session of the web version of the App. Running a locally installed version allows you to keep the App open indefinitely and the maximum RAM per instance is limited only by your computer's hardware. The web version permits a maximum file size of 1000 MB. Pre-loaded HiC and promoter-capture HiC are human (hg19 reference) data, while ATAC-seq and ChIP-seq are mouse (mm10 reference) data types.

Supported browsers

  • Chrome
  • Firefox
  • Safari
  • Microsoft Internet Explorer
  • Microsoft Edge

Header requirements

DNA Rchitect works with both custom headers or no headers at all. In cases where the user is unsure as to what header to use we recommend the following:

File Format Required headers
bed chrom, start, stop
bedpe chrom1, start1, end1, chrom2, start2, end2, score, samplenumber
bedgraph chrom, start, stop, value

Tutorial

There is an interactive tutorial accessible through the help button on the app. Access a PDF version of the tutorial here.

Errors and Troubleshooting

Incorrect headers

If the user's data contains a header they should make sure they check "Does your data contain a header?" on the home screen. Custom headers or files without a header as both allowed.

HiC Plotting Error

Error: Current genomic window cannot be plotted, probably because an anchor crosses the plot boundary. Adjust genomic window coordinates (zoom in or out) and re-submit
The above error indicates that the current genomic window (as defined by the genomic interval to left and right of gene or by the selected coordinates) contains a HiC anchor on the plot boundary. Adjust your window and click Submit Parameters again. Repeat until your window plots properly (ie until your boundary coordinates do not intersect anchors).

Grayed out page

Disconnected from server
Reload
If the page 'grays out' with the above error message, the App has disconnected from the server. This may occur because you left the App idle for >15 minutes (at which time the active instance is shut down), your internet connection was disrupted, or you exceeded the hard maximum of 8 GB of RAM per instance (which causes the web version of the app to die -- see Web version for more details). See the Shiny docs for more information on grey screens.

Maximum upload size exceeded

Maximum upload size exceeded
The above warning will displayed if you attempt to upload a file exceeding 1000 MB. The web version of the app has a maximum individual file size of 1000 MB. To analyze files larger than 1000 MB, install and run a local version of the app on your computer. The default maximum file size is 1000 MB on the locally installed app. To increase the maximum file size, edit the following line of code:
options(shiny.maxRequestSize = 1000*1024^2)
For example, to increase maximum file size to 2000 MB adjust the code as follows:
options(shiny.maxRequestSize = 2000*1024^2)

Shiny Deploy Error

Unable to determine package source for Bioconductor package BiocGenerics: Repository must be specified
The above error may occur while trying to deploy the App to ShinyApps.io or a private ShinyServer. The error seems to occur because the Bioconductor repository is not locally configured. See this discussion and check the repository configurations with getOption("repos"). Run the following code in your R console to configure the Bioconductor respository:
options(repos = BiocInstaller::biocinstallRepos())
If this does not resolve the issue, close the App file and try the following (or some combination):

  1. Delete the rsconnect folder from the source directory for the App
  2. Go to Session... and click Clear Workspace...
  3. Go to Session... and click Restart R...
  4. Open the App file and set working directory to App source file location (you may need to also Run App)
  5. Run in the R console: options(repos = BiocInstaller::biocinstallRepos())
  6. Try to deploy/publish the App

Sample data

Sample bedpe, bed, and bedgraph data sets for testing with this App are available here
The web version of the application also contains sample data that can be used.
You can download this entire github repository (including the sample_data folder) by clicking on the green Clone or Download button at the top of this page.

Adding gene annotation for a new species

Use the speciesTool to generate the required files for adding gene annotation for a new species to the DNARchitect app. The files for each species must be stored using the following convention at the google storage bucket:
https://storage.googleapis.com/gencode_ch_data/speciesName/fileName
For example, for the Gencode.chr1.txt gene annotation file for the mouse chr1, the file would be stored at:
https://storage.googleapis.com/gencode_ch_data/mouse/Gencode.chr1.txt
There are two types of files that must be included in the new species storage.googleapis.com bucket:

  1. The gene annotation files for each chromosome:
    Example: https://storage.googleapis.com/gencode_ch_data/mouse/Gencode.chr1.txt
  2. The searchNames file for the species:
    Example: https://storage.googleapis.com/gencode_ch_data/mouse/mouse_searchNames.txt
    The searchNames file is used by the App to generate options when typing a gene name in the plotting panel for use in the searchByGene function.

Changes required to code when adding new species

The code must be changed in 3 places to accomodate a new species.

  1. geneNames: Each new species requires its own column in the geneNames object. Create a new geneNames$yourNewSpecies and update the URL so that the pulled file comes from the correct directory (ie: https://storage.googleapis.com/gencode_ch_data/yourNewSpecies/yourNewSpecies_searchNames.txt, where yourNewSpecies must be updated). Note that the yourNewSpecies must be the same name used in input$genome
  2. output$chromNumberUI: Each new species requires its own case in the switch statement to render UI for selecting the chromosome to visualize. Follow the existing code and add your new species.
  3. output$searchNamesList: Each new species requires its own case in the switch statement to render UI for visualizing by gene. Follow the exisintg code and add your new species.

The follow species are currently supported by the App

  1. mouse: mm9, mm10
  2. human: Hg19, Hg38
  3. drosophila_melanogaster Release 6

References

This application utilizes the following packages and libraries:
IntroJS
shiny
jsonlite
Sushi
DT
RColorBrewer
visnetwork
igraph
BioNet

Authors

Karni Bedirian - Department of Immunology, Harvard Medical School
Ricardo Ramirez - Department of Immunology, Harvard Medical School
Simon Matthew Gray - Department of Immunology, Harvard Medical School
Alos Diallo - Department of Immunology, Harvard Medical School

Copyright © 2018 the President and Fellows of Harvard College.

Blavatnikimmunology Immgen

MIT License