##############################################
# #
# #
# Dowser++ User Manual #
# Original Program by Alexander Morozenko #
# Manual Written by Ardavan Farahvash #
# #
# #
# #
##############################################

###### Part 1: Installation Guide ######

1) Download and Unpack Dowser++ from the tar gz file: dowserplusplus.tar.gz

2) Install MGLTools: http://mgltools.scripps.edu/

3) Locate the pythonsh file in the "bin" directory of MGLTools installation and do either one of the following:
a. copy and overwrite the "pythonsh" file to the "files" directory of the Dowser++ installation
b. edit lines 11, 14, and 17 of the "main.sh" file in the "files" directory of Dowser++ to include the full path to the "pythonsh" file in the MGLTools installation

4) You're done!

###### Part 2: Running Dowser++ ######
1) When in the main Dowser++ directory simply type "./Dowser++ ABCD.pdb" substituting ABCD for the name of the specific path to the pdb file you wish to hydrate

2) Wait until it's finished.

###### Part 3: How it All Works ######
The purpose of this section will to be give some details as to what the Dowser++ script is doing, at least as far as I understand it. I have included this because of the fact that the original code is, admittedly, extremely poorly commented.

1) Upon running the "Dowser++.sh" script, it copies your pdb file to the "files" directory and calls the "main.sh" script

2) The "main.sh" script will first convert the pdb file to a pdbqt file using the "prepare_receptor4.py" script
Note: the pdbqt file is just a pdb file that also contains Gasteiger partial charges

3) The "main.sh" script will then make a set of box files (these are actually parameter files for WaterDock aka the R-Script written in "main.sh")
Note: Each of these boxes is 10x10x10 Ang, and together they span the entire protein.

4) The "main.sh" script runs the WaterDock R-script on each box seperately, collecting the results in the temp_PredictedWaters*.pdb files
Note: for details on what the WaterDock R-script is doing, consult the original publication: https://doi.org/10.1371/journal.pone.0032036

5) The "main.sh" script the concatenates all the temp_PredictedWaters*.pdb files into one big PredictedWaters.pdb file

6) A series of compiled programs is run on the PredictedWaters.pdb file
reform - reformats pdb file
drain - removes exterior water molecules and overlapping water molecuels
sorting - sorts water molecules based on binding energy
internalpredicted - I'm not sure
placewat - I'm not sure
choosing - removes all waters with binding energy less than $cutoffenergy
Since I do not have access to the source code used to write these programs, I am honestly not entirely sure how some of them operate...

7) The final output of these programs is the file PredictedInternal.pdb which contains the locations and calculated binding energy of the predicted waters.

###### Part 4: Troubleshooting ######
Most of the time any trouble that comes from running Dowser++ actually comes from Vina. Dowser++ uses the prepare_receptor4.py script of Autodock Vina to create a .pdbqt file, however a number of errors can cause this script to crash if it is unable to read the input PDB file.

I have outlined some of these errors below:

1) Nonstandard Element: Sometimes PDB files contains unidentified atoms and denote them with the elemental symbol X. This causes Dowser++ to crash when Vina cannot properly identify the atom. Please remove any such lines from your PDB file when running Dowser++.

2) Please make sure your PDB file, especially if not downloaded from the PDB, follows specific PDB formatting guidelines. If, for example, too much white-space is put in the wrong location on a specific ATOM coordinate line, Dowser++ could crash due to Vina being unable to make sense of the line.

3) Please also delete any ANISOU lines from your pdb file as well before running Dowser++, as these can also sometimes cause it to crash.

######
If your run into any other issues, please email Ardavan Farahvash using either afarahva@mit.edu or afarahvash@ucdavis.edu.