Installation Instructions for MiModD and Required Software
**********************************************************

Required Software (needed for MiModD core functionality):
=========================================================

Python3:
--------

version 3.2 or higher

download from `<http://www.python.org/downloads/>`__ or see
whether there is a package available through your OS package manager

.. Note::

    On many platforms you will need to separately install the *python3-dev*
    package (the exact name of the package varies between platforms, make
    sure you are installing a version matching your Python version). If
    later, during the installation of MiModD (see below), you get an error
    concerning missing header files, this is because this package is
    missing.

--------------

SNAP:
-----

version 0.15.4

download from:
`http://snap.cs.berkeley.edu <http://snap.cs.berkeley.edu>`__

.. Important::

    A beta version of SNAP 1.0.0 has recently been released. While this
    version of SNAP offers many promising new features, MiModD does **NOT**
    currently support it. We are planning to change this shortly after there
    is a stable release of the new version, but for now make sure you
    install the old version (links to both are available on the SNAP
    homepage.)

installation:
~~~~~~~~~~~~~

copy the snap executable to a directory in your system $PATH (e.g., to
/usr/local/bin)

--------------

samtools:
---------

version 0.1.19

download from
`http://sourceforge.net/projects/samtools <http://sourceforge.net/projects/samtools>`__

installation:
~~~~~~~~~~~~~

Unpack the downloaded archive to any directory (called <UNPACK\_DIR>
from here on), then follow the instructions in the INSTALL file.

BRIEF SUMMARY of the installation procedure (this requires the gcc
compiler, which comes pre-installed with most operating systems):

from a console/terminal window type:

.. code::

    cd <UNPACK_DIR>

then:

.. code::

    make

This will compile all tools to executables.

If the compilation fails make sure you have

-  the `zlib library <http://www.zlib.net>`__ version 1.2.3 or higher and
-  the `ncurses library <http://www.gnu.org/software/ncurses/>`__

installed on your system. If you are not going to use ``samtools tview``
(MiModD does not use it), then, instead of installing the ncurses
library, you can also change the ``Makefile`` in <UNPACK\_DIR> as
detailed in the samtools installation instructions.

copy ``samtools`` and ``bcftools/bcftools`` to a directory in your
system $PATH (e.g., to /usr/local/bin)

.. Hint::

    you may also copy any other executables/scripts found in the ``misc``
    directory, but these are not required by MiModD.

.. Important::

    keep all files in the unpacked download directory until you have
    finished installing MiModD

Optional Software (can also be installed later)
===============================================

snpEff:
-------

version 3.3 or higher

download from:
`http://snpeff.sourceforge.net/ <http://snpeff.sourceforge.net/>`__

.. Note::

    snpEff is written in and, thus, requires Java, which you may need to
    install separately, if you do not have it yet on your system.

installation:
~~~~~~~~~~~~~

Unpack the downloaded archive to a newly created ``snpEff`` folder in
your home directory. If you prefer a different installation directory,
read the instructions at
`http://snpeff.sourceforge.net/download.html#install <http://snpeff.sourceforge.net/download.html#install>`__.

--------------

Galaxy:
-------

release 2013.02.08 is the oldest tested with MiModD 0.1

installation:
~~~~~~~~~~~~~

see
`https://wiki.galaxyproject.org/Admin/GetGalaxy <https://wiki.galaxyproject.org/Admin/GetGalaxy>`__
for instructions

.. Note::

    -	Currently, Galaxy runs under Python 2.6 or 2.7 (Python 3 is not yet
	supported).

	This means that you will have to have two different Python versions
	installed on your system (2.6/7 for Galaxy, Python 3.2 or higher for
	MiModD). The simplest way to make Galaxy and MiModD use their correct
	versions is by making Python 2.x available as ``python`` and Python
	3.x as ``python3`` from your shell.

	You can use ``python --version`` and ``python3 --version`` from the
	command line, respectively, to find out what versions of Python are
	known to your system under the different names.

	The installation link above (under check your python version) also
	provides an example of how you can manipulate your $PATH variable to
	make your system find the right Python.

    -   The installation procedure for Galaxy requires Mercurial. To see
	whether that is installed on your system, type ``hg`` on the command
	line and see whether that brings up a help or an error message. If
	you do not have Mercurial you can get it from
	`http://mercurial.selenic.com/wiki/Mercurial <http://mercurial.selenic.com/wiki/Mercurial>`__
	or via your OS package manager.

    -	If you are trying to install Galaxy from behind a proxy and you
	cannot connect to the repository following the installation
	instructions, then instead of the standard:

	``hg clone https://bitbucket.org/galaxy/galaxy-dist/``

	try:

	``hg --config http_proxy.host=ADRRESS_OF_PROXY:PORT_NUMBER clone https://bitbucket.org/galaxy/galaxy-dist/``
	or

	``hg --config http_proxy.host=ADRRESS_OF_PROXY:PORT_NUMBER --config http_proxy.user=USERNAME --config http_proxy.passwd=PASSWORD clone https://bitbucket.org/galaxy/galaxy-dist/``
	(for proxies requiring authentication)

MiModD Installation:
====================

Standard Installation (Python Package plus command line script):
----------------------------------------------------------------

1.  Unpack the downloaded archive file and, using a console/terminal, 
    change to the unpacked directory, via ``cd <UNPACK_DIR>``

2.  Copy all required samtools files to the package by typing:

    .. code::

	python3 setup.py import <SAMTOOLS_DIR>

    where <SAMTOOLS\_DIR> should be replaced with the full path to the
    unpacked download directory that you should have kept from the
    samtools installation step. If you do not have that directory
    anymore, simply download and unpack the samtools archive again.

    .. Note::

	``python3`` in the above and the next command should be substituted
	with the name or alias of your local Python 3.2 or higher version of
	the Python interpreter that you want MiModD to use once installed.

3.  Install the package by typing:

    .. code::

	sudo python3 setup.py install

    Note that:

    -	you will be asked to authorize yourself as administrator / superuser 
	at this step
    -	there may be lots of ``WARNINGS`` during the installation, which you 
	can safely ignore unless the installation aborts with a real ``ERROR``

    .. Hint::

	If the installation process aborts with a message about some header
	files not being found, your system requires the developer package for
	python3, which you can find in your package manager under a name like
	``python3-dev`` or ``python3-devel``.

    **MiModD should now be installed on your system and be ready to
    use!**

    .. Hint::

	To test the installation, try:
	``mimodd --help``

	If you get a list of available subcommands, you installed MiModD
	successfully !!

--------------

Installation for Galaxy:
------------------------

Complete the Standard Installation, then proceed as follows:

4.  On the command line type:

    .. code::
	
	mimodd enable_galaxy <path_to_local_galaxy>``
	
    where ``<path_to_local_galaxy>`` typically is something like 
    ``~/galaxy-dist``

5.  (Re)start Galaxy and import the Workflows that come with MiModD 
    (and can be found in the galaxy-workflows directory of the unpacked 
    download directory).

**Congratulations. MiModD is now fully functional!**

--------------

Configuring MiModD for your system:
-----------------------------------

From the command line use:

.. code::

    mimodd config -v

to see the current configuration settings of MiModD.

Type:

.. code::

    mimodd config --help

to learn how to change settings.

.. Note::

    The basic command for this will look like:

    ``mimodd config -c`` followed by a specification of the parameter you want 
    to change.

    Typically, any changes to the configuration file will require
    superuser/administrator rights, so you will have to use something like:

    ``sudo mimodd config -c <parameter_specs>`` in most cases.

These are the settings that currently can (and should) be configured:

.. Note::

    You can change all settings at any time, but you should definitely set
    them according to your system specifications before you start using
    MiModD for any real analysis.

**TMPFILES\_PATH**: the directory that MiModD will use to store
temporary files.

In a typical analysis pipeline, MiModD will produce several GB of data
in this directory, which it will remove again at the end of the
analysis. Under rare circumstances, files may not be deleted when they
should be, so this directory is the first place you should look at if
you require more space on your disk. Also, any users of MiModD will
require write permission in this directory.

**MULTITHREADING\_LEVEL**: the maximum number of threads that a single
MiModD process will ever use on the system.

**MAX\_MEMORY**: the maximum memory in GB that a single MiModD process
will use on the system. This value will be respected by all MiModD
subcommands/tools **EXCEPT for the snap alignment subcommands/tools**.
Due to the nature of the underlying SNAP aligner, ``mimodd snap``,
``mimodd snap_batch`` and the Galaxy tool *SNAP Read Alignment* will
always use a fixed amount of memory that depends on the size of the
reference genome and which may be significantly more than the configured
setting.

.. Tip::

    MULTITHREADING\_LEVEL and MAX\_MEMORY will have a big effect on the
    performance of MiModD, but also on the responsiveness of your system
    during any analysis. As a rule of thumb, if you do not have special
    requirements, we recommend to set both parameters to one half of the
    available resources on your system, i.e., if you have 8 threads and 16
    GB of RAM on your system, you might set MULTITHREADING\_LEVEL to 4 and
    MAX\_MEM to 8.

**SNPEFF\_PATH**: this is the path where MiModD will look for the SnpEff
variant annotation tool. With a typical SnpEff installation this should
be set to ~/snpEff, but your system may require a different setting. If
you do not SnpEff, you can accept the default setting, which will not
let you use MiModD tools that depend on SnpEff.
