.. _installation:

Download and installation
=========================

Overview
--------

There are a number of dependency requirements in order to run NanoOK. You need to ensure these are installed before installing NanoOK (see below).
If you would rather use a pre-installed image, we also provide a :ref:`VirtualBox image <virtualbox>` or a :ref:`Docker image <docker>`.

Requirements
------------

Please make sure you have installed the following before attempting to run NanoOK:

1. `Java SE runtime environment <https://java.com/download>`_ - the main application is written in Java.
2. `R statistical environment <https://www.r-project.org>`_ - for graph plotting. Make sure you have the necessary packages and see section below on installing missing ones.

   - Packages needed: ``ggplot2``, ``scales``, ``gridExtra``, ``reshape``

3. `LaTeX environment <http://latex-project.org/ftp.html>`_ that includes pdflatex - for generating PDF. Make sure you have the necessary packages installed. 

   - Packages needed: ``graphicx``, ``url``, ``multirow``, ``rotating``, ``color``, ``titlesec``, ``geometry``, ``float``

4. `HDF5 tools <https://www.hdfgroup.org/products/hdf5_tools/>`_ - are required for extracting FASTA/Q from FAST5 files.
5. `LAST <http://last.cbrc.jp/>`_ or other supported alignment tool - NanoOK also supports BLASR, BWA-MEM and MarginAlign. NanoOK assumes the aligner is available in one of the directories pointed to by the PATH variable.
6. `Git <https://git-scm.com/downloads>`_ - required for accessing the source code. Or you can download from the `NanoOK github page <https://github.com/TGAC/NanoOK>`_.

Checking if you have the dependencies installed
-----------------------------------------------

1. Type ``java -h`` to see the help text for Java.
2. Type ``R -h`` to see if R is installed.
3. Type ``pdflatex -v`` to see if LaTeX is installed.
4. Type ``h5dump -h`` to see if HDF5 tools are installed.
5. Type ``lastal -h`` to see help text for LAST.

Installing missing R packages
-----------------------------

First, start R - on Linux you may want to give sudo access to allow the installation, i.e.::

  sudo R

Then, to install packages type::

  install.packages(c("ggplot2", "scales", "gridExtra", "reshape"))

You may then have to select a 'mirror' site for the download. Once complete, you can type q() to exit R.

Installing NanoOK
-----------------

NanoOK works best on Linux and MacOS. If you need to use Windows, some tips are provided below, but installation of the dependencies is not as straightforward as on Linux and Mac OS.
NanoOK can be downloaded from TGAC's GitHub repository. You can either download the .zip file, or if you have git installed, you can type::

  git clone https://github.com/TGAC/NanoOK.git

To install:

1. Copy the whole NanoOK directory somewhere appropriate on your system.
2. Set a NANOOK_DIR environment variable to point to this directory. This enables NanoOK to know where to find the Java JARs and R scripts it uses. On Linux, you would typically do this by adding the following command to your .bash_profile (or .profile on Ubuntu) file or 'source' script::
   
     export NANOOK_DIR=/path/to/NanoOK

   On MacOs, you can edit the file using::
   
     open -e ~/.bash_profile

3. Add the bin directory to your PATH variable. On Linux, you would typically do this by adding the following command to your .bash_profile (or .profile on Ubuntu) file or 'source' script::

     export PATH=/path/to/NanoOK/bin:$PATH

4. You may have to reset for the change to take effect.
5. Set Java heap size for the tool - the main JAVA program is packaged as a .jar file. A wrapper script called nanook (in the bin directory) enables this to be run without specifying the Java Virtual Machine parameters. By default, this script request 2Gb of RAM for the Java heap. If you wish to reduce/increase this, please edit this file.

Tips for Ubuntu users
---------------------

Most of the dependencies can be installed with sudo apt-get install::

  sudo apt-get update
  sudo apt-get install r-base
  sudo apt-get install r-cran-ggplot2
  sudo apt-get install hdf5-tools
  sudo apt-get install texlive
  sudo apt-get install texlive-latex-extra
  sudo apt-get install default-jre
  sudo apt-get install git

LAST needs to be compiled from the source code, but this is very straightforward - see the website.
NanoOK can then be installed as above.

Tips for Mac OS users
---------------------

* Clicking on the links in the "Requirements" section above should take you to pages where you can download the dependencies.
* The HDF5 tools binary for Mac OS isn't completely obvious to find! Try this link: https://www.hdfgroup.org/ftp/HDF5/releases/hdf5-1.8.7/obtain5187.html
* Some users like to use Homebrew (http://brew.sh) to install some of the dependencies. This provides a package installation command similar to the Ubuntu apt-get install command.