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.