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


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


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.


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 `* 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
ggplot2 r-cran-ggplot2
gplots r-cran-gplots
MASS r-cran-mass
plotrix r-cran-plotrix
RColorBrewer r-cran-rcolorbrewer
reshape r-cran-reshape
reshape2 r-cran-reshape2
scales r-cran-scales

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 \

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
cd vdjtools/
mvn clean install

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