PreDyJE Files

###########################################################
###                                                     ###
###   README.txt for PreDyJE (Dehydron predictor)       ###   
###  Eduardo Santamaría, Jorge Ruiz - Python project    ###   
###                                                     ###
###########################################################

PreDyJE is a python tool to calculate dehydrons in a protein PDB. Dehydrons are solvent-exposed hydrogen bonds.
(for further info on dehydrons see: 
Fernández, A., and S. Ridgway. "Dehydron: A structurally encoded signal for protein interaction." Biophys. J. 85 (2003): 1914-1928)

INSTALLATION:
Download PreDyje tar.gz file and uncompress it. Created folder will be PredyJE main folder.

DEPENDENCIES:
-To execute these applications you must have installed these python libraries:
    .argparse	Available at http://code.google.com/p/argparse/
    .scipy 		Available at http://www.scipy.org/SciPy

-To execute these applications you must have installed reduce program in your system:
    http://kinemage.biochem.duke.edu/software/reduce.php
By default 'reduce' executable must be located in PreDyJE folder or set in the PATH environment to execute the main application.
Otherwise, you can set your 'reduce' executable location with -r option.
    
-In addition, graphical output can be displayed in PyMOL molecular visualization system using two PyMOL scripts, so its installation is recommended:
    http://www.pymol.org/
    http://sourceforge.net/projects/pymol/

Then, you need to import module plugins (folder PreDyJE/plugins) before Pymol launches to load hbonds_pymol.py, predyje_pymol.py and dehydrons_pymol.py in menu. 
So, if you don't have a configured fixed folder for Pymol plugins, you must insert into your .pymolrc file lines contained in add_to.pymolrc.txt, 
replacing location of plugins (which is ####/path/to/PreDyJE/####)  with your PreDyJE location.
    gedit ~/.pymolrc


MODULES
PreDyJE is composed by these python modules:
    predyje.py		Executable, main module
    parsing.py		Module to parse PDB files
    hbond.py		Module to calculate hydrogen bonds properties and near carbones
    envandgrad.py	Module to define the environment of hydrogen bonds and to calculate dehydrons
    training.py		Module to train dehydron calculations with a set of proteins
    hbonds_pymol.py	PyMOL script to display total calculated backbone hydrogen bonds in PreDyJE
    dehydrons_pymol.py	PyMOL script to display total calculated dehydrons in PreDyJE
    predyje_pymol.py	PyMOL script, main module to run PreDyJE in pymol and display results
    
FOLDERS
    PreDyJE		Main folder of the program
    demo		Output text examples and pymol images of calculated dehydrons (to be created)
    doc			PreDyJE documentation (made with Doxygen)
    plugins		Pymol plugins and configuration
    results		Folder to save results: PDB with hydrogens (if reduce is activated), hydrogen bonds text and dehydrons text
    test		Example protein pdbs to run PreDyJE
    training	Set of protein pdbs to run training part
    

EXECUTABLE:
There is a main executable:
.predyje.py:
    Description: Main executable of PreDyJE in command-line option.
    
    usage: predyje.py [-h] -i INPUT [-o OUTPUT] [-nh] [-hb_distNO HB_DISTNO]
                  [-hb_distOH HB_DISTOH] [-hb_angle HB_ANGLE] [-c C] [-t T]
                  [-d D]

Computation of dehydrons in a protein.

optional arguments:
  -h, --help            show this help message and exit
  -i INPUT, --input INPUT
                        pdb input to calculate dehydrons
  -o OUTPUT, --output OUTPUT
                        output list of dehydrons (default = dehydrons)
  -nh, --non_reduce     do not calculate hydrogens in pdb
  -hb_distNO HB_DISTNO  maximum distance N-O in hydrogen bonds (default = 3.9)
  -hb_distOH HB_DISTOH  maximum distance O-H in hydrogen bonds (default = 2.5)
  -hb_angle HB_ANGLE    angle range HNO in hydrogen bonds (default = 60)
  -c C                  desolvatation sphere radius (default = 7)
  -t T                  threshold set as maximun alteration of the local
                        permitivity for identying dehydrons (default = 0.049).
                        "calculate" for getting it from the training set
  -d D                  distance from the HF test to the center of the bound
                        (default = 9.5)
    
         
    Output: 
	-reduce.log: One file with the log from the reduce (if enabled). 
	-pdbid_H_bonds: One file with the h_bonds
	-pdbid_solvation_carbones: One with the C in each solvation sphere.
	-pdbid_dehydrons: One file with the list of dehydrons (output name can be changed in menu).
	-pdbidH.pdb: One pdb with hydrogens if reduce option is enabled. Required to run pymol scripts.
	
	
PYMOL SCRIPTS:
PreDyJe prediction can be done in Pymol:
             
.predyje_pymol.py :     
    Description: PyMol script. Loads a PDB protein (with hydrogens), run PreDyJE and display dehydrons in PyMol. Reduce and training options
    are not available (but you can execute both in shell).
   
    To run:
         1. pymol>Plugin>Run PreDyJE on Pymol
         2. Put your parameters and select your PDB file with H (default folder: PreDyJE folder)
         3. Wait and watch the results. Predictions can take a few minutes.
         
    Output:
         Loads the PDB structure with hydrogens in PyMol and then use distances to draw backbone dehydrons in yellow.

In addition, there are two PyMol scripts to visualize the output, you can use both scripts to combine information. Both scripts works with results of PreDyJE:
	
.dehydrons_pymol.py :     
    Description: PyMol script. Loads the complete result dehydron list in PyMol and draw dehydrons in the loaded protein 
    (it must be the same pdb used in PreDyJE with hydrogens -created in results-).
    
    To run:
	 1. Open your pdb protein (with hydrogens) and delete other non-necessary proteins or objects open in the visualizer
         2. pymol>Plugin>Dehydrons visualizer
         3. Write the name of your dehydron output obtained in folder results (without path, it searches in results folder).
         
    Output:
         Loads the PDB structure with hydrogens in PyMol and then use distances to draw backbone dehydrons in yellow.


.hbonds_pymol.py :     
    Description: PyMol script. Loads the complete hydrogen bond list in PyMol and draw hydrogen bonds in the loaded protein 
    (it must be the same pdb used in PreDyJE with hydrogens -created in results-).
   
    To run:
	 1. Open your pdb protein (with hydrogens) and delete other non-necessary proteins or objects open in the visualizer
         2. pymol>Plugin>Backbone Hbonds visualizer
         3. Write the name of your hbond output obtained in folder results(without path, it searches in results folder).
         
    Output:
         Loads the PDB structure with hydrogens in PyMol and then use distances to draw backbone hydrogen bonds in red.