BEAVR

A Browser-based tool for the Exploration And Visualization of RNAseq data

BEAVR is a graphical tool to automate analysis and exploration of small and large RNAseq datasets using DESeq2.

The easiest way to get started with BEAVR is to use our Docker container!

Enter: docker run -ti -p 3838:3838 pirunthan/beavr:latest

Then open your browser and enter localhost:3838 or 127.0.0.1:3838 in the address bar to start using BEAVR.

Check the Docker section for more detailed instructions for using Docker on Windows, Mac OS, and Linux.

Check the Troubleshooting section for some common issues and solutions.

Please note: results from the latest version of BEAVR (1.0.10) may differ slightly from those of the initial publication version (version 1.0.8). This is not due to changes in BEAVR itself, but a result of updates to dependencies required by BEAVR, such as the DESeq2 package or packages used to generate plots.

Another note before you continute: BEAVR requires raw read counts, such as those generated by the STAR aligner. Why isn't this step included in BEAVR? Well, that was part of the initial goal and an early version of BEAVR did include this - but it meant end users required a very powerful computer BEAVR because the alignment process is very computatioanlly demanding. Ultimately it was decided to remove the alignment step from BEAVR.

By removing the alignment step, BEAVR becomes a very portable tool that can run on the average computer.

If you are not comfortable using STAR or Linux shell commands, I have an easy to follow tutorial which you can follow to quickly create a Google cloud virtual machine to run STAR aligner.

But keep an eye out - a standalone, graphical frontend for alignment is on the way soon!

Installation & Requirements

We provide three ways to install and use BEAVR. They vary in ease and speed to get BEAVR running on your computer: 1. Use a Docker container - the easiest and fastest method! 2. Setup a new R environment with the automated installer - for those who don't want to install Docker 3. Run in your existing R installation - for those who already have R installed

Use the Docker container

The easiet and quickest way to install and use BEAVR - especially for those who have no R, programming, or command line experence - is to use our Docker container.

For those who are familiar with Docker, you can pull the latest version of BEAVR using docker pull pirunthan/beavr:latest and you can run the container using docker run -ti -p 3838:3838 pirunthan/beavr:latest.

For those who are new to Docker, follow these instructions to get started:

Docker on Windows

Install Docker from the Docker website using their setup wizard:
- Docker Desktop for Windows
Download and extract the BEAVR-Docker setup package for Windows:
- Windows
Run (pull) our Docker container:
- Double-click Run-BEAVR.bat in the BEAVR-Docker setup package you downloaded above (you may need to right-click and run as administrator)
  
  Or
You can also just enter this command at in a command prompt window or in Windows Power Shell:
```
docker run -ti -p 3838:3838 pirunthan/beavr:latest
```
Open your browser and enter localhost:3838 in the address bar to use BEAVR.

Once the Docker container is downloaded to your computer, you can also access it from the Docker Dashboard as shown below (to get to the Dashboard, right-click the Docker whale icon in the system tray in the bottom right and then click Dashboard):

You can use this interface to start, stop, or open a browser to localhost:3838 (circled in red) without using Run-BEAVR.bat or Run-BEAVR.sh executable scripts as explained in step 3 above.

However, keep in mind that this only runs your current locally downloaded version of BEAVR. To get the most up-to-date version, follow step 3 to update your local copy.

Docker on Mac OS

Install Docker from the Docker website using their setup wizard:
- Docker Desktop for Mac OS
To download and run the BEAVR container you can either copy and paste the following command in Terminal:
```
docker run -ti -p 3838:3838 pirunthan/beavr:latest
```
Or

Do the following steps instead to use our automated script: (You only have to download this once and do steps 1-3 once)

Download and extract the BEAVR-Docker setup package for Mac OS:
- Mac OS
Before you can execute the setup script, you will likely have to allow execute permissions or Mac OS will give you an error. You can do this as follows by copying and pasting this command into Terminal:
```
chmod +x ~/Downloads/BEAVR-Docker-Mac/Run-BEAVR.command
```
Where ~/Downloads/ is the path where you extracted the BEAVR-Docker-Mac folder from step 3 (usually your Downloads folder or ~/Desktop/ if you moved it to your desktop.)
If you double-click Run-BEAVR.command, you will likely get another error because you didn't download it from the App store.

To get around this, right-click the file and go to Open and then click Open in the popup box:

This will start BEAVR in the Docker container.

Open your browser and enter localhost:3838 in the address bar to use BEAVR.

Once the Docker container is downloaded to your computer, you can also access it from the Docker Dashboard as shown below (to get to the Dashboard, click the Docker whale icon in system tray in the top right of your screen and then click Dashboard):

You can use this interface to start, stop, or open a browser to localhost:3838 (circled in red) without using Run-BEAVR.bat or Run-BEAVR.sh executable scripts as explained in step 3 above.

However, keep in mind that this only runs your current locally downloaded version of BEAVR. To get the most up-to-date version, follow step 2 or step 6 to update your local copy.

Docker on Linux (Ubuntu)

Download and extract the BEAVR Docker setup package for Linux:
- Linux
Install Docker for your operating system: Use our automated installer in the BEAVR-Docker-Linux package you extracted above (named Docker-setup-ubuntu.sh). You will need to open Terminal and enter this command to execute it:
```
bash Docker-setup-ubuntu.sh
```
Note, if you get permission errors, you may need to give the script executable permission
```
chmod +x Docker-setup-ubuntu.sh
```
Run (pull) our Docker container: Enter bash Run-BEAVR.sh in Terminal.

Note, if you get permission errors, you may need to give the script executable permission
```
chmod +x Run-BEAVR.sh
```
Or

You can also just enter this command:
```
docker run -ti -p 3838:3838 pirunthan/beavr:latest
```
Open your browser and enter localhost:3838 in the address bar to use BEAVR.

Setup a new R environment with the automated installer

If you prefer not to install Docker and you do not already have R installed on your computer, you can follow these steps to easily install and configure R for BEAVR.

A new R environment in Windows

Download and install R for Windows using the installation wizard:
- Download the latest version of R here
Download and install RTools for Windows using the installation wizard:
- Download the latest version of RTools here
Download and extract the BEAVR setup files from here
Look in the "Setup" folder to find the automated installer for Windows:
- Right click on the file named Configure-BEAVR-Windows.bat and click run as administrator (agree to any warnings/prompts to run it)
This will open a command prompt window.
You will be prompted to "enter the path to your Rscript.exe:"
- Rscript.exe is located in a folder named bin within the path where you installed R (in step 1).
- E.g. C:\Program Files\R\R-VERSION\bin\Rscript.exe, where VERSION is the version of R you have installed.
- For example, for R version 4.0.2, this will be C:\Program Files\R\R-4.0.2\bin\Rscript.exe.
This will download and install the R packages required for BEAVR. Once finished, you can close the command prompt window.
To run BEAVR:
- Double-click Run-BEAVR-Windows.bat
This will open a new command prompt window. Leave it open to keep BEAVR running.
Open your browser and go to 127.0.0.1:3838 to start using BEAVR.

A new R environment in Mac OS

Download and Install R for your operating system using the installation wizard:
- Download R 3.6.3 for Catalina here
- Download R 3.6.3 for El Capitan and higher here
Download and extract the BEAVR setup files from here
Before you can execute the install scripts, you will likely have to allow execute permissions or Mac OS will give you an error. You can do this as follows for both configuration scripts by copying and pasting these commands in Terminal:
```
chmod +x ~/Downloads/BEAVR/Setup/Configure-BEAVR-MacOS.command
chmod +x ~/Downloads/BEAVR/Run-BEAVR-MacOS.command
```
Where ~/Downloads/ is the path where you extracted BEAVR above (usually your Downloads folder or ~/Desktop/ if you moved it to your desktop.)
Look in the "Setup" folder to find the automated installer for Mac OS named Configure-BEAVR-MacOS.command. If you double-click the Configure-BEAVR-MacOS.command installer, you will likely get another error because you didn't download it from the App store.

To get around this, right-click and go to Open and then click Open in the popup box:

This will download and install the R packages required for BEAVR.

Note: You may get a popup asking for permission to install Xcode. You must agree to this install and let it finish before continuing!

To run BEAVR:
- Right-click Run-BEAVR-MacOS.command, click Open and then click Open again in the popup box.
Open your browser and go to localhost:3838 or 127.0.0.1:3838 to start using BEAVR.

A new R environment in Linux

Download and extract the BEAVR setup files for Linux:
- Linux
Run the automated installer (named Configure-BEAVR-Linux.sh). You will need to open Terminal and enter this command to execute it:
```
bash Configure-BEAVR-Linux.sh
```
This will install the latest version of R and also download and configure all of the required R packages for BEAVR automatically.

Note, if you get permission errors, you may need to give the script executable permission
```
chmod +x Configure-BEAVR-Linux.sh
```
To run BEAVR, enter this command from Terminal:
```
bash Run-BEAVR-Linux.sh
```
Note, if you get permission errors, you may need to give the script executable permission
```
chmod +x Run-BEAVR-Linux.sh
```
Open your browser and go to localhost:3838 or 127.0.0.1:3838 to start using BEAVR.

Run in your existing R installation

If you already have a working installation of R on your computer (version 3.5+), then you can follow these steps to install the required R packages to run BEAVR on any operating system.

Note, the required packages are as follows:

#CRAN packages
colourpicker
data.table
devtools
DT
ggplot2
ggpubr
ggrepel
ggraph
gridExtra
pheatmap
RColorBrewer
scales
shiny
shinydashboard
shinyWidgets
shiny
shinydashboard
shinyjqui
shinyWidgets
shinycssloaders
shinyalert
circlize

#Bioconductor packages
DESeq2
vsn
apeglm
org.Hs.eg.db
org.Mm.eg.db
ReactomePA
enrichplot

#GitHub packages
kevinblighe/EnhancedVolcano
jokergoo/ComplexHeatmap

Use your existing R installation in Windows

Note: R has been tested to work on R 3.6+

Download and extract the BEAVR setup files from here
If you don't have RTools installed already, download and install RTools for Windows using the installation wizard:
- If you R 4.0.x installed, download RTools here
- If you have an older version of R installed, download the appropriate version of RTools here
Look in the "Setup" folder to find the automated installer for Windows:
- Right click on the file named Configure-BEAVR-Windows.bat and click run as administrator (agree to any warnings/prompts to run it)
This will open a command prompt window.
You will be prompted to "enter the path to your Rscript.exe:"
- Rscript.exe is located in a folder named bin within the path where you installed R (in step 1).
- E.g. C:\Program Files\R\R-VERSION\bin\Rscript.exe, where VERSION is the version of R you have installed.
- For example, for R version 4.0.2, this will be C:\Program Files\R\R-4.0.2\bin\Rscript.exe.
This will download and install the R packages required for BEAVR. Once finished, you can close the command prompt window.
To run BEAVR:
- Double-click Run-BEAVR-Windows.bat
This will open a new command prompt window. Leave it open to keep BEAVR running.

Or

You can open the start.R file in RStudio and click Run App button in the top right

Or

You can run BEAVR from the R command prompt (after changing the working directory to where you extracted BEAVR)
```
setwd('\path\to\where\you\extracted\BEAVR\')
library(shiny)
library(shinydashboard)
runApp(port=3838)
```
Open your browser and go to 127.0.0.1:3838 to start using BEAVR.

Use your existing R installation in Mac OS

Download and extract the BEAVR setup files from here
Before you can execute the install scripts, you will likely have to allow execute permissions or Mac OS will give you an error. You can do this as follows for both configuration scripts by copying and pasting these commands in Terminal:
```
chmod +x ~/Downloads/BEAVR/Setup/Configure-BEAVR-MacOS.command
chmod +x ~/Downloads/BEAVR/Run-BEAVR-MacOS.command
```
Where ~/Downloads/ is the path where you extracted BEAVR above (usually your Downloads folder or ~/Desktop/ if you moved it to your desktop.)
Look in the "Setup" folder to find the automated installer for Mac OS named Configure-BEAVR-MacOS.command. If you double-click the Configure-BEAVR-MacOS.command installer, you will likely get another error because you didn't download it from the App store.

To get around this, right-click the file and go to Open and then click Open in the popup box:

This will download and install the R packages required for BEAVR.

Note: You may get a popup asking for permission to install Xcode. You must agree to this install and let it finish before continuing!

To run BEAVR:
- Right-click Run-BEAVR-MacOS.command, click Open and then click Open again in the popup box.
Or

You can open the start.R file in RStudio and click Run App button in the top right

Or

You can run BEAVR from the R command prompt (after changing the working directory to where you extracted BEAVR)
```
setwd('\path\to\where\you\extracted\BEAVR\')
library(shiny)
library(shinydashboard)
runApp(port=3838)
```
Open your browser and go to localhost:3838 or 127.0.0.1:3838 to start using BEAVR.

Use your existing R installation in Linux

Download and extract the BEAVR setup files for Linux:
- Linux
Run the automated R script file to install all the required packages automatically (or you may install them manually; see the complete list above)
```
sudo Rscript installpkgs.R
```
To run BEAVR, enter this command from Terminal from the BEAVR folder:
```
bash Run-BEAVR-Linux.sh
```
Note, if you get permission errors, you may need to give the script executable permission
```
chmod +x Run-BEAVR-Linux.sh
```
Or
```
Rsript start.R
```
Or

You can run BEAVR from the R command prompt (after changing the working directory to where you extracted BEAVR)
```
setwd('\path\to\where\you\extracted\BEAVR\')
library(shiny)
library(shinydashboard)
runApp(port=3838)
```
Open your browser and go to localhost:3838 or 127.0.0.1:3838 to start using BEAVR.

Installing BEAVR on a server with multi-user support

If you wish to have BEAVR running on a centralized server for your research group, you or your system administrator can follow the instructions below. We implement this using Docker and ShinyProxy which allows each user to be sandboxed in a unique Docker instance. These instructions are provided for Linux/Ubuntu servers (for now)

Download and extract the BEAVR-multiuser-server-setup.tar.gz setup package from here

Note, if you get any permission errors running the automated configuration scripts, allow permissions for the scripts:
```
chmod +x Docker-setup-ubuntu.sh OpenJDK-setup.sh ShinyProxy-setup.sh
```
From within the folder where you extracted the files.
If you already have Docker installed on your Ubuntu server, skip to step 3. Otherwise, in the setup package you just downloaded, run the Docker installer by entering this command in Terminal (this will remove any previous version of Docker!):
```
bash Docker-setup-ubuntu.sh
```
If you already have Java 8 runtime environment installed on your Ubuntu server, skip to step 4. Otherwise, in the setup package you just downloaded, run the OpenJDK installer by entering this command in Terminal (you can use another distribution of JDK like Oracle as well):
```
bash OpenJDK-setup.sh
```
Finally, run the script ShinyProxy-setup.sh to configure Docker and setup ShinyProxy:
```
bash ShinyProxy-setup.sh
```
Configure ShinyProxy settings for user access:
- If you look in the setup package you downloaded in step 1, you will find a file named application.yml
  - The bottom part of this file is pre-configured for BEAVR already.
  - In the top portion of the file, you will find the configuration line for the port (default 8080) and for user access control:
  - You can keep the default "simple" authentication method and specify user names and passwords in this file (note this file is not encrypted!)
  - You can also LDAP authentication or social authentication
  - You can set this to "none" to have no authentication so anyone with the address can access the server
  - See the ShinyProxy documentation for more information regarding authentication
To start the ShinyProxy server, enter this command in Terminal:
```
java -jar shinyproxy-2.3.0.jar
```

BEAVR Tutorial

Input files (and example files)

BEAVR requires two file inputs:

See the Examples folder for examples of these two files prepared for the Sehrawat et al. (2018) dataset.

These examples should also be in the BEAVR setup files you downloaded. Otherwise, you can download them from here

Preparing the read count table file

The read counts table file contains all the raw reads for all the samples in your experiment in a tab-delimited (.txt) or comma-separated (.csv) file type.

The table must be arranged as follows:

The first column must contain ENSEMBL IDs for every gene. The heading name for this column must be gene_id.
The next n columns must contain the raw read counts for each n samples. Label the heading name for each column with a unique sample/replicate identifier.

Here is what it looks like for the Sehrawat et al. (2018) dataset in Microsoft Excel:

The gene_id column contains ENSEMBL IDs for each gene. The columns labelled DMSO_24h-1, DMSO_24h-2, DMSO_24h-3, SP2509_24h-1, SP2509_24h-2, SP2509_24h-3 are the unique samples/replicates in the experiment and contain the raw, unnormalized read quantities for each gene for eacn sample.

Preparing the sample treatment matrix file

The sample treatment matrix file informs BEAVR which columns in the read count file belong to which treatment groups (ie. Untreated and Treated, or Wildtype and Mutant). The file type may be tab-delimited (.txt) or comma-separated (.csv).

The table must be arranged as follows:

The first column must list the sample or replicate identifiers of each sample you have in your read counts file. For example, for n samples in the read counts file, you must have n rows in the column data file. Each row is a unique sample. The heading name for this column can be left blank (it is not used).
- Note: it is critical that the order of the samples here (each row) is in the same order as the samples (each column) in the read count table file!
The second column identifies which treatment condition/group the samples belong to. The heading name for this column must be condition. For example, in each row of this column, you must identify that respective sample as belonging to Untreated or Treated or Wildtype or Mutant.
In the third column, you can specify additional characteristics for each sample. For example, you can specify different genotype groups or replicates like Replicate-A, Replicate-B, and Replicate-C (must be alphanumeric). The heading name for this column must be replicate.

Here is the sample treatment matrix file prepared for the Sehrawat et al. (2018) dataset in Microsoft Excel:

Loading your data into BEAVR

On the Load Data tab, select the files you have prepared. Make sure you select the correct file type format for each file.

Experiment settings

On the Settings tab, you can select a few options such as the reference organism, the control condition and the treatment condition, the false discovery rate used for statistics, and the minimum read count required for each gene (genes below this value will be dropped from analysis).

Differential gene expression analysis (DGE)

Click on the Gene Table tab to begin calculations. You will see a progress bar in the bottom right-hand corner of the window. The results will be displayed in a table format which you can search, order and filter and download using the sidebar.

Once these calculations finish, you can begin to visualize your data through a series of figures and download the results.

Plots, graphs and heatmaps

Each of the other tabs will provide output of plots, graphs, heatmaps and pathway figures for your data

PCA plot

The PCA tab will plot each sample on the same plot and show you the variances between samples.

Sample clustering plot

The Sample Clustering tab will cluster samples by rows and columns depending on the variance.

Read count plots

The Read Count Plots tab will allow you to plot the normalized read counts for any number of genes you specify.

You can enter genes in the sidebar separated by a comma (no spaces, as shown in image). You can specify a grid layout to show multiple plots. For example, specify 2 rows by 2 columns to show 4 plots in a square format. Or you can specify 4 rows by 1 column to show them in a stacked column format. You can also customize the position of the legend or not show a legend at all. To show just a single plot, set the grid to 1x1.

You can also chose to display the read counts in a jitter plot instead of a box plot:

Heatmap

The Heatmap tab will allow you to display the differential expression of genes in a clustered heatmap. You can enter a list of genes separated by a comma to make a heatmap of genes you are interested in. Alternatively, if you want to make a heatmap of the top differentially expressed genes, select the checkbox Show top genes instead and then enter the number of top genes to show (e.g. the top 10, 50, 100, etc.). Note: increasing the number of genes to show will increase processing time to perform clustering.

Volcano plot

The Volcano Plot tab will plot the differentially expressed genes in a volcano plot format which, unlike the heatmap, will also display the p value information for each gene.

If filtering is enabled in the Gene Table tab, then only those filtered genes will be used to make the volcano plot. Otherwise, all the genes from the Gene Table will be used.

Pathway enrichment plot

The Pathway Enrichment Plot tab will perform over-representation analysis using the filtered (or unfiltered) data set from the Gene Table tab. You can set the p value cutoff in the sidebar of the Pathway Enrichment Plot and also set the numnder of pathways to show.

You can also change an option in the sidebar to display this data as a dot plot instead of a bar plot.

Pathway enrichment map

The Pathway Enrichment Map tab will perform over-representation analysis and show you all of the pathways as an interconnected map.

Pathway enrichment table

The Pathway Enrichment Table tab will show you details of the enrichment results from the Pathway Enrichment Plot tab. You can use the Download Table button in the sidebar to download the table or use the controls in the sidebar to filter the results.

Gene set enrichment analysis (GSEA)

Similar to the Pathway Enrichment Map tab, the GSEA Map tab will perform GSEA and show you an interconnected map of pathways.

GSEA running enrichment score plot

The GSEA plot tab, will perform GSEA on your data and plot the running enrichment score. You can select which pathway to plot in the sidebar from a list of enriched pathways.

GSEA table

Similar to the Pathway Enrichment Table tab, the GSEA Table tab will show you the results of GSEA in tabular form. You can download the table or filter it using the sidebar controls.

Customizing figures

For all figures, the sidebar shows contextual options and parameters that you can configure. These are dependent on the type of plot/tab you are currently viewing. These options may include a list of genes, log2 fold change cutoffs, p value cutoffs, font sizes, colors, or legend placement options.

These parameters are categories in different headings which you can click to expand and collapse.

Resizing plots and adjusting the aspect ratio

Any of the figures in BEAVR can be resized to change their size and/or aspect ratio.

To do this, just put your mouse near the edge of the plots (near the black border). Your mouse pointer will change to indicate the area can be resized. Simply drag with your mouse to resize.

You can hold the Shift key to maintain the same aspect ratio; otherwise you can freely change the aspect ratio.

Saving figures

You can save any figure by using the Save Plot button above each figure.

You can save images as JPG, PDF, PNG, SVG, or TIFF. The Output dpi (dots per inch) setting is only used for PDF and SVG formats (the default is 48 dpi).

Troubleshooting

Issue	Solution
Bug: PCA plot, gene read count plot, and volcano plot won't auto-update after changing the treatment condition in experiments with >2 conditions/treatments. The results table will update correctly.	Change one of the parameters in the sidebar for these plots, or just refresh the page, and reload the input files.
Error message:`ncol(countData) == nrow(colData) is not TRUE`	The samples (columns) in your read count table file do not match the samples (rows) in your sample treatment matrix file. Please check to make sure sample names match and that you've selected the correct files (and formats: .csv or .txt) to load into BEAVR.
Error message:`None of the keys entered are valid keys for 'ENSEMBL'. Please use the keys method to see a listing of valid arguments`	This means the ENSEMBL IDs contained in your read count table file cannot be mapped to the reference genome you selected in the Experiment settings tab. Please verify you have selected the correct one.
Error message:`mapIds must have at least one key to match against.`	This error typically occurs when the read count table file is not in the correct format/file type. Please save the file as "CSV (Comma delimited) (.csv)" and not "CSV UTF-8 (Comma delimited) (.csv)".
Error message:`unused arguments (pointSize = input$volcanoPointSize, labSize = input$volcanoFontSize_label, legendLabels = c("Not Significant", expression(Log[2] ~ FC ~ only), "p-value only", expression(p - value ~ and ~ log[2] ~ FC)), labCol = "black")`	This error occurs because you have the incorrect version of the `EnhancedVolcano` plot installed and BEAVR is loading that one instead of the correct developmental version of the package. To fix this, remove the EnhancedVolcano package by entering this in R: `remove.packages("EnhancedVolcano")`, restart your R session. Then install the correct version of the package with: `devtools::install_github("kevinblighe/EnhancedVolcano")`. If you don't have the `devtools` package, then install it with `install.packages("devtools")`.
Error message:`lfcShrink: coef %in% resultsNamesDDS is not TRUE`	The condition names you entered in your sample treatment matrix file contain characters other than letters, numbers, underscores, or periods. Spaces or special characters are not permitted.

MusculusMus/BEAVR