AutoGrow 2.0.4 Tutorial

  Uncompress     Installation     Configuration     Execution     As the Program is Running     Output  

AutoGrow 2.0.4 Tutorial

Uncompress Archive

Prior to use, AutoGrow must be properly installed. After uncompressing the AutoGrow.zip file, several directories are initially created. These include the bin, src, and fragment directories. The bin directory contains the AutoGrow executable files, the src directory contains the AutoGrow source code, and the fragment directory contains default fragment libraries.

[user@cluster AutoGrow]$ unzip AutoGrow_2_0_4.zip
Archive: AutoGrow_2_0_4.zip
creating: bin/
inflating: bin/atom.class
inflating: bin/atom_group.class
inflating: bin/BondLengthLibrary.class
...
[user@cluster AutoGrow]$

Installation

Without further installation, however, AutoGrow will not run. AutoGrow can be installed by running the program in “Install” mode. When run in “Install” mode, AutoGrow requeuests information about the computer system, including the paths to the AutoDock executable, AutoDockTools (ADT) python scripts, etc.

When running AutoGrow in Install mode, all required files and directories are automatically created and configured. Additionally, a sample parameter file (default.prm) is created in the bin directory to assist the user in configuring AutoGrow. (Click here to see an example of this sample default.prm file.)

[user@cluster AutoGrow]$ cd bin
[user@cluster bin]$ java Main -run_mode Install
AutoGrow 2.0.4
You're running AutoGrow in install mode. Install mode sets up scripts and configuration files for use on your system.
Install mode does not create certain key files, including the fragment libraries and Java class files. These files
should have been placed in their correct directories when AutoGrow was uncompressed.

Checking to make sure you're running this program from the bin directory...Done.
Checking existance of "scripts" directory...Failed.
     Creating the "scripts" directory...Done.
Checking existance of "run_dir" directory...Failed.
     Creating the "run_dir" directory...Done.
Checking existance of "fragment" directory...Done.
Checking to see if the default parameter file, "default.prm" is present in the "bin" directory...Failed.
     Creating "default.prm,", with some default parameters. Must be edited before running AutoGrow...Done.
Please type in the directory (absolute path) that contains the autodock vina binary file: /net/linux/src/autodocksuite-4.0.1/src/autodock-vina/
Checking to see if the "autovina.dat" is present in the "scripts" directory...Failed.

Here's all the files in "/net/linux/pkg/autodock-vina-1/":

1: vina_split
2: vina

Please type in the number that corresponds to the AutoDock Vina executable file and press enter: 2

Creating "autovina.dat" in the "scripts" directory...Done.
Please type in the directory (absolute path) where I can find the "mglenv" file, which sets required environment variables.
     Depending on how you installed MGLTools, you may not need an "mglenv" file. If you don't need the file,
     just press enter: /u1/jdur/scripts

Here's all the files in "/u1/jdur/scripts/":

1: end_of_dlg.dat
2: prepare_gpf.dat
3: prepare_ligand.dat
4: mglenv
5: autogrid.dat

Please type in the number that corresponds to the "mglenv" file and press enter: 7

Please type in the directory (absolute path) that contains the MGLTools python scripts (e.g. prepare_ligand4.py):
     /net/linux/src/MGLTools/share/lib/python2.4/site-packages/AutoDockTools/Utilities24/
Checking to see if the "prepare_ligand.dat" file is present in the "scripts" directory...Failed.

Here's all the files in "/net/linux/src/MGLTools/share/lib/python2.4/site-packages/AutoDockTools/Utilities24/":

1: prepare_dpf.py
2: prepare_dpf4.py
3: prepare_gpf.py
4: prepare_gpf4.py
5: prepare_ligand.py
6: prepare_ligand4.py
7: prepare_receptor.py
8: prepare_receptor4.py

Please type in the number that corresponds to the ligand-preparation python script (e.g. prepare_ligand4.py) and press enter: 6

Creating "prepare_ligand.dat" in the "scripts" directory...Done.
Checking to see if the "prepare_receptor.dat" file is present in the "scripts" directory...Failed.

Here's all the files in "/net/linux/src/MGLTools/share/lib/python2.4/site-packages/AutoDockTools/Utilities24/":

1: prepare_dpf.py
2: prepare_dpf4.py
3: prepare_gpf.py
4: prepare_gpf4.py
5: prepare_ligand.py
6: prepare_ligand4.py
7: prepare_receptor.py
8: prepare_receptor4.py

Please type in the number that corresponds to the receptor-preparation python script (e.g. prepare_receptor4.py) and press enter: 8

Creating "prepare_receptor.dat" in the "scripts" directory...Done.
Done installing scripts and parameter files. Before running AutoGrow, you should examine the following files:
     "default.prm" in the "bin" directory, which can be used as a template for a AutoGrow parameter file.
Thanks for using AutoGrow!
[user@cluster AutoGrow]$

Configuration

Following installation, the user must configure AutoGrow for a given run by modifying the variable values contained in the user-input file (bin/default.prm by default). (Click to see an example of the install-generated defaultm.prm and a configured default.prm file.) First, the user must specify the location of several important directories. The “working root directory” variable indicates the directory where AutoGrow will place the AutoDock input and output files for each generation of the evolutionary algorithm. An output file called BestLigands.log in also created in the working root directory; this file contains the AutoDock scores of the top ligands of each generation. The default location of the working root directory is run_dir.

The “fragments directory” variable indicates the directory location of the fragment library used to create “mutant” ligands. The PDB fragments in this directory are added to the evolving ligand in order to improve hydrogen bond, electrostatic, and hydrophobic interactions. AutoGrow comes with two default fragment libraries. The default location of the fragments directory is fragment/large_fragment.

The “scripts directory” variable indicates the directory containing scripts that allow AutoGrow to interface with AutoDock, AutoGrid, and the ADT python scripts, as well as with the scheduling system, if any. By default, this variable points to the scripts directory.

The user must also identify the location of both initial-ligand and protein-receptor PDB files. The “initial ligand” variable contains the absolute path to the PDB file of the initial “core” scaffold, and the “receptor” variable contains the absolute path to the PDB file of the protein receptor.

AutoGrow makes calls to AutoDock Vina. This program accepts a number of user-specified parameters that should be defined in the AutoGrow user-input file. The variables "autodock grid center" and "autodock box size" specify the size and the location of a cube encompassing the receptor active site. For more information about each of these AutoDock Vina variables, please see the AutoDock Vina manual.

In addition to specifying the parameters that AutoGrow will pass to the AutoDock Vina program, the user must also specify the parameters of the AutoGrow evolutionary algorithm itself. The variable “number of carryovers” specifies the number of best-fit ligands from each generation that become the founding members of the next generation. The variables “number of children” and “number of mutants” specify the number of “children” and “mutant” ligands derived from those founders via the “crossover” and “mutation” operator, respectively.

The user can place a number of constraints on the growing ligands. The variable “number of generations” specifies the maximum number of generations for which AutoGrow will run; AutoGrow termination prevents ligands from growing too large. The “max number atoms” variable is likewise used to prevent AutoGrow ligands from growing too large; AutoGrow will not create ligands that exceed the number of atoms specified. The user can also require that the evolving ligands dock within a specific active site. The “receptor location” and “receptor radius” variables are used to specify the location and size of the active site. Additionally, the “indices of hydrogens that are not linkers” variable contains the indices of scaffold hydrogen atoms to which AutoGrow will not add fragments.

Example default.prm files:

General bin/default.prm Created upon Installation

Modified bin/default.prm for a Specific Project

//DIRECTORIES
working root directory: /u1/AutoGrow/run_dir
fragments directory: /u1/AutoGrow/fragment/large_fragment
scripts directory: /u1/AutoGrow/scripts

//INPUT FILES
initial ligand: ????
receptor: ????

//AUTODOCK PARAMETERS
autodock grid center: ??.??? ??.??? ??.???
autodock box size: 15 15 15

//EVOLUTION PARAMETERS
number of carryovers: 10
number of children: 20
number of mutants: 20
max number atoms: 500
receptor location: ??.??? ??.??? ??.???
receptor radius: 10
indices of hydrogens that are not linkers: -1
number of generations: 8
//DIRECTORIES
working root directory: /u1/AutoGrow/run_dir
fragments directory: /u1/AutoGrow/fragment/large_fragment
scripts directory: /u1/AutoGrow/scripts

//INPUT FILES
initial ligand: /u1/AutoGrow/models/nsc16209.pdb
receptor: /u1/AutoGrow/models/1XDN.pdb

//AUTODOCK PARAMETERS
autodock grid center: 39.000 21.500 13.500
autodock box size: 15 15 15

//EVOLUTION PARAMETERS
number of carryovers: 10
number of children: 20
number of mutants: 20
max number atoms: 500
receptor location: 38.754 26.297 9.154
receptor radius: 10
indices of hydrogens that are not linkers: -1
number of generations: 8

Execution

If you'd like to follow this tutorial on your own UNIX-based computer cluster, click to download nsc16209.pdb and 1XDN.pdb. If you choose to use another ligand and/or receptor, be sure to add all hydrogen atoms to both before processing with AutoGrow. Place both these files in the directory specified in your default.prm file. The location used above, /u1/jdur/, is not likely to be the ideal directory for your system.

[user@cluster AutoGrow]$ cd bin
[user@cluster bin]$ java Main -run_mode Execute -parm_file default.prm
AutoGrow 2.0.4
ACTION: Loading INI file "default.prm.old2"
     "working root directory" set to "/u1/jdurrant/AutoGrow_Vina/run_dir"
     "fragments directory" set to "/u1/jdurrant/AutoGrow_Vina/fragment/large_fragment"
     "scripts directory" set to "/u1/jdurrant/AutoGrow_Vina/scripts"
     "initial ligand" set to "/u1/jdurrant/AutoGrow_Vina/test/nsc16209.pdb"
     "receptor" set to "/u1/jdurrant/AutoGrow_Vina/test/1XDN.pdb"
     "autodock grid center" set to "39.000 21.500 13.500"
     "autodock box size" set to "86 72 78"
     "number of carryovers" set to "5"
     "number of children" set to "10"
     "number of mutants" set to "10"
     "max number atoms" set to "70"
     "receptor location" set to "38.754 26.297 9.154"
     "receptor radius" set to "5"
     "indices of hydrogens that are not linkers" set to "44 34 45 46 33"
     "number of generations" set to "9"
MESSAGE: Make sure the receptor files have been set up correctly.
     ACTION: Creating directory for receptor at "./receptor"
     ACTION: Copying receptor PDB file from source specified in AutoGrow parameter file.
          ACTION: Loading file "/u1/jdurrant/AutoGrow_Vina/test/1XDN.pdb"
          ACTION: Saving file as "/u1/jdurrant/AutoGrow_Vina/run_dir/receptor/receptor.pdb"
     ACTION: Preparing receptor.
          ACTION: Creating receptor PDBQT file.
          MESSAGE: Program output:
          setting PYTHONHOME environment adding gasteiger charges to peptide
MESSAGE: Prepare generation directory (create or restart, as necessary).
     ACTION: No previous generation directories exist. Setting up the first generation.
          ACTION: Loading file "/u1/jdurrant/AutoGrow_Vina/test/nsc16209.pdb"
          ACTION: Saving file as "/u1/jdurrant/AutoGrow_Vina/run_dir/generation_1/ligand1.pdb" ...


As the Program is Running

For didactic purposes, let's follow the program's output as it runs.

  1. The receptor AutoGrid map files are generated in run_dir/receptor. Here's an example of what that directory looks like once the map files have been created:

    [user@cluster receptor]$ ls receptor.make.bat receptor.pdb receptor.pdb.pdbqt
  2. Next, a directory is created at run_dir/generation_1. The program then places in that directory a number of ligands derived from the initial scaffold, nsc16209.pdb, by adding fragments through randomly selected hydrogen atoms. Here's some examples of these new ligands:

    NSC16209 (Original)
    Derivative Ligands (Small Molecular Fragments Added to NSC16209)
  3. Having generated many new ligands, AutoGrow docks each into the protein receptor using AutoDock Vina. After each ligand is docked, an AutoDock output file (OUT file) is created automatically. (Click to see a sample OUT file.)
    [user@cluster generation_1]$ ls *.out ligand10.vina.out ligand17.vina.out ligand23.vina.out ligand6.vina.out ligand11.vina.out ligand18.vina.out ligand24.vina.out ligand7.vina.out ligand12.vina.out ligand19.vina.out ligand25.vina.out ligand8.vina.out ligand13.vina.out ligand1.vina.out ligand2.vina.out ligand9.vina.out ligand14.vina.out ligand20.vina.out ligand3.vina.out ligand15.vina.out ligand21.vina.out ligand4.vina.out ligand16.vina.out ligand22.vina.out ligand5.vina.out
    These files each contain the AutoDock-predicted binding energy of the corresponding novel ligand.
  4. AutoGrow identifies the ligands with the best predicted binding affinities. The names of these ligands and their predicted binding energies are written to the file run_dir/BestLigands.log. (Click to see a sample BestLigands.log file.)
  5. Having docked all the ligands of the first generation, AutoGrow creates a new directory at run_dir/generation_2. The ligands with the best predicted binding affinities from the first generation are copied to run_dir/generation_2. These ligands now become the founders of the next generation; the program produces a number of new ligands based on these founders, and the process starts over again.

Program Output

AutoGrow writes output to a number of files in the working root directory (run_dir by default). Contained within the working root directory are a number of subdirectories called generation_#, where # is a number. The AutoGrow and AutoDock input and output files of each generation are stored in these directories.

[user@cluster AutoGrow]$ cd run_dir
[user@cluster run_dir]$ ls
BestLigands.log generation_1 generation_2 generation_3 generation_4 generation_5 generation_6 generation_7 generation_8 generation_9 receptor
[user@cluster run_dir]$ cd generation_8
[user@cluster generation_8]$ ls

do_copy.bat ligand16.pdbqt ligand21.vina ligand4.pdb ligand10.pdb ligand16.pdbqt.make.bat ligand21.vina.out ligand4.pdbqt ligand10.pdbqt ligand16.vina ligand22.pdb ligand4.pdbqt.make.bat ligand10.pdbqt.make.bat ligand16.vina.out ligand22.pdbqt ligand4.vina ligand10.vina ligand17.pdb ligand22.pdbqt.make.bat ligand4.vina.out ligand10.vina.out ligand17.pdbqt ligand22.vina ligand5.pdb ligand11.pdb ligand17.pdbqt.make.bat ligand22.vina.out ligand5.pdbqt ligand11.pdbqt ligand17.vina ligand23.pdb ligand5.pdbqt.make.bat ligand11.pdbqt.make.bat ligand17.vina.out ligand23.pdbqt ligand5.vina ligand11.vina ligand18.pdb ligand23.pdbqt.make.bat ligand5.vina.out ligand11.vina.out ligand18.pdbqt ligand23.vina ligand6.pdb ligand12.pdb ligand18.pdbqt.make.bat ligand23.vina.out ligand6.pdbqt ligand12.pdbqt ligand18.vina ligand24.pdb ligand6.pdbqt.make.bat ligand12.pdbqt.make.bat ligand18.vina.out ligand24.pdbqt ligand6.vina ligand12.vina ligand19.pdb ligand24.pdbqt.make.bat ligand6.vina.out ligand12.vina.out ligand19.pdbqt ligand24.vina ligand7.pdb ligand13.pdb ligand19.pdbqt.make.bat ligand24.vina.out ligand7.pdbqt ligand13.pdbqt ligand19.vina ligand25.pdb ligand7.pdbqt.make.bat ligand13.pdbqt.make.bat ligand19.vina.out ligand25.pdbqt ligand7.vina ligand13.vina ligand1.pdb ligand25.pdbqt.make.bat ligand7.vina.out ligand13.vina.out ligand1.pdbqt ligand25.vina ligand8.pdb ligand14.pdb ligand1.pdbqt.make.bat ligand25.vina.out ligand8.pdbqt ligand14.pdbqt ligand1.vina ligand2.pdb ligand8.pdbqt.make.bat ligand14.pdbqt.make.bat ligand1.vina.out ligand2.pdbqt ligand8.vina ligand14.vina ligand20.pdb ligand2.pdbqt.make.bat ligand8.vina.out ligand14.vina.out ligand20.pdbqt ligand2.vina ligand9.pdb ligand15.pdb ligand20.pdbqt.make.bat ligand2.vina.out ligand9.pdbqt ligand15.pdbqt ligand20.vina ligand3.pdb ligand9.pdbqt.make.bat ligand15.pdbqt.make.bat ligand20.vina.out ligand3.pdbqt ligand9.vina ligand15.vina ligand21.pdb ligand3.pdbqt.make.bat ligand9.vina.out ligand15.vina.out ligand21.pdbqt ligand3.vina receptor.pdb.pdbqt ligand16.pdb ligand21.pdbqt.make.bat ligand3.vina.out

Specifically, files of the form ligand*.vina.out are the AutoDock Vina output files. (Click to see an example of an AutoDock Vina output OUT file.) PDB files of the form ligand*.vina.out.best.pdb contain the coordinates of the best docked ligand. (Click to see an example of this type of PDB file.)

[user@cluster generation_8]$ cd ..
[user@cluster run_dir]$ ls
BestLigands.log generation_1 generation_2 generation_3 generation_4 generation_5 generation_6 generation_7 generation_8 generation_9 receptor
[user@cluster run_dir]$ cat BestLigands.log
...
./generation_6/ligand1.pdb -12.2
./generation_6/ligand2.pdb -12.17
========================================
TIME OF COMPLETION: 10-09-2008 21:28:30

./generation_7/ligand23.pdb -14.07
./generation_7/ligand28.pdb -13.03
./generation_7/ligand21.pdb -12.99
./generation_7/ligand1.pdb -12.54
./generation_7/ligand19.pdb -12.5
./generation_7/ligand2.pdb -12.5
./generation_7/ligand3.pdb -12.47
./generation_7/ligand33.pdb -12.46
./generation_7/ligand4.pdb -12.43
./generation_7/ligand5.pdb -12.41
========================================
TIME OF COMPLETION: 10-10-2008 01:31:58

./generation_8/ligand1.pdb -14.07
./generation_8/ligand17.pdb -13.35
./generation_8/ligand2.pdb -13.03
./generation_8/ligand3.pdb -12.99
./generation_8/ligand16.pdb -12.79
./generation_8/ligand35.pdb -12.73
./generation_8/ligand23.pdb -12.71
./generation_8/ligand4.pdb -12.54
./generation_8/ligand6.pdb -12.5
./generation_8/ligand5.pdb -12.5

The BestLigands.log file, contained in the working root directory, provides a summary of the AutoGrow results for each generation. The best ligands of each generation are listed with their corresponding AutoDock-predicted binding energies. This file can be a useful guide in navigating the results of the generation_# subdirectories. (Click to see an example of a BestLigands.log file.)

When run in “ExtractBest” mode, AutoGrow provides an easy way to extract and visualize the results of a given generation. Running AutoGrow in “ExtractBest” mode creates a new subdirectory in the working root directory called BestResults.#############, where ############# is a uniqueue numeric identifier. AutoGrow copies a PDB file of the receptor as well as PDB files of the best ligands of the specified generation into this directory for easy visualization or analysis.

[user@cluster run_dir]$ cd ..
[user@cluster AutoGrow]$ cd bin
[user@cluster bin]$ java Main -run_mode ExtractBest -parm_file default.prm -generation 8
ACTION: Loading INI file "default.prm"
      "working root directory" set to "/u1/AutoGrow/run_dir"
      "fragments directory" set to "/u1/AutoGrow/fragment/small_fragments"
      "scripts directory" set to "/u1/AutoGrow/scripts"
      "initial ligand" set to "/u1/jdur/nsc16209.pdb"
      "receptor" set to "/u1/jdur/1XDN.pdb"
      "number of carry overs" set to "10"
      "number of children" set to "20"
      "number of mutants" set to "20"
      "max number atoms" set to "70"
      "receptor location" set to "38.754 26.297 9.154"
      "receptor radius" set to "5"
      "wait time before rechecking if dlg files are done" set to "3600"
      "indecies of hydrogens that are not linkers" set to "15 18"
      "number of generations" set to "8"
WARNING: If you've used spaces in your directory names, this feature may not work.
Your best ligands have been saved to "/u1/AutoGrow/run_dir/BestResults.1223679656832"
[user@cluster bin]$ cd ..
[user@cluster AutoGrow]$ cd run_dir
[user@cluster run_dir]$ ls BestResults.*
BestResults.1223679656832
[user@cluster run_dir]$ cd BestResults.1223679656832
[user@cluster BestResults.1223679656832]$ ls
ligand12.docked.generation_2.rank_1.pdbligand13.docked.generation_2.rank_5.pdb
ligand16.docked.generation_2.rank_9.pdbligand18.docked.generation_2.rank_10.pdb
ligand1.docked.generation_2.rank_2.pdbligand23.docked.generation_2.rank_3.pdb
ligand2.docked.generation_2.rank_4.pdbligand3.docked.generation_2.rank_6.pdb
ligand4.docked.generation_2.rank_7.pdbligand5.docked.generation_2.rank_8.pdb
receptor.pdb
[user@cluster BestResults.1223679656832]$ vmd -m *