Installation of the PIPSA python module (multipipsa)

The recommended setup for the PIPSA python module is to use an anaconda environment.
Although the multipipsa module should also work with python2, it is mainly 
tested witha python3 environment. Also only linux setup is tested. 


1. Install Anaconda 3 from https://www.anaconda.com/download
The Linux installer comes as a .sh Install it with 
    /bin/bash NameOfAnacondaFile.sh
Make sure you add the path of the anaconda3/bin directory to your system path and 
    source anaconda3/etc/profile.d/conda.sh
in your bashrc.
Start a new bash, to read your .bashrc and verify that now the command:
   which python
shows a python interpreter from within the installed anaconda3 distribution.
Also the command
   which conda
should be available.

Also you need to have apbs available from your system. This can conveniently 
be installed
from the linux package manager, eg: apt-get install apbs


2. Setup the channels from where conda installs packages. Since multipipsa depends
on some bio-related pacakges, we recoomend to set the following channels in the given order:
    conda config --add channels defaults

Make sure the conda forge and bioconda channel is not added, we had recommended
this in a previous release, but they may introduce version incompatibilities:
    conda config --remove channels bioconda
    conda config --remove channels conda-forge

3. Create a conda environment for your pipsa runs:
    conda create -n mypipsa2 python=2
or  
    conda create -n mypipsa3 python=3
depending on if you want to work with python2 or python3. We recommend to use
python 3, as python2 is deprecated at this point in time.

4. Every time you want to use pipsa, load the environment:
    conda activate mypipsa3 [or mypipsa2 respectively]
you can deactivate your environment using
    conda deactivate


5. If not already installed, one needs additional linux system packages to
install as root. The corresponding dependencies are: 

   sudo apt-get install python-dev libxml2-dev libxslt-dev r-base-core
   
If you want to use the structural alignment tool, you also need the 
sequence alignment tool muscle installed (https://de.wikipedia.org/wiki/MUSCLE_(Software)):

   sudo apt-get install muscle

Within the multipipsa distribution, go to the top directory. Load your
anaconda environment and install multipipsa in it. 
   cd <multipipsa-root-dir>
   conda activate mypipsa3
   python setup.py install

If you use python2, you need to activate your python2 environment:
   cd <multipipsa-root-dir>
   conda activate mypipsa2
   python setup.py install

To be able to generate electrostatic grids the programs apbs and pdb2pqr are
required. Depending on your linux distribuion, they can be installed via
the command (sometimes pdb2pqr is part of the apbs package, sometimes it is 
a seperate package):

   sudo apt-get install apbs
and 
   sudo apt-get install pdb2pqr
if pdb2pqr is a seperate package and not included in your apbs package.
 
In case you have already setup a python environment using conda or virtualenv
etc. you can also install the multipipsa package using
pip install --extra-index-url https://projects.h-its.org/pypi multipipsa
   
6. To run multipipsa the testMultipipsa.py should be run first. This also gives
some ideas on how to use the multipipsa python module. Also the main method of
the multipipsa.py module file contains some example. This example takes about 
1h to run. Please note, PIPSA requires superimposed structues as they are
included in the example directory.

Please note, apbs produces the following Error that can be ignored:

    asc_getToken: Error occurred (bailing out).
    Vio_scanf: Format problem with input.

   cd <multipipsa-root-dir>/multipipsa
   python testMultipipsa.py 
   
Warnings about IEEE_INVALID_FLAG can also be ignored, they are due to running the 
comparision also inside the protein, where no overlap on the surface can be generated.

7. To generate python documentation, go to the <multipipsa-root-dir>/multipipsa directory and execute
   cd <multipipsa-root-dir>/multipipsa
   pydoc ./multipipsa.py ./clusterpipsa.py

pydoc also allows to generate different formats 
( see http://www.sphinx-doc.org/en/master/ ).
   
8. Structural alignment can also be performed using the multipipsa module. 
Please consult the main method of multipipsa/structurealign.py for an example.
As mentioned above, the structural alignment depends on the sequence alignment 
tool muscle to be installed.

The code to run the structural alignment is as follows and asumes the 
PDB files in the <multipipsa-root-dir>/multipipsa/data/example/pdbs
directory (set by the dataDir flag).

    examplePDBs = os.path.join(os.getcwd(), 'data', 'example', 'pdbs')
    stal=StructureAlign(structures=["1hti",  "1b9b", "1ci1", "1i45", "1tim"],
                        dataDir=examplePDBs)
    stal.alignWithTemplate(template="1tim")

The aligned pdb files are also generated in this directory with the suffix "-aln". 
The structural alignment is performed in R using the struct.aln method of the 
bio3d package: http://thegrantlab.org/bio3d/html/struct.aln.html
The script installs the package itself, Errors about 
configuration failed for package ‘ncdf4’
can be ignored.