.. MacSyFinder - Detection of macromolecular systems in protein datasets
    using systems modelling and similarity search.            
    Authors: Sophie Abby, Bertrand Néron                                 
    Copyright © 2014  Institut Pasteur, Paris.                           
    See the COPYRIGHT file for details                                    
    MacsyFinder is distributed under the terms of the GNU General Public License (GPLv3). 
    See the COPYING file for details.  

.. _installation:


************
Installation
************

========================
MacSyFinder dependencies
========================
MacSyFinder has two dependencies:
 - the *formatdb* (>=2.2.26) or *makeblastdb* (>=2.2.28) tools provided with the Blast suite of programs 
(http://blast.ncbi.nlm.nih.gov/Blast.cgi?CMD=Web&PAGE_TYPE=BlastDocs&DOC_TYPE=Download) 
 - the program *Hmmer* version 3.1 (http://hmmer.janelia.org/).

*formatdb* or *makeblastdb* and *hmmsearch* programs should be installed (*e.g.*, in the PATH) in order to use MacSyFinder. Otherwise, the paths to these executables must be specified in the command-line: see the :ref:`command-line options <hmmer-options>`. 
 
**Python version 2.7** is required to run MacSyFinder: https://docs.python.org/2.7/index.html 

======================
Installation procedure
======================

It is recommended to use the MacSyFinder package instead of the git repository.

Archive overview
================

* bin => contain the executables (macsyfinder)
* data => the hmm profiles and the systems definitions
* doc => the documentation in html and pdf
* etc => a template of macsyfinder configuration file
* test => all needed for unit tests
* macsypy => the macsyfinder python library
* setup.py => the installation script

Installation steps:
=======================

Make sure every required dependence/software is present.
--------------------------------------------------------

By default MacSyFinder will search if `makeblastdb` is on your PATH if not it will looking for `formatdb`.
if neither `makeblastdb` nor `formatdb` are in your path you have to set the absolute path toward one of
these tools in the configuration file.
by default MacSyFinder will try to use `hmmsearch` in your PATH, if `hmmsearch` is not in the PATH,
you have to set the absolute path to the `hmmsearch` in configuration.
If the tools are not in the path, some test will be skipped and a warning will be raised.


Perform the installation.
-------------------------

Uncompress the archive
""""""""""""""""""""""

::

    sudo python setup.py install
    tar -xzf macsyfinder-x.x.tar.gz
    cd macsyfinder-x.x


Build MacSyFinder
"""""""""""""""""

macsyfinder installation follows classical "pythonic" installation procedure (see http://docs.python.org/2/install/): ::

    python setup.py build

Test MacSyFinder
""""""""""""""""

It is **highly recommended** to run tests before performing the full installation.
To test the libraries you just build: ::

    python setup.py test -vv

Install
"""""""

::

    sudo python setup.py install


If you have not the privileges to perform a system wide installation,
you can use a [virtual environment](https://virtualenv.pypa.io/en/stable/). ::

    vitualenv macsyfinder
    source macsyfinder/bin/activate
    mkdir macsyfinder/src
    cd macsyfinder/src

and follow the "regular" procedure:

* uncompress the archive
* build MacSyFinder
* test MacSyFinder

for installation do not use neither `--prefix` nor `sudo` ::

    python setup.py install


To exit the virtualenv just execute the `deactivate` command.
To run `macsyfinder`, you need to activate the virtualenv: ::

    source macsyfinder/bin/activate

Then run macsyfinder/macsyview

You can access all general cmd with ::

    python setup.py --help

or specific options with ::

    python setup.py cmd --help




  
.. note::
  Super-user privileges (*i.e.*, ``sudo``) are necessary if you want to install the program in the general file architecture.
  
  
.. note::
  If you do not have the privileges, or if you do not want to install MacSyFinder in the Python libraries of your system, 
  you can install MacSyFinder in a virtual environment (http://www.virtualenv.org/).

Procedures specific to MacSyFinder can be used instead of default. Please run the command for full options::
  

  python setup.py --help

The main ones are::
 
  python setup.py install --prefix /usr/local/home/bob/my_programs # Specifies an installation path

=> It will install MacSyFinder and required data (profiles folder and systems definition folders) in the Home directory of "bob", in the "my_progams" folder (useful if you do not have super-user privileges).

.. warning::
  When installing a new version of MacSyFinder, do not forget to uninstall the previous version installed ! 

Uninstalling MacSyFinder
========================

To uninstall MacSyFinder (the last version installed), run::

  (sudo) python setup.py uninstall 


If You want to install from the git repository
==============================================

::

    virtualenv macsytest
    mkdir macsytest/src
    source macsytest/bin/activate
    cd macsytest/src
    git clone https://github.com/gem-pasteur/macsyfinder.git
    cd macsyfinder/
    python setup.py build
    python setup.py install --no-viewer