CheVi_Tree.Manual

the 3D molecular viewer recommended for eHiTS®User Guide forCheVi version 6.2 and aboveCopyright © 2006-2008, SimBioSys Inc. - All Rights Reserved. Contents1.Introduction2.Installation3.Working with CheVi1.Main Window2.3D Viewing3.Molecule properties4.Displaying proteins5.Displaying protein surfaces6.Displaying single or multiple molecules7.Superimposing molecules8.Viewing solutions for a docking job9.Displaying molecule surfaces10.Displaying ligand-receptor interactions11.Displaying ligand-receptor surface difference12.Displaying rigid fragments of a moleculeDocking with eHiTS from CheVi4.5.Input file formatsExporting high quality images6.7.Editing molecules and output file formats8.How-To...1.How do I use CheVi to look at eHiTS results?2.How do I close a solution in CheVi, the "File" -> "Close" seems not to be working?9.Bug Reporting1. IntroductionCheVi® (Che mical Vi sualizer) is a 3D molecular viewer primarily developed for the eHiTS® (electronic High Throughput Screening) docking tool, but suitable for many molecular viewing requirements.This user's manual covers the basic operation of CheVi and should provide all the information necessary to start using the program.The current beta version of CheVi is intended to provide users of eHiTS with the ability to view native eHiTS files (*.tma, *.sga, etc.) without the need to convert them to other standard file formats. It also gives the user the ability to examine eHiTS docking results, with corresponding eHiTS scores. CheVi is also able to view several other standard file formats, see section 4. "Input file formats" for details.This is a first generation beta version and is not intended to be a complete molecular modeling package, please check the SimBioSys website on a regular basis for updates of CheVi. SimBioSys values the input of users on all our applications, if you have any suggestions for additional features of CheVi, please contact us at info@simbiosys.ca2. InstallationUsers are advised to use the scripts provided with the CheVi package.Once the self extracting binary is downloaded from the SimBioSys web site (or demo CD), please use it in the following way:Usage: ./CheVi_version_platform.bin <INSTALL_DIRECTORY_PATH>To run CheVi follow the message given during installation. :<prompt>$ ./CheVi_6.1.dw9.4_Linux.bin <INSTALL_DIRECTORY_PATH>Unpacking CheVi files to <INSTALL_DIRECTORY_PATH>Installation successful!You can now run CheVi by typing<INSTALL_DIRECTORY_PATH>./CheVi_6.2/CheViat the prompt.3. Working with CheViMain Window1.The main window of CheVi consists of three areas. The graphical display area on the right displays themolecules/surfaces/etc. The left side bar is split into two areas, the navigation window, on top, and the controlsection, below.The navigation window provides an interface for navigating the various elements (receptor, ligands, solutions, surfaces, interactions, etc) used in a docking job from eHiTS, hence its named. These various elements are displayed in a tree-like structure clearly indicating what each element belongs to. This section also allows opening and closing of various file types supported by CheVi.The control window displays a set of properties that the user can alter to suit his/her own personal viewing preference. Depending on which item is selected in the navigation window, different sets of properties will show up to be edited by the user.3D Viewing2.Zooming, rotating and translating the image is controlled by the mouse."Left click + mouse movement" for rotating"Middle click + mouse movement" for translating"Right click + mouse movement" for zoomingMolecule properties3.All molecules opened in CheVi (see input file formats) are listed in a tree like structure on the navigation window (top-left section). To modify the display properties of each molecule, you must first highlight that molecule element by clicking on it.Upon highlight, the control window (bottom-left section) displays the available display options to view the molecule.Display options:Color: The color menu allows you to change the color scheme of the molecule. Each color scheme changes the color of the carbon atoms to the specified color.Display: Under the display menu you can switch the display from a ball and stick mode to a line drawing mode.When in ball and stick mode, double clicking on the molecule name will open a menu that allows you to alter the size of the atoms (balls) and bonds (sticks).H/Lp: The H/Lp menu allows you to toggle on or off the hydrogens and lone pairs.Labels: Under the Labels menu you can choose various text labels to appear on the molecule (if they were present in the input). These include the ID number, atomic number, residue label and Atomic symbol. Displaying proteins4.To open a protein click on the "Open" button (or use File -> Open ) and traverse your local directory system to find the molecular file you wish to open, and click “Open” or hit the return key.The default mode of CheVi is to view proteins (and all molecules) in ball and stick mode. This can be changed by clicking on the name of the protein(molecule) and selecting the “Line” display “Mode” from the Control window.In a similar manner the color mode of the protein can be changed. NOTE: the color mode alternates automatically for each new molecule opened.eHiTS users will find opening "preprocessed" receptor sites useful when examining docking results. eHiTS, by default, stores all input molecules in native eHiTS file formats under the $HOME/ehits_work/preprocessdirectory.Receptor files can be found in $HOME/ehits_work/preprocess/receptors/<PROTEIN_NAME>/ directory. The files of interest are:1. <PROTEIN_NAME>_protein.tma; the input receptor (complex) converted to tma format, if a complex isused, this will be the "split" receptor with no ligand or waters (see eHiTS manual for more information).2. <PROTEIN_NAME>_protein_clip.tma; this is the clipped receptor, based on the clip file given, and is theactual receptor active site that is used during the docking. This file is often much smaller than the full protein and therefore easier (faster) to view.3. <PROTEIN_NAME>_protein.sga; the SGA file is the surface of the active site as determined by eHiTS.4. <PROTEIN_NAME>_ligand.tma; if eHiTS is ran using the "-complex" option, then eHiTS splits the ligandfrom the receptor. This file is the converted .tma of that split ligand. It is also the reference for the clip box and used as the comparison for RMS calculations.Note: the *.tma files have all the hydrogens and lone pairs, as perceived by eHiTS if they were not included in the input.Displaying protein surfaces5.To view a receptor surface, as calculated and used by eHiTS, click the open button and traverse to the appropriate directory (typically $HOME/ehits_work/preprocess/receptors/<PROTEIN_NAME>/). The eHiTS surface file is saves as a .sga file. First you must change the "Files of types" selection in the open window from "*.pdb, *.mol, ...etc." to "*.sga, *.sgb". Then click on the surface file and select open.Note that it is often important to change the opacity of a surface (so you can view ligands within the surface).This can be done by adjusting the sliding bar in the properties window (under the molecule managementwindow). Note, you must have the surface selected (highlighted) to see this option.In addition to the .sga surface grid file, there is an associated .fga file that contains information about the surface point types used during the eHiTS docking process. When you open a surface grid file (.sga) CheVi will look for the associated .fga file (it will look for the REC_protein_clip.fga file) If it finds the correct .fga file, the surface will be colored based on the surface points of eHiTS.This feature is very useful in examining the interactions found during docking. Becoming familiar with the color scheme of the surface points can help select "good" binding ligands and aid in determining ways to optimize a lead. The legend for the colors is shown in the left-bottom frame.The surface point coloring can be turned off by unchecking the "Color Surface Point Types", this will show thesurface in grey scale. Please see pictures below for color and grey scale protein surfaces.Figure: Showing the interaction color coded clipped protein surface and the grey scale clipped protein surface for1azm.pdb complexTo make viewing binding or docked ligands in the receptor site easier, there are the "Hide Frontface" and "HideBackface" options. These will remove the side of the surface facing the front. Both front and back face options are there since different input refer to different sides of the surface as the front. Thus you may need to try both to get the desired effect.Under the Grid Type pull down menu there are several different grids used within eHiTS. Each can be viewed and analyzed by clicking on them.Surface points can also be displayed by clicking on the “Surface Point” button located at the control window (bottom-left). Each surface point is drawn as a cone shape pointing at the direction of the normal. The color of the cone denotes the type of the surface point as found in the legend in the control window.Two hidden functionalities that have not been exposed with buttons are to show the neighbours of the surface points and to show the atom of the surface point. With the appropriate control for the surface shown in the control window, pressing “Ctrl+W” toggles the surface point neighbours on or off. They are drawn as white wired lines between surface points. “Ctrl+S” toggles the surface point and atom lines. They are drawn as cyan wired lines between surface points and atoms in the molecule.Displaying single or multiple molecules6.Displaying single or multiple molecule files is the same as displaying a protein file. Open the desired file using the open button and traversing to the desired molecule file.If you are opening a multiple ligand file (*.sdf, *.mol2 or *.tma) you will see a properties and navigation window open below the molecular management window. To navigate through the multiple ligands, click on the arrow buttons next to the "Superimpose" button. You can "jump" to a specific molecule by clicking on the "N of M"text box and typing the number of the ligand you wish to see then pressing enter. You can also “jump” to a specific molecule by clicking on the N-th molecule on the Tree.Under the navigation buttons, there is a properties window that shows information from the input file. In an sdf file all the tags and data will be shown in the table. If the sdf file is eHiTS output then the eHiTS docking score will be part of this information (allowing users to examine the scoring of eHiTS).Superimposing molecules7.When viewing a multiple ligand file, you can superimpose selected molecules for comparison purposes, this could be especially useful in examining different poses of a docked ligand. To superimpose molecules to go the top level of the molecule set (called "Solutions" in the picture below and is highlighted in blue), navigate to the molecule of interest (by clicking the arrow keys or typing the number in the N of M box) the click on the"Superimpose" button. You can also change the color of each ligand to help in viewing clarity.Superimposed molecules are highlighted in grey on the tree so you know which molecules are currentlydisplayed. The current molecule would always be highlighted in dark grey as shown in the picture below.Figure: An explanation figure on how to superimpose moleculesOnce you have selected a molecule to superimpose, to remove it, navigate back to the same molecule and click "Superimpose" button again. The molecule number that has been selected to be superimposed is shown in the properties table, called "Superimposed".Viewing solutions for a docking job8.Solutions of a docking job are usually saved in$HOME/ehits_work/results/<RECEPTOR>/<LIGAND>/ehits.tma for the particular receptor and ligand docking job. If you attempt to open the results file in the results directory under ehits_work, with a filename of“ehits_best.tma”, “ehits.tma” or “solutions.sdf”, the entire docking job tree will be created for display. A solution parent node, with receptor, ligand, and the eHiTS solutions child nodes. Expanding each of these child nodes will display that particular molecule for you.This pre-populated tree is a convenience function for the eHiTS user. If CheVi finds the default files used by the eHiTS naming convention, it will populate the tree.Adding additional ligands to an existing solution view is also possible. Click on the eHiTS solution node in the tree structure and click on “add Ligand” button to select a ligand file to be added. If the newly opened ligand file is compatible with the receptor, you can view the interactions or surface difference between this ligand(s) and the previously opened receptor.The advantage of first opening an ehits.tma or a solutions.sdf is that the solution tree organizes the differentcomponents of a docking job into a tree like structure. Many additional information can be shown from this tree.One of the interesting ones include the ligand-receptor interaction points. This will be later elaborated in section3.10 "Displaying ligand-receptor interactions" of the manual.Instead of opening the fore-mentioned file names to get your solution tree, a new way (versions since Aug2006) is now capable of allowing you to select a receptor and a ligand file to open to form a solution tree. From the file menu, choose “Open Receptor/Ligand Pair” and fill up the 2 spaces with the receptor and ligand filenames respectively and click “Open”. Note that if you open a ligand that is not compatible with the receptor, interactions and surface difference may not be generated correctly or at all.Displaying molecule surfaces9.A useful piece of information when analyzing docking results is to be able to see the surface of molecules. CheVigives you the ability to show surfaces for receptor or small molecules. The surface generated is based on the exact surface eHiTS would use during the scoring phase of docking. The surfaces are colored by "Surface Point Type" as defined in eHiTS. For more information of surface point types, please see the eHiTS documentation.To display surfaces, expand the molecule node in the navigation tree. Then expand the surface node (by click on the +). For small molecules this will generate a surface around the ligand. For receptors, the surface should be precalculated in eHiTS preprocess directories and will be read from there.Once the surface is generated for the molecule, it has a similar control as was described in section 3.5"Displaying protein surfaces" in this manual.Displaying ligand-receptor interactions10.The key interaction being made between a ligand and receptor can give the user a lot of information about why the molecule is docked in the pose shown. When looking at an eHiTS solution (by opening either thesolutions.sdf or ehits.tma from the ehits results directory) CheVi allows the user to see the strong interactions between the ligand and receptor.Interactions between the ligand atom and the receptor atom can be shown from within an eHiTS solution tree (see section 3.8 "Viewing solutions for a docking job" for more details). Within a solution tree, each ligand and solution has a child node named “Receptor interaction”. By expanding this node below the molecule, dotted lines will be drawn between the ligand atom and the receptor atom.These lines are colored based on the type of interaction it is. A color legend similar to the one used to color the surface is displayed in the control window (bottom-left).Figure: Interaction lines for the ligand of the 1azm.pdb complex. For interaction number 4, whose type is H on aliphatic (chain) hydrophobic carbon, we also show the distance (4.12 A) of the ligand atom from the receptoratom.Please note that sometimes, an interaction may seem to be drawn floating somewhere off from the molecule. This may be caused by the fact that hydrogens and/or lone pairs of the molecule may not be displayed. Please refer to section 3.3 "Molecule properties" for detail on how to display them.There is an information table in the control window of the interaction display that enumerates some of theproperties for the specific interaction. Eg. The angles of the interaction, the distance, the score, as well as their end atom pairs of the interaction. The score value that is displayed here describes the strength of the specific interaction. Please note that this score does not include atom based contributions, like van-der-Waals force, steric clash, etc, which are being accounted for in the final score for the pose.If you wish to view all the interaction information, simply click the “Export All Info” button to select a file to save all the information into an ascii text file.Displaying ligand-receptor surface difference11.Obtaining useful information from the ligand and receptor surfaces at the same time may sometimes be difficult, especially when both surfaces are relatively close to each other. The surface difference feature shows onlysurfaces of both the ligand and the receptor which are sufficiently close to each other within a specified threshold, measured in Angstrom.Clicking on the “Surface Difference” node of either the original ligand or the docked solutions in the navigation tree will display a set of controls at the bottom left corner of CheVi. The threshold can be modified using the Threshold slider here. The exact measurements are indicated by the number to the right of the slider.Figure: The difference surface of the first docked solution and the receptor of 1azm.pdbAlso, you are able to control the opacity of the surface by sliding the opacity slider. Opacity values range from 0(invisible) to 100(solid)By default, the surfaces are color coded by interaction types. The different types of interaction and itscorresponding colors can be found in the legend at the control window(bottom left corner of CheVi).You can also color the surface difference based on score. Select “Score” from the “Color by” menu in thecontrols section and a legend will appear on screen mapping colors to their specific scores. If you would like to fine-tune this coloring, the min and the max sliders allow you the ability to tune the score colors that you are interested in, so you can zoom in to a specific range of scores for a more detailed perception of the surface. To go back to the default scoring range, just hit the “Default” button.The surface difference can be shown only from within an eHiTS solution tree (see section 3.8 "Viewing solutions for a docking job" for more details). Within a solution tree, each ligand and solution molecule has a child node named “Receptor surface difference”. By expanding this node below the molecule, the surface difference will be drawn between that molecule and the receptor.Displaying rigid fragments of a molecule12.Rigid fragments of a molecule can be seen by expanding the “Rigid Fragment" node beneath the molecule on the display tree. Each rigid fragment is drawn as a polygon and color coded by their chemical features detailed by the legend on the bottom left corner.You can view all of the rigid fragments at once, or select from the drop down which rigid fragment you are interested in. Reducing the opacity of the display may help you see what's underneath the rigid fragment representation.Labels are also available to uniquely identify each piece of rigid fragment used inside eHiTS during its computation.(a)(b)(c)Figure: Ligand of the 1azm.pdb complex in picture (a) fragmented in picture (b) and the fragments shown with an opacity setting of 20% to show both the ligand and the rigid fragments at the same time.4. Docking with eHiTS from CheViBefore starting to do eHiTS docking in CheVi one must configure CheVi with the location of the eHiTS installation. To do this click on "Edit" -> "Configuration" under the main navigation window and set the location of the eHiTS installation directory as shown on the picture below.Figure: The first time you install CheVi and eHiTS you need to set the location of eHiTS for CheVi, i.e. configure thetool for the docking package you will be using.This configuration will be remembered afterwards, so no need to set it again in subsequent start ups of CheVi, only if CheVi or eHiTS is reinstalled then it needs setting again.To start a new eHiTS docking job in CheVi, go to the main navigation window and click on the "New eHiTS Docking" button. As seen on the picture below:Figure: The main window of CheVi, where a new docking job is started by clicking on the "New eHiTS Docking"buttonThis will bring us to a docking job set-up panel with six tabs. The various tabs are shown in the next picture.Tab #1: Input selection Tab #2: Output selection Tab #3: Parameters selectionTab #6: Filtering options Tab #4: Database options Tab #5: Parallel processing /distribution optionsFigure: A glance at all the 6 tabs that belong to "setting up a docking job".For explanation on each of the choices in the tabs please refer to the eHiTS manual. For simplicity purposes we will give an example on how to start an eHiTS job using "1azm.pdb". We will load "1azm.pdb" in the first tab from a local file system. "1azm.pdb" is a PDB complex, and by clicking on the "Complex" toggle button in the first tab the user will let the program automatically split the ligand from the receptor, define and prepare the cavity, populate all the tabs with default options, and by just clicking on one more button called: "Run eHiTS" the user should be able to start docking of the 1azm ligand (a sulfonamide drug) into the receptor of 1azm (oxo-acid lyase). This button can be clicked on from any of the 6 tabs. In the pictures above it is highlighted in the sixth tab, i.e. under the filter options, but can be done under the first tab as well.During the docking the progress is reported and any time the docking can be stopped or cancelled with the "Stop eHiTS" button. When the run is done, one can view the results by clicking on the "View Results" button. From then on the same viewing mechanism is valid as described in the previous sections.a) docking in progress b) docking is done, one can view theresultsFigure: Monitoring the docking job5. Input file formatsThe program support the following 3D input file formats:MDL Molecular files (mol) - note: must be 3D coordinates;SD file format (sd/sdf) - note: must be 3D coordinates;Protein Data Bank files (pdb);Tripos Mol2 files (mol2) - note: must be 3D coordinates;Tagged Molecule Ascii (tma) - native eHiTS format;Tagged Molecule Binary (tmb) - native eHiTS format.Steric Grid Ascii (sga) - native eHiTS receptor surface format;Steric Grid Binary (sgb) - native eHiTS receptor surface format;6. Exporting high quality imagesTo export high quality images of the display screen, use the File -> Export menu to open the export window. In the export window you can browse to find the location you wish to save the output, type the file name and choose a magnification level. The higher the magnification the higher the quality the image will be. Be aware, images can get very large and take up alot of disk space, 4-5 x magnification is often enough for most applications.7. Editing molecules & output file formatsAt this time, there are no Editing capabilities implemented for CheVi. Please make a request if you would like to see this feature implemented.8. How to...1. How do I use CheVi to look at eHiTS results?CheVi has be specifically designed to help users of the eHiTS docking tool examine docking results. To get the most out of CheVi, it is recommended that users open the eHiTS results from the ehits_work directory.Open ehits.tma or solution.sdf from $HOME/ehits_work/results/<receptor_name>/<ligand_name>/By opening this file first, you will create a "eHiTS Solutions" group in CheVi. This group automatically provides all necessary links between ligands and docked solutions, with the associated receptors and surfaces. This will make using CheVi much easier and provide more information.2. How do I close a solution in CheVi, the "File" -> "Close" seems not to be working ?The "File"-> "Close" button works only for the first level of children of the "CheVi" tree-root, as indicated by the red arrows in the picture below:Figure: How to use the "File" -> "Close" option9. Bug ReportingIf a bug is identified the user should submit the description of the problem to SimBioSys Inc. Additionally, if the input data can be provided to SimBioSys, that would be very useful.Please report your problems to us on-line at: "SimBioSys" -> "Support", on that page under the "Technical Support" section you will find the "submit" link to:http://www.simbiosys.ca/support/support-form.htmlTel: +1 416 741 4263Fax: 1 416 741 5084Address:Support StaffSimBioSys Inc.135 Queen's Plate Dr., Unit 520Toronto, ON, M9W 6V1 CANADAWe hope you enjoy working with your CheVi !This document contains proprietary and confidential information of SimBioSys Inc. The content of this document may not be disclosed to third parties, copied or duplicated in any form, in whole or in part, without the prior writtenpermission from SimBioSys Inc.。