Installing VDJtools

Installing binaries

First make sure that you have installed Java Runtime Environment (JRE) v1.8 by running java -version. Any recent Linux distribution will provide it via its package manager. If not, or if your system is running MacOSX or Windows, download the JRE from Oracle.

Then download and unpack the VDJtools binaries from the latest release.

The program is then run by executing the following line:

java -jar path-to-vdjtools-X.X.X.jar

where X.X.X stands for the VDJtools version (omitted further for simplicity). This will bring up the list of available routines. To see the details (parameters, etc) for a specific routine execute

java -jar vdjtools.jar RoutineName -h

Windows

Dedicated VDJtools bundle can be downloaded from the release section and is marked with .win.zip suffix.

Linux

A VDJtools bundle can be downloaded from the release section which includes the required vdjtools.jar file.

All plotting is handled by R and will require several R packages some of which will be available via your distribution package manager. See Setting up plotting routines below.

MacOS

Installation can be performed using Homebrew package manager:

brew tap homebrew/science
brew tap mikessh/repseq
brew install vdjtools

Note that this sets vdjtools as a shortcut for java -jar vdjtools-X.X.X.jar. JVM arguments such as -Xmx can be still passed to the script, e.g. vdjtools -Xmx20G CalcBasicStats ....

Setting up plotting routines

All plotting in VDJtools framework is performed via running R scripts. Therefore one needs to install R programming language and several of its packages. Make sure that

Rscript --version

runs successfully. Note that all R scripts were tested under R version 3.1.0.

The pre-compiled `*.win.zip includes all the required R packages and the homebrew installation will install them automatically. In all other cases the required packages need to be manually installed.

These are the required packages:

CRAN package Debian package
ape r-cran-ape
circlize  
FField  
ggplot2 r-cran-ggplot2
gplots r-cran-gplots
grid  
gridExtra  
MASS r-cran-mass
plotrix r-cran-plotrix
RColorBrewer r-cran-rcolorbrewer
reshape r-cran-reshape
reshape2 r-cran-reshape2
scales r-cran-scales
VennDiagram  

If your Linux distribution includes pre-packaged versions of a package, those should be prefered. The following will install the existing for Debian and Debian based distributions such as Ubuntu and Mint:

apt-get install r-cran-ape r-cran-ggplot2 r-cran-gplots r-cran-mass \
  r-cran-plotrix r-cran-rcolorbrewer r-cran-reshape r-cran-reshape2 \
  r-cran-scales

while the other packages will have to be installed via R itself:

install.packages(c("circlize", "grid", "gridExtra", "VennDiagram"))

Alternatively, VDJtools has a ref:Rinstall routine:

java -jar vdjtools.jar Rinstall

This would also print the list of required R modules, so in case Rinstall fails, they could be installed manually by running the following command in R:

install.packages(c("reshape2", "FField", "reshape", "gplots",
                   "gridExtra", "circlize", "ggplot2", "grid",
                   "VennDiagram", "ape", "MASS", "plotrix",
                   "RColorBrewer", "scales"))

Note that most issues with package installation can be resolved by switching to correct CRAN mirror.

Dedicated windows binaries already have all R packages bundled, and the options summarized above should be considered only when troubleshooting R script execution issues.

Compiling from source

VDJtools could be compiled from source code using Apache Maven. Compilation should be performed under JRE v1.8 by running the following commands:

git clone https://github.com/mikessh/vdjtools.git
cd vdjtools/
mvn clean install

Binaries could then be found under the vdjtools/target/ folder.