Introduction
The docking simulation can be carried out using several different search methods, involving many possible parametric refinements. Preparation of the molecules also depends on various sets of parameters.
To simplify the setting up of an AutoDock run, we have developed a graphical user interface called AutoDockTools. This leads the user through the preparation of the input files, helps to start the various programs, and helps to analyze the results. AutoDockTools, or "adt", consists of five modules which build on the Python Molecular Viewer, "pmv". AutoDockTools can be started from the Unix prompt using the command:
> adt
To get started with adt, the user needs to know a few basic things about pmv...
Pmv Basics
Starting pmv opens a Molecular Viewer which is composed of two or more menu bars at the top, a viewer in the center and a message box at the bottom.
 | - | - Menu bars |
| - | - Viewer window | |
| - | - Message box |
The Menu Bars
- The menu bars contain a collection of menu buttons with labels such as `File', `Display', `Color', etc. These menu buttons give the user access to menus of commands or to check buttons for specialized uses. The menus can be `torn off' by selecting the dashed line at the top. Some entries in the menus give access to a second list of commands via cascading menus. This is indicated by a small triangle on the right. Torn-off menus can be closed with the right mouse button.`PyShell', a check-button located at the left of the lowest menubar, opens a Python interpreter. The `PythonShell' opens automatically with an error message when an illegal operation occurs. Users familiar with the Python debugger, pdb, can use it to get useful information about what may have caused the problem.
Menu buttons for the five adt modules are loaded into a tan menubar, and are labelled `Ligand', `Grid', `Docking', `Run' and `Analyze'.
Viewer Basics
The DejaVu Viewer-object is a fully functional visualization application providing control over a variety of rendering parameters such as: depth cueing, rendering modes (points, lines, polygons), shading modes (flat, Gouraud), multiple light sources, arbitrary clipping planes etc. Geometries to be visualized can be handed to a viewer object to be displayed and transformed. More information about these advanced properties may be obtained from the DejaVu Tutorial.
The viewer has default key-stroke bindings which allow the user to reset, normalize and center the scene. The user must press these keys while the cursor is over the viewer, to have the desired effect.
The viewer has default mouse bindings for the trackball object, which allow the user to rotate, translate or scale objects in the scene; the effect of each mouse button is also modifed by the <Shift> keys:
| Modifier Key | Left Mouse Button | Middle Mouse Button | Right Mouse Button |
| (None) | Pick | Rotate. | XY-Translate. |
| Shift | Set the center of rotation. | Scale. | Z-Translate. |
Owing to perspective, the Z-translation may appear like a scaling operation, but it is not. You can tell the difference by doing a Z-translation away from you: hold down the <Shift> key and the right mouse button, and move the cursor to the left or downwards in the viewer window. If you have depth-cueing turned on (press the <D> key), you will see the object not only shrink, but also fade into the dark fog.You can set the rotation center of the current object by picking on any vertex in the scene with the left mouse button, while holding down the <Shift> key.
The Current Selection
Most pmv commands operate on the set of objects the user has currently selected. Selection is performed using the `Select' menu. By default, the selected vertices are indicated by yellow crosses. An example of the use of the selection is shown in the image at the top of thispage. To make the small molecule more distinct, it was selected using the `Select : Direct Select : Molecule List...' option. Then its display was changed using `Display : SticksAndBalls'.
Self-Logging
The user should note that all actions in adt log themselves in the message area below the viewer, and also in a file. Scripts may be built using these log files, and sourced in adt using the `File : Source' command, in order to replay a sequence of commands. By default, each session writes a log file of all the commands used in the molecular viewer into a file called `mvAll.log.py'. To prevent this from being over-written in a subsequent session, the user should save this by copying or moving this to a different filename.
Commands Executed at Start-Up
Sequences of commands, which the user wishes to be executed every time the adt is used, may be kept in a `.pmvrc' file which Pmv will access on starting. This is normally stored in the user's home directory.
Loading Other Functions
Also, Pmv is modular, customizable and extensible. This means that the user is able to add new functions to the viewer while working. For example, the `measure' module is not routinely loaded when adt is started. If the user wanted to measure the distance between two atoms, this module can be loaded using the `File : Load Module' command. Likewise, individual commands may be added using the `File : Load Command' option. Macros, such as `showHideDejaVuGui', one of four macros in `DejaVuMac.py' which gives the user access to the advanced viewer properties mentioned above, can be loaded using `File : Load Macros.'
Ligand Tutorial
Example: HIV-1 Protease Inhibitor, XK-263
This example shows how to use the ADT interface to Ligand to format a small molecule, in this case, an HIV-1 Protease Inhibitor, XK-263. The following sections describe each of the menu options in the Ligand module.
Ligand :
Input Molecule
- as shown below, this opens a file browser to facilitate selecting the ligand. Notice these things about this type of file browser:
- Clicking on the bar at the right of the 'Files of type:' button shows a list of alternative file types. Currently the browser is listing files of type 'pdbq'. A 'mol2' or 'pdb' file type could be selected here.
- Activate current choice by clicking on 'Open' button or 'Return' keystroke.
- NB: All atoms in the molecule must have their valencies are completed and partial charges added. Ligand adds polar hydrogens and charges of either Kollman or gasteiger type. The total charge on each 'residue' in the ligand must be an integral value. Ligand checks the total charges and notifies the user if there is a problem. The user must edit the final output file to correct any charge error. (In the case of non-peptide ligands, all the atoms in the ligand are grouped into one residue by the Molecule Viewer's parsers.)
- Selecting xk.pdbq results in displaying this molecule in the Viewer and in setting a number of Ligand specific values stored in a dictionary, `mv.atorsDict'.
Read Molecule
Choose Molecule
- use this option when the molecule has already been read in to the viewer.
Rigid Molecule
- In specialized applications, the user may want to dock a ligand with no rotatable bonds.
This option writes a new file with the necessary ligand-specific keywords required by AutoDock added.
Ligand :
Define Rigid Root
Autotors formats the ligand file inserting keywords based on the metaphor of a tree. The 'root' is defined as the fixed portion of the ligand, from which rotatable 'branches' sprout. Branches within branches are possible. Nested rotatable bonds are rotated in order from the 'leaves' to the 'root'. The 'root' is set either to an atom picked by the user or automatically to the atom which is considered to be in the center of the molecule with the most 'balanced' subtrees. The root atom is marked in adt by a large green sphere. [Please note here that the visibility of this sphere may be toggled on and off via the last menu entry in the Ligand menu: 'hide sphere(s) marking root atom(s)']
By Picking
The user sets the root to a vertex by 'picking' it with the left-mouse button. In the image below, the user has selected C7 as the root atom.Automatically
AutoRoot detects which atom in the molecule has the smallest 'largest-subtree'. (for more details, see reference manual)Show Root Atoms
atoms contiguous with the picked atom up to the first 'active' torsion are considered part of the 'root' by Ligand. Visualizing this expansion consists of marking adjacent root atoms with small green spheres. The user may toggle this visualization on and off.
Ligand :
Define Rotatable Bonds
To allow flexibility in the ligand, AutoDock can handle up to MAX_TORS torsions, which is set to 32 but can be changed by recompiling the AutoDock source code. Bonds in cycles and bonds to 'leaf' atoms are not able to be flexible in AutoDock. All other bonds could be. This portion of Ligand consists of deciding which of the possible torsions to model as flexible.During this phase, bonds are color-coded to show which cannot be flexible: colored red, which are currently active: colored green and those which could be active but have been inactivated by the user: colored purple. Labels for atoms in bonds which could be flexible are composed of the atom name and its number.
A separate toplevel widget, 'Torsion Count', facilitates these actions. It includes a display of the total number of currently active torsions, buttons to Disallow Peptide Backbone Torsions' and 'Disallow Amide Torsions' and a button to stop labelled 'Done'. The total number of current active torsions is displayed. Inactivations in this phase are reversible.
When the user is finished defining rotatable bonds, he clicks 'Done' which closes the 'Torsion Count' widget, restores the display and removes the labels.
Ligand :
Aromatic Carbons :
Calculations based on the force field used in AutoDock treat planar carbons differently from aliphatic carbons. For this reason, Ligand checks carbons in rings for planarity. Here, aromaticity is an all or none property: if some atoms in a ring fail the aromaticity cut-off, none of the carbons in that ring are considered aromatic.Rename Aromatic Carbons
Carbons in cycles in which all atoms are found to be planar are marked aromatic by changing their names to 'A...'. They are colored green in the Viewer and their element type is set to 'A'.Restore Aliphatic Carbons
Names, colors, and elements are restored for planar ring carbons.Set Carbon Names
Individual carbons may be picked, arbitrarily changing their name and display color.Change Aromaticity Criteria
The aromaticity cut-off is set to 7.5 degrees between the normals to adjacent carbon atoms in a ring. This value may be changed by the user.
Ligand :
Non Polar Hydrogens
The united atom model simplifies a docking by reducing the overall number of atoms to be considered. This is accomplished by merging nonpolar hydrogens with the carbons to which they are bonded. The partial charge of each non-polar hydrogen is added to the charge of its carbon and then the hydrogen is 'eliminated' from the molecule. In the viewer, the bonds between the carbons and their hydrogen neighbors are removed as are the hydrogen atoms themselves.
Ligand :
Write PDBQ ... :
In writing the formatted output file, the convention is to name this new file with the extension 'out.pdbq'. Here we wrote xk.out.pdbq. This file contains the necessary keywords to mark ROOT and BRANCH parts of the ligand. Please note, Ligand changes the order of the atoms in the output file because they are written starting with the root atoms and followed by the rest as encountered in a breadth-first order traversal of the branches. The atoms are renumbered. Non-polar hydrogen atoms are not written if they are merged when output file is produced. If cyclic carbons have been converted to aromatic type, their names will reflect this change. The next output line contains another important keyword, TORSDOF, which is is the number of torsional degrees of freedom initially detected for the molecule (and is not changed by toggling torsions). The first lines in the output file include information for AutoDock about the flexibility of the torsions and begins with the keyword 'REMARK'. CONECT records are written at the end of the file.
Ligand :
Show Ligand rootSpheres
Visibility of the large green sphere which marks the current root atom and the smaller ones which mark root expansion can be changed with this menu entry.
Ligand :
Automatic autotors setup
This option allows the user to prepare a ligand for AutoDock in one step, assigning charges, possibly merging non-polar hydrogens, lone pairs and disallowing amide and peptide-backbone torsions. This feature is particularly useful in scripts.
Grid Tutorial
Example: HIV-1 Protease Inhibitor, XK-263
AutoDock requires pre-calculated grid maps, one for each atom type present in the ligand being docked. These maps are calculated by AutoGrid. A grid map consists of a three dimensional lattice of regularly spaced points, surrounding (either entirely or partly) and centered on some region of interest of the macromolecule under study. Typical grid point spacing varies from 0.2Angstrom to 1.0 Angstrom, although the default is 0.375 Angstrom which is roughly one quarter of the length of a carbon-carbon single bond. Each point within the grid map stores the potential energy of a 'probe' atom of the grid map type that is due to all the atoms in the macromolecule. For example, in a carbon map a specific point represents the potential energy of a carbon atom in the ligand at that point in the macromolecule.
This tutorial shows how to use Grid to prepare a parameter file 'xk.gpf' to be used by AutoGrid to build grid maps.
Grid :
Macromolecule
Read Macromolecule
User select a new macromolecule . 'pdbqs', 'pdbq', 'pdb' or 'mol2' types can be used. AutoGrid requires 'pdbqs' type file which has both partial charges and solvent parameters added so charges, polar hydrogens and solvation parameters can be added as needed. There should be no nonpolar hydrogens or lone pairs in the macromolecule so these can be merged. Please note that the atom types in the macromolecule are checked vs a list of standard types: CNOSH. If an unusual atom type is detected in the macromolecule, the user is presented with the option of adding that type which entails changing the name and defining new energy parameters for the new type. Two new types, the first named 'M' and the second 'X', can be accommodated. The result can be saved as a pdbqs file.Choose Macromolecule
The user may select a molecule which is already present in the viewer.Merge NonPolar Hydrogens
This command merges nonpolar hydrogens of a selected macromolecule and allows the user to write a corrected pdbq(s) file.Add Solvent Parameters
This command adds solvent parameters a selected protein which has partial charges and writes a pdbqs file. (NB. solvent parameters are residue based.)
Grid :
Set Map Types
Set Map Types Directly
- The types of the maps to be calculated may be entered as a string. Possible types include: CNOPSHfFcbIMZ.
By Choosing Ligand
- Map types are set to the set of elements found in the choosen molecule.
By Reading Formatted file
- A new molecule is added to the viewer by reading the chosen file. As before, map types are set to the set of elements found in the molecule.
Set Parms For New Atom Type
- AutoGrid calculations are based on two sets of parameters: the equilibrium separation distance between the nucleii of two like atoms, 'Rij', and the pairwise potential energy, 'epsij'. Parameters for new atom types may be added to the current session via this menu choice. Also, this menu entry could be used to change default values for the standard types CNOPSHfFcbIM.
Set Up Covalent Map
Parameters for a covalent map can be set with this option. It entails setting the energy barrier height, its half-width, a constant for the Covalent Map and specifying the attachment atom.
Grid :
Set Grid
Setting the extent and center of the maps.
Grid :
Set Other Options
Choosing whether to model hydrogen bonds, whether to generate a floating potential map and what kind of dielectric constant to use
Grid :
Write .gpf ... :
Writing the grid parameter file
Grid :
Edit .gpf ... :
Editting the grid parameter file.
Grid :
Get values from a GPF
This allows the user to read in all the values defined in a previously prepared AutoGrid parameter file (or 'GPF').
Docking Tutorial
Example: HIV-1 Protease Inhibitor, XK-263
Using Docking to prepare a docking parameter file to be used by AutoDock for the actual docking.
Docking :
Set Macromolecule
Choose Macromolecule
If the macromolecule is already present in the Viewer, 'Choose Macromolecule' allows the user to select it via a MoleculeChooser.
Select Macromolecule Filename
'Select Macromolecule Filename' starts a file browser for selecting the macromolecule filename. The macromolecule must be in pdbqs format. NB: the chosen macromolecule is NOT read into the viewer by this route.
Docking :
- whether or not to use a floating point grid map
- how to set the initial state of the ligand's position and relative dihedral offset
- what coefficient of torsional degrees of freedom to use
- whether to specify initial dihedrals
- The GUI containing the Ligand Parameter Options opens when a new ligand is selected. It may be re-opened at any time with 'Adjust Ligand parameters'.
Set Ligand Parameters
Choose Ligand
If the small molecule is already present in the Viewer, use this option to pick it.
Read Autotors-Formatted Ligand File
'Read Autotors-Formatted Ligand File' lets the user pick a filename. This file must contain the results of Autotors: i.e. key words such as ROOT and ENDROOT are correctly placed , torsion activity has been set and the number of torsional degrees of freedom is included on the last line.
Adjust Ligand parameters
Ligand Parameters which can be set by the user include:
Docking :
Set Search Parameters
The following figures show the menus and dialog boxes used to set up various types of dockings.
Simulated Annealing Parameters
Genetic Algorithm Parameters
Local Search Parameters
Docking :
Set Docking Run Parameters
Docking :
Write DPF
Write the docking parameter file for the chosen algorithm.
Docking :
Edit DPF
allows the user to view and make changes to the docking parameter file.
Docking
Get values from a DPF
Re-reading a pre-existing docking parameter file, using `Get values from a DPF', allows the user to re-use selections made previously.
Run Tutorial
Example: HIV-1 Protease Inhibitor, XK-263
Run :
Run AutoGrid :
Using Autostart to start AutoGrid and AutoDock runs. Select a macro to set host and executable. Hosts dictionary defines available macros. These may be added to the session via 'Edit Hosts Dictionary' or defined in the user's .adrc. The LocalHost is always available. Currently this assumes that the autodock executables are in the user's path and are called 'autogrid3' and 'autodock3'. This can be editted. Setting the program pathname Selecting the parameter file Selecting the log file for interactive queue machines, setting the job priority for nqe machines, setting the time limit and number of processes launching the job.
Run :
Run AutoDock :
Please Note: AutoDock3.05 (or later versions) must be used in order to look at docking results with the Analyze section of adt .
Run :
Process Manager :
- managing jobs on interactive machines
Run :
Edit Hosts Dictionary:
- add or delete macros which define combinations of machines and executables
Analyze Tutorial
Example: HIV-1 Protease Inhibitor, XK-263
- Using Autoanalyze to read in and visualize the results of a docking experiment.
Analyze :
Please Note: AutoDock3.05 (or later versions) must be have been used in order to look at docked ligand conformations with this section of adt .Read Docking Log
- Choosing the docking log
.
- Choosing which docked conformations to visualize: None, Input Ligand Only, Input and the best docked conformation of the best cluster, Input and the best docked conformation of each cluster or All of the available ligand conformations. (the number of available docked conformation is set by the output level keyword 'outlev' specified in the dpf)
Analyze :
Delete Docking Log
- Choosing which docking log to delete from a list of dockings which had been read into the molecular viewer.
Analyze :
Select Docking Log
- Choosing which one of the dockings present in the molecular viewer is to be the current docking log.
Analyze :
Choose a Docked Conformation
- Selecting a docked conformation from the current docking
Analyze :
Show Macromolecule
- Adding the macromolecule of the current docking
Analyze :
Show Histogram
- Summarizes results of current docking
Analyze :
Read directory of dlgs
- Choosing the directory. This command lets the user read in a group of docking log files without having to manually select each one. Each file with the extension '.dlg' in the selected directory is read.
Analyze :
Show Chart
- Choosing the docking logs to be included in chart
Analyze :
Get Output
- Choosing the docking logs causes output for each dlg to be put in a text window. Here is a sample result when two dockings were selected.
Analyze :
Show Grids Used For Calc
- Showing the grids used for calculation
- the bounding box of the grids may be visualized
Analyze :
Show Extra Grid
- Reading in an additional grid for comparison
No comments:
Post a Comment