GRASP
Graphical Representation and Analysis of Surface Properties
Manual for Version 1.04
Anthony Nicholls
October 1992
Section Contents Page
1 Introduction 1
2 Features 3
2.1 Subsetting 3
2.2 Color Coding 4
2.3 Surfaces 5
2.4 Electrostatics 7
2.5 Distance Calculations 8
2.6 Maps 8
2.7 Atoms 9
2.8 Bonds 10
2.9 Contours 11
2.10 Colors 11
2.11 Simple Property Mathematics 11
2.12 Objects 12
2.13 Pair-Wise Interaction (Matrix) Representations 13
2.14 Stereo/Split Screen Operations 14
3 Getting Started 17
3.1 Grasp Environment 17
3.2 Running Grasp 18
3.3 Dial and Mouse Movement 18
3.4 Data Files 19
3.5 The Textport 19
3.6 Exit 20
4 Menus 21
4.1 Display Menu 21
4.2 Build Menu 24
4.3 Calculate Menu 26
4.4 Mouse Functions Menu 33
4.5 Read Menu 36
4.6 Write Menu 39
4.7 Formal Subset Menu 41
4.8 Programs Menu 44
4.9 Set Parameters Menu 45
4.10 Miscellaneous Menu 47
4.11 Help Menu 48
4.12 Macros Menu 49
4.13 Quit GRASP 49
5 Command Line 51
5.1 Subsetting Codes 51
5.1.1 Negation, Ranges, and Concatenation in Subsetting Codes 51
5.1.2 Atom Subsetting Codes 52
5.1.3 Surface Subsetting Codes 54
5.1.4 Bond Subsetting Codes 55
5.1.5 Backbone Box Subsetting Codes 56
5.1.6 Pair-Wise Interaction (Matrix) Strand Subsetting Codes 56
5.2 Coloring 57
5.3 Precise Rotation and Translation 59
5.4 Listing Atom Properties 59
5.5 Altering Radii and Charges 60
5.6 History and ! Commands 60
6 Control Keys 63
7 Worked Examples 69
7.1 Color a molecular surface by electrostatic potential 69
7.2 Display surface potential and curvature side by side 69
7.3 Surface two interacting parts of a molecule and select the interface 70
7.4 Calculate the occluded accessible surface area between these parts 70
7.5 Display atomic B- values on a surface 71
7.6 Calculate and display effective dielectric from a single charge site 71
7.7 Calculate surface area by hydro-phobic and -philic residue 72
7.8 Find and display all residues within 3 Angstroms of an active site 73
7.9 Find the common volume between two superimposed molecules 73
7.10 Form a 6-helix bundle from a single helix 73
8 Future Developments 75
8.1 General Improvements 75
8.2 Intelligent DelPhi 76
8.3 Secondary Structure Display 79
8.4 Docking with Realistic Energies 80
Appendix A File Formats 83
A.1 Grasp Surface File 83
A.2 DelPhi Potential Map 83
A.3 DelPhi Charge File 83
A.4 DelPhi Radius File 84
A.5 Protein Data Bank (PDB) File and Grasp Variants 85
A.6 Grasp Property File 85
A.7 Grasp Script File 86
A.8 Grasp Macro File 86
A.9 Pair-Wise Interaction (Matrix) Energy File 87
Appendix B .init_grasp Commands 89
Appendix C Grasp Data Files 91
References 93
1 - Introduction
Grasp came about because I wanted to visualize electrostatic potentials at surfaces, in particular the surface of biological molecules. Barry Honig's lab is well known for the program DelPhi which calculates electrostatic potentials from the Poisson- Boltzmann equation, and has the led the way in applying this equation in structural biology. The program can be used to get productive quantitative numbers for a variety of biochemical phenomena but qualitative visualization had been limited to isopotential contouring, typically with a program such as Insight from Biosym Technologies. The limitation of such an approach is that such contours do not capture local topology or shape. They often extend significant distances away from the molecule while one would expect most of the 'action' to be close to the molecule, in fact at the surface of molecules. So I decided it was time to attempt a graphics program which emphasizes surfaces and electrostatics.
I would not have been so confident in starting this project had it not been for considerable groundwork laid by others, in particular Kim Sharp. He and Mike Gilson had devised a novel algorithm some years ago for calculating the molecular volume (i.e. water inaccessible volume) using a cubic lattice. This method, though not efficient when the lattice spacing is small relative to atomic radii, can be made rapid at lower resolution. Given the molecular volume, Kim had also reinvented a technique commonly known as the "Marching Cubes" algorithm to produce a surface tessellation. Putting these together in an optimized form produced a rough and ready surface description which could be easily visualized on a Silicon Graphics Iris (SGI) computer. The potentials at surface points could then be interpolated from the 3- D map produced by Delphi and color coded to indicate the result.
The initial results were surprisingly good, both in terms of aesthetics and usefulness. The large difference in dielectric between water and the interior of proteins modelled by DelPhi means that local electrostatic effects can dominate global ones. So, for instance, an active site can be negative even when the protein total net charge is very positive. This is seldom seen if Coulomb's Law is used to calculate potentials because of the long range nature of (1/r). Grasp was immediately able to display this consequence of electrostatic screening, for instance showing the deeply negative binding site of the catalytic magnesium of RNAse H, crystallized without that ion by Yang and Hendrickson.
So it was clear that this approach held some merit. The combination of surface shape and electrostatic potential was synergistic. Moreover I began to see that just having a rapid surfacing and visualization algorithm was useful. For instance it was simple using surface connectivity to display only the internal cavities of proteins. Here the initial use was the bacteriorhodopsin structure of Henderson which has numerous "holes" surrounding the retinal moiety.
It was also instructive to "project" properties of the underlying atoms onto the surface and color code them, an example being the B values normally accompanying crystallographic structures. So I began to see the surface itself as useful construct, regardless of electrostatics. This became a central tenet of Grasp, that surfaces and atoms should be treated with equal importance.
There was still a need for other electrostatic representations, such as isopotential contours, projection planes, field lines, etc. Also, since typical use of the program was visualization of large molecules with thousands of atoms, I devised a simple representation for those atoms that was fast to display and could be colored by property. This led to other representations of atoms and groups of atoms.
The program grew beyond my initial plans. Hopefully, however, the program maintains a coherent philosophy. For instance the use of surfaces both for displaying properties and as objects in their own right, the visualization of electrostatic properties, and more lately the generalization of the idea of an object representing both a set of atoms (as the surface does) and a property (such as electrostatic potential). An example of the latter is the DNA representational project of Rex Bharadwaj. Here DNA bases can be represented as elongated boxes whose width can represent a property associated with that base, such as base twisting, sliding or rolling.
The program has achieved most of the goals I had concerning the development of these ideas. Of course in their actualization they have spawned many more. But hopefully the present version is at least complete enough to be useful.
Comments as always are much appreciated.
Anthony Nicholls
October 1992
2 - Features
Grasp uses a perspective-based view, which means things farther away from the eye are smaller. To enlarge a view, one simply moves it closer to the eye. Manipulations are by mouse or by dials. Molecules are mapped to a "unit box" which can be displayed with the front side removed. There are also embedded cross- hairs to remind the user of any rotations and translations they have applied. The default clipping planes are very close to the "eye" position and very far away. These can be altered via a slice control tool (section xxx). The background is either black or that produced by the unit box. The default window size may be changed in the usual window resizing manner. There is also a fullscreen option where the entire screen is used by the display. All functions are accessed by hierarchical menus via the right mouse button, or via the command line (section 5). Commands may also be read in from a script file (section A.7). All display objects (surfaces, atoms etc.) are independent - they can all appear at the same time or be individually hidden from view.
2.1 - Subsetting
A central feature of Grasp is the ability to specify a subset of atoms, surface vertices, bonds, objects, etc., based upon a very wide range of properties.
The first method of selecting a subset is by typing property subsetting codes on the command line or in response to a menu query. Properties which can be used for atoms are atom name, atom number, residue name, residue number, residue projection, chain name, charge, radius, potential, original coordinates, screen coordinates, general properties 1 and 2 (which can be assigned any number desired), molecule number, accessible area, distance, formal subset name, and discrete atom color. Properties for surfaces are potential, original coordinates, screen coordinates, general properties 1 and 2, distance, formal subset name, suface number, curvature, vertex number, and discrete vertex color. There is a deliberate similarity between these two lists based on the program philosophy of equality between surfaces and atoms.
The general property fields can be used in a variety of ways. For instance any atom property can be mapped to a surface and stored (and hence displayed) as general property 1 or 2. Or the user can produce a new quantity out of others by the simple property mathematics utility. Or properties can be imported.
Variables are either characters or numbers. The latter may be specified as ranges, for instance one can select all atoms which have a residue number between 5 and 10 or a charge greater than zero. Character variables (except formal subset names) may include wild cards, so one can select all carbon atoms or all carbon atoms which have the character "1" in the third position of the atom name. There are also short cut names for atoms in a protein backbone or in side chains, and for residues which are ionizable, hydrophobic or hydrophilic. All specifications can also be negated, so that one can select all atoms that are NOT carbon atoms.
The purpose of subsetting depends upon the context. One of the simplest uses is to alter the display color of a subset. For instance, one might want to employ a color scheme which displays all positively charged atoms one color and all negatively charged atoms another, or all hydrophobic residues yellow and all hydrophilic purple, etc. Colors are specified by the index number (0- 99) assigned to each color in Grasp.
Another use of subsetting is creating a formal subset. Formal subsets are assigned names, either by the program, in which case a hierarchical naming convention is used, or by the user. Formal subsets may be spatially manipulated independently of the rest of the surfaces/atoms. They can also be referred to by name in all subsequent operations. Formal subsets may be sets of atoms or portions or collections of surfaces, or may have mixed character - a surface may be associated with a set of atoms, or a set of atoms associated with a surface. For instance, as well as selecting an active site surface one might want to associate all atoms which are in contact with that surface.
Most other subsetting uses depend on the action being undertaken. For instance, when the surfacing subprogram is activated the user has the option to enter a subset of atoms. One could surface a single helix in a protein.
Most subsetting codes are exclusively AND based - subsetting by progressive refinement based upon properties. The reason for this is that one of the most useful applications of Grasp is using it to look for correlations. So one might want find all residues which are a certain distance from the molecular surface AND charged.
The second menthod of selecting a subset is "scribing" the surface. This is under menu control and allows the user to "draw" upon a surface the border of a region of interest with the mouse cursor in much the same way in which one might with a Macintosh- like draw program.
2.2 - Color Coding
Grasp supports two different modes of color coding.
The first color coding mode, 3 color continuous, requires three numerical values, called "control" values, along with three colors, one color per value (colors are defined by RGB triplets, or by an index into a list of colors). Color coding is then implemented as follows: If a number is less than the minimum of the three control values it is assigned the color associated with that minimum value. If it is greater than the maximum value it is assigned that value's color. If it is between the minimum and middle values the assigned color is found by linearly interpolating between the minimum and middle colors, and if it is between the middle and maximum values by linearly interpolating between the middle and maximum colors. By linearly interpolating is meant the following: Colors are made up of red, green and blue components, each component having a strength of 0.0 to 1.0. If a number is, for example, halfway between one value and another, then its interpolated color is similarly halfway between the two colors assigned to those values, i.e. its red, blue and green components are half those of one color and half of the other.
Grasp also supports 2 color continuous mode which is equivalent to 3 color continuous mode but with the middle value and color set to be the same as that of the minimum value and color.
Continuous color maximum, minimum and middle values may also be adjusted via a mouse activated widget. This is useful in rescaling the color code to bring out particular features on the fly. Independent widgets appear for each continuous property displayed. These also offer access to other features via drop-down menus.
The second color coding mode is zonal coloring, wherein a certain range of values is assigned a certain color. The color boundaries between different zones are sharp. This is also referred to as discrete coloring. Default colors are provided for all properties - for electrostatic potentials they are red, white and blue, with red for the minimum value (typically negative), white at zero, and blue for the maximum value (typically positive). However these colors may be also set by the user. Default maximum and minimum control values are taken as the maximum and minimum values of the property being represented (surface potential, atom distances, etc). The middle value is set to zero unless the maximum and minimum are both greater than or less than zero, in which case it is set to the average of those two values. These control values can also be explicitly altered.
2.3 - Surfaces
Grasp supports two types of surfaces, molecular and accessible. The molecular surface is defined as the boundary of that volume within any probe sphere (meant to represent a water molecule) of given radius sharing no volume with the hard sphere atoms which make up the molecule. The accessible surface can be defined as the locus of the centers of all possible such probes described above in contact with the hard sphere atoms. Alternatively it can be defined as the hard sphere surface if each atomic radius is increased by the probe radius. The default probe radius for each type of surface is 1.4 Angstroms. This can be changed by the user.
Everything which can be done with molecular surfaces can be done with accessible surfaces. Therefore except where differentiated they will both be referred to as molecular surfaces. The surfacing resolution, the lattice spacing used to generate the surface, is determined automatically. The lattice spacing used in the process is scaled relative to the largest dimension of the molecule, hence coarser lattices are used for larger molecules. This scaling has the advantage that the surface of very large molecules can be as easy to manipulate as that of small molecules. Though the surface of larger molecules will then be less accurate, one is often interested in coarser features of such molecules.
If the molecule has only a few atoms, this method can lead to a lattice spacing at which the method Grasp uses is inefficient, hence there is a minimum allowed lattice spacing. This parameter can be set by the user to force use of a coarser grid (as might be preferred to improve draw speed or to overcome memory limitations).
Surfaces can be constructed for all atoms or for subsets of atoms. The process takes a few seconds at most and results in a smooth tessellation of the surface which is colored white but shaded by the SGI lighting routines. This can be quite slow on some machines as there may typically be 20,000 triangles. To enhance drawing speed there are three other draw modes. The first is a rendered surface (the triangles are filled in) but the lighting calculations are simplified (pseudo- lit) and done in software rather than by using the SGI hardware calls. The second is a mesh representation, where the triangles are not filled in. The third is a points- only representation. The default surface produced by the program can be preset in the .init_Grasp file (see appendix B).
All displays of surfaces (and also contours, atoms and bonds) are depth shaded. This means that the farther away a part of the surface the darker the color. Its color is interpolated to black based on the distance from the viewer. Grasp uses a dynamic depth range, where the front edge, where interpolation begins, is determined by the nearest point on the structure to the viewer, and the back edge, the depth at which the color is set to black, is a fixed distance behind this point. Depth cueing makes a dramatic difference to the mesh representation, and to a lesser extent to other representations. Depth cueing parameters can be set by the user.
For the lit and pseudo- lit surfaces the direction of the incident light may be changed. Other material properties of the surface such as reflectivity, transparency, etc., are not currently user- configurable.
Surfaces are colored by assigning colors to each vertex. This can be done according to any value associated with that vertex. Alternatively, surfaces can be colored by selecting a subset and assigning a discrete color. There are many ways of selecting a surface subset based on vertex properties, associated atom properties, or by scribing. Any surface or subset can be "uncolored" i.e. undisplayed. Hence one can remove portions of surfaces to create "windows" into the underlying molecule. Any surface property can be interrogated using the mouse buttons - placing the mouse at any given point and clicking returns a value or values associated with the nearest surface vertex. Which property values are returned, and by which mouse button, can be set by the user.
Surface properties can be classified as those which can be used for subsetting and displayed, and those which can be used for subsetting but not displayed. Surface properties which can be displayed are generally calculated within the program and include electrostatic potential, curvature, distance (to another surface or set of atoms), and the two general property fields. The general property fields can be assigned other property values to make possible the display of properties which would otherwise be undisplayable. Surface properties which cannot be displayed are original coordinates, screen coordinates, discrete vertex color, surface number, formal subset name, and vertex number.
Surface potentials are interpolated from potential maps. Distances as a surface property are calculated either from another surface or surface subset, or from a set of atoms, and in each case are the minimum such distances. Curvature is as defined in Nicholls et al and is derived from a concept of local hydrophobicity. Briefly, each possible placement of a water "sphere" against the surface of the molecule reduces the accessibility of that water to other waters. Against a concave surface this accessibility is less than against a convex surface, and a formal correspondence can be made between contact to an arbitrarily complicated surface to contact with a sphere of a certain curvature. Curvature thus defined is a property of the accessible surface, but can be uniquely mapped to the molecular surface. When color coded it reinforces the effect of SGI lighting in that surface hollows are made distinct from surface projections, and so is useful in visualizing patterns of surface shape.
Surface data (which means vertex coordinates, connections, and normals), and any properties, calculated or assigned, of any surface or subset of surfaces can be written to a data file. These data files can be read in during program execution or at startup. Surface data can be appended to other files to make surface "libraries". Since subsets of surfaces can be saved one could, for instance, make a library of the surfaces of the active sites of different enzymes.
The property data of a surface or subset can also be saved as an ascii file for analysis, or for temporary storage. This file can also be read back in as a user-generated function mapped to a particular surface.
Surfaces or subsets of surfaces can have their surface normals inverted. In this way one can look at molecules from the inside. One can also do like- with- like comparisons of two surfaces which might form complexes by inverting one surface of the pair. Surface properties can also be inverted, for instance positive turned to negative and vice versa through the simple property mathematics utility.
Along with cavity surfaces (which can be thought of as a surface subset) and contour surfaces, one can calculate the area of any molecular surface or subset of a molecular surface, and similarly the volume enclosed (noting that the volume is not meaningful if the surface is not closed). The surface area for an accessible surface gives a measure which has often been associated with hydrophobicity, since it is related to the number of water molecules in contact with the molecule. Grasp also has a more accurate surface area subroutine for atom by atom accessible area.
Any surface or subset can also be attached to the rotation and translation dials alone. This creation of a formal subset can then be manipulated independently. This allows for parts of surfaces to be removed, compared, docked, etc.
2.4 - Electrostatics
Grasp includes a Poisson- Boltzmann (PB) solver which is a similar but simpler version of that used by DelPhi. The fields calculated by it are for qualitative use only. For quantitative use there is full support for the output from DelPhi, in terms of potential maps, dielectric maps, modified pdb files, charge files, size files, etc. Grasp does not yet contain an interface to DelPhi, hence that program has to be run separately.
The Grasp PB solver uses two 33 cubed grids, one nested within the other. The inner grid dimension is set to be larger, by the diameter of one water molecule, than the maximum x, y or z dimension of the collection of atoms used in the calculation. The second grid is twice the size of the first, with the same center. The potentials on the outer grid are solved for first, then interpolated and refined further on the inner grid. Potentials are then interpolated to a 65 cubed grid the same size as the outer grid. This final grid, or "map" as it is referred to, is then used in all subsequent calculations. It may also be written out in DelPhi form.
Although there is no choice in the sizing of these grids, the user has control of the inner and outer dielectric constants, the probe radius used to determine water inaccessibility, the salt concentration, and the ion exclusion radius. There is no support for the nonlinear equation, for periodic boundary conditions, membrane slabs and holes, or any other DelPhi features.
Once a map is calculated, it can be evaluated in several ways. Isopotential (also referred to as "through space") contours may be calculated at any value, given any color, and displayed as solid surfaces, meshes or points. Potentials may be interpolated at any molecular surface, and at any set of atoms (trilinear interpolation is used throughout). The electric fields may be calculated at a set of points and represented in magnitude and direction as three dimensional arrows. Molecular dipoles may be calculated and similarly displayed. Field lines can be calculated from a set of points, colored and displayed in 1- D or 3- D (lines or tubes). The potential may also be interpolated at a slice plane perpendicular to the Z direction (parallel with the screen). This latter display is updated as the map/molecule is moved, or alternatively as the position of the slice plane is altered.
Values at surfaces and atoms may be colored by 2 or 3 color continuous or by discrete colors. The Z plane will only show the former. Field vectors may have their magnitude encoded in their length. Field lines can be assigned directionality and color when calculated.
2.5 - Distance Calculations
Grasp will calculate minimal distances from surfaces to surfaces, from surfaces to atoms, from atoms to surfaces and from atoms to atoms. In the case of atoms there is also the option to subtract the assigned van der Waals radii from the distance.
An example of a novel use of distances in Grasp is to calculate a "depth" map, i.e. the depth of atoms from the surface to every atom. Distance maps are also useful in defining interfaces between domains, either surface- wise or atom- wise.
2.6 - Maps
Grasp contains room for two internal "maps", i.e. 65 cubed, cubic lattices. Internally generated maps are stored in the first of these arrays. Maps read in are put in the second array. Simple operations are allowed on and between maps, such as differences, sums, etc. Maps can also be swapped so that both can be internally generated or both externally generated by DelPhi. Difference maps are particularly useful to highlight the effects of changing parameters such as charge, radii, salt concentration, dielectrics, etc.
As one of the three primary external data files supported by Grasp (the other two being protein data bank (.pdb) files for atoms and surface representation files (.srf) for surfaces), maps may be read at startup, so that one can analyse maps without any atom data or surface data. Although maps are usually associated with electric potential, they can be used quite generally for any 3- D data, though at present Grasp requires the grid to be 65 cubed. For example, the consensus volume option in Grasp, finding the common volume between a set of molecules, results in values assigned to a 65 cubed grid which can then be manipulated and displayed as a potential map (e.g. Z- plane projection, isopotential contours). The dielectric boundary map or salt exclusion map from DelPhi can also be read in as this form.
2.7 - Atoms
Atomic coordinates are the fundamental data structure from which everything else is derived. Grasp does not contain any "build" utility and hence is dependent on external files for this data. Primary support is for PDB files, the standard crystallographic format, along with certain variants.
Atoms can be displayed in several ways. The traditional method, which is included in Grasp, is as spheres of a given radius. This is often referred to as CPK modelling. In Grasp the surfaces of the spheres are lit. CPK can be demanding on the graphics resources for large molecules. An efficient alternative is to represent the atom as a circle of the correct radius always oriented flat with respect to the viewer. With a little differential coloring these flat circles can be given an apparent three- dimensionality. There is also an option to color these circles with patterns. There is another representation which gives small, uniformly sized circles for use with bond representations. Spheres may also be drawn with lines or dots.
Atoms can be colored discretely - any subset of atoms can be assigned any color, or continuous color colding may be used. The properties supported for this are potential, distance, charge, and general properties 1 and 2. Atoms can be uncolored to remove them from view. Atom colors are depth shaded.
Upon reading a PDB file, radii are set to default values from an external file (which the user may edit). This file is in the same format as the control file for atom size used by DelPhi. Similar files may be read during program execution. Charges are 0 by default when a structure is read, but Grasp can read DelPhi charge files and assign charges based on the descriptions therein. Some sample files are provided, such as those to assign charges to each ionizable residue of a protein. Radii and charges may also be assigned via the command line by specifying a radius/charge and the subset of atoms to have this radius/charge. Keyboard commands also support intrinsic operations such as multiplication of radii/charges by constants, or addition of constants.
Since charges are only of importance for electrostatic purposes and since charge is also a display property, it may be utilized as a "dummy" variable, and actually represent another physical property. This becomes particularly useful when combined with the DelPhi control file format. For instance if one is interested in a per- residue property, say helix- forming propensity, a control file can be constructed with one line for each residue and its property value. This can then be read into Grasp, the atoms of each residue will be assigned a "charge" equal to that residue's helix- forming propensity, which can then be color coded and displayed.
Grasp also supports three variants on the standard PDB file which involve the fields to the right of the atom coordinates. These typically contain occupancy and B- values. One option is to read this information in as general properties 1 and 2. There is also an option to read these fields in as the radius and charge of each atom because this is what they are used for in DelPhi modified PDB files. Finally, for higher precision, the entire field to the right of the coordinates can be read, in free format, as general properties 1 and 2. Files in the these formats can all be written from within Grasp.
Separate molecules will be recognized from within a single PDB file if separated by "TER" statements. Each will be assigned an index, i.e. a molecule number, which as a property is analogous to "surface number" in Grasp. Molecules can be superimposed using the Kabsch algorithm, which gives the best rotation and translation (RMS- wise) between molecules or parts of molecules. The only restriction is that the same number of atoms from each molecule must be used to determine the minimum RMS difference. Grasp will not yet superimpose surfaces.
Grasp contains algorithms for calculating both the volume and surface area of molecules or subsets of atoms. Surface area can be either accessible area or that of the van der Waals surface. Control is given to the user over the precision of these calculations.
Grasp does not contain methods to alter structures such as torsional rotations, minimization, etc., with one key exception. Grasp allows independent rotations and translations of defined subsets, which may then be "fixed" relative to each other. For instance, a substrate may be selected and moved relative to an active site. Upon making the transformations, new surfaces, distances, electrostatic fields, etc., can be calculated based on the new coordinates. One can undo transformations which have not yet been "fixed".
Atom properties can be queried in the same way as surface properties, i.e. point and click. Atom properties can even be queried when covered by surfaces. The "atom picking" function can also be set to report geometric parameters such as distance, angle, and torsion angle between picked pairs, triplets, and quadruplets of atoms.
2.8 - Bonds
Bonding patterns are calculated upon reading in a pdb file. Bonds may be represented in three ways: lines, sticks, and cylinders. Lines are the traditional line drawings used by most programs. Cylinders are a three dimensional variant of this, the diameter of which can be set by the user. Sticks follow the method of Kuznetsov and Lim in which bonds are represented by quadrilateral tubes. The advantages of this approach are that the bonds are made significantly more three dimensional, inter bond angles are well brought out, and the display is relatively quick to draw.
Bonds can be colored based upon a preset pattern, upon transferring the discrete colors of the underlying atoms, or by subsetting based on the properties of those atoms. They can also be selectively undisplayed by being "uncolored". Bond colors are depth shaded. Properties of atoms can be queried by picking at bond ends.
2.9 - Contours
Isopotential contour surfaces can be constructed at any potential value for either internal map. Contours can be displayed in all the surface modes available to molecular surfaces: lit, pseudo- lit, mesh and points. They are also independently depth-shaded. Contours are not automatically recalculated if the parent map changes, though contours can be deleted and recalculated. Volume and surface areas may be calculated for any contour.
2.10 - Colors
Grasp supports 99 independent indexed colors. These can be set during program execution using a color palette, or in an external file as RGB triplets. All changes to colors are automatically saved (except for colors 91-99, which are always equal to the default colors 1- 9), thus the user can design their own set of colors or use those provided. Color 0 is always black and is also used as a flag to prevent display of that an object - an atom colored 0 is hidden. This "uncoloring" applies to surfaces, bonds, backbone boxes and matrix strands. Grasp also has undo and restore commands for atoms and vertices. Undo removes the previous coloring, while restore acts on objects colored 0 by giving them the color previously assigned. Once a color is assigned to an object it becomes a property which can be used in subsequent subsetting selections.
The use of assigned color as a property allows for some quite flexible subsetting. For example it can act as a bridge between atomic and surface properties. Suppose we want to find all vertices of a surface which are concave (have a calculated curvature less than zero)and which are formed by hydrophobic residues. One way to do this is to color all hydrophobic residues one color, transfer that color to the surface, then select all vertices which have that color AND which have curvature less than zero.
Color can be used to build up subsets based upon disparate properties which could not be specified in a single command. For instance we can select all atoms which are in a region of positive potential and belong to negatively charged residues plus all those atoms which are negative but belong to positively charged residues. This is a way to include an OR statement in Grasp's subsetting vocabulary.
2.11 - Simple Property Mathematics
Sometimes the properties calculated or imported into Grasp are not exactly what one is interested in. For instance one might be interested in not the surface potential interpolated from map one or that from map two, but some average of them (for instance weighted by the average ionization state of two residues). The same might be true of the maps themselves and one might like a combination of the two maps. Simple property mathematics addresses this by providing for arithmetic on one or two fields, putting the result in another or in the same field.
The operations available for maps include addition or division of two maps, along with multiplication by a constant and swapping the two maps. The operations for atom and surface properties include addition, subtraction, division and multiplication of two properties, as well as addition or multiplication of a single property by a constant. Also supported are special functions on a single field including square root, reciprocal, exponentiation, logarithm, cosine, sine, and hyperbolic functions.
More useful to some extent are the contraction operations which take a field and return a single value, maximum, minimum, average and sum. These can be combined with subsetting so that only portions of the selected fields are acted upon. For instance, one can find the accessible area of all lysines, or all charged groups, or all charged groups of a particular helix, etc.
Fields can be shifted around. For instance, one can multiply a field by 1.0 and place the result in a second field. This can be useful if one field is to be used as a dummy field. For instance, if charges were assigned to represent helix forming potential via a DelPhi charge file format they can then be passed on to one of the general property fields.
Properties can be inverted. One can invert the normals of a surface to make it appear similar to its complement. One can also or invert its electrostatic potentials since one might expect a complementary surface to also be complementary in potential. This is simply achieved by selecting the surface of interest and multiplying its surface potential by - 1.0.
Also included is a facility to map an atomic parameter directly to the surface. One advantage of this is that a surface is to some extent simpler than the collection of underlying atoms and as such is often a better vehicle for displaying properties. One further advantage is that by using the accessible surface one can project these properties into space away from the molecule.
2.12 - Objects
An object is an abstraction which represents both the shape and a property of a set of atoms. There are two for proteins and three for DNA.
The first protein object is a backbone trace called a "backbone worm". It consists of a set of cylinders forming a tubular B- spline though atom positions. When the command is made to build a backbone worm, the user is given the default option of using all alpha carbons of the protein backbone or entering a different set. This latter option might be used to select only a subset of all alpha carbons, or to select a totally different set of atoms like amide nitrogens.
If the user has previously constructed one or more worms, the user has the option of replacing all of these or adding to them. There may be up to one hundred disjoint splines constructed.
If two sequential atoms in the selection are more than a certain distance apart the spline is terminated and a new one begun. Hence, if constructing a backbone worm when the protein has more than one chain, there will be one spline per chain. The distance used to determine spline breakage can be set by the user. If set sufficiently large, this will force the construction of a single spline through disjoint chains. It can also be useful in judging patterns of distances of a certain subclass of atoms - spline breakage contains local distance information.
A B- spline segment is constructed from each set of four consecutive atoms in the selection list. Each segment is made of four subsegments by default. This can also be adjusted by the user. Note that this change in resolution only takes effect when a worm is built and does not alter the segment density in chains already constructed. Each subsegment is a tube of polygonal cross- section. The default number of sides to this polygon is ten, and this too may be altered by the user. Finally, the user may alter the radius of the cross section of the worm, i.e. the worm thickness. Changes made to these two parameters are reflected immediately in any worm already built.
One limitation to the subsegment density described above is that the number of subsegments per segment must be even. This arises from the method of assigning atoms to each subsegment. The procedure used is that the first half of the segment is assigned to the second atom in the defining four atom sequence and the second half to the third atom. Hence to be able to equally distribute subsegments there must be an even number of such per segment. Note that this method of subsegment distribution results in no segments assigned to the first and last atoms in a sequence, and only half segments to the second and second-to-last atoms.
The second protein object is a peptide plane representation called a "backbone box". As is well known, the peptide bond has double bond character and so is stiff to torsional rotations. As a consequence the set of backbone atoms CA(n)- C(n)- N(n+1)- CA(n+1) lie in a plane. This can be represented as a quadrilateral with corners at carbon alphas (CA) and at the oxygen and hydrogen of carbon (C) and nitrogen (N) respectively. This is given a little width for display purposes to make a quadrilateral box. These boxes can be colored in several ways. The default color scheme is white at the alpha carbons, red at the oxygen, blue at the hydrogen. In this mode it is easy to see, for instance, where backbone loops have all carbonyls or all amide hydrogens aligned in one direction (which can be significant electrostatically). It is also makes secondary structures particularly clear. Boxes can also be colored by subsetting based on the underlying atoms, or uncolored to display only parts of chains.
The 3 DNA objects are the phosphate backbone, the pentose sugars, and the DNA bases themselves. The backbone can be represented as a thick ribbon smoothly splined through backbone phosphates. The pentose sugars are represented either as rings or line pentagons. The pentagons are color coded by the endo- or exo- nature of the sugar carbon. The bases are represented as rectangular slabs colored by base type. Base representation can also be made to width- encode a DNA base pair parameter. Support is provided for the output from the program CURVES which describes 38 such parameters. These can also be mapped to a helical sheet and color coded.
2.13 - Pair-Wise Interaction (Matrix) Representations
One quantity which is difficult to represent by conventional means is pair- wise interactions. This is because the variable has a value and two positions instead of just one position. For this reason this is like attempting to display a matrix, as opposed to a vector. Such variables occur in electrostatics as the interaction energy between each charge in a set of charged sites. Another example is effective inter- residue forces which some have developed to model protein stability. Since both these uses are essentially residue-based, the formulation of the pair- wise interaction representation is residue-based in Grasp - it acts between residues, not atoms.
In Grasp these forces are represented by means of lines running between pairs of sites. These lines have as properties the interaction strength and those properties of both interaction residues themselves. Hence lines may be colored (or "uncolored") by standard subsetting commands.
Interactions also have the property of "rank" - since sites may have several interactions, each interaction also has a rank amongst those assigned to that site. Thus one can subset by rank, and only show the strongest interaction for each site. Since interactions can be strong by being very attractive or very repulsive, the interaction strength very negative or very positive, support is provided for ranking by either criteria. This can be useful in determining 'zones' of interactions - patches of residues which interact mostly amongst themselves.
Grasp goes one step further than merely representing forces with lines by expanding the lines into cylinders. As well as being visually striking, this allows the width of the cylinder to act as an indicator of the absolute strength of interaction. By default, Grasp sets the maximum width to represent the maximum absolute interaction, but this can be set to be larger or smaller by the user. All other coloring operations still apply. Grasp also allows for the cylinder representation without width encoding.
The ends of these lines or cylinders are by default set to the average position of all atoms in the residue. This can be altered to any subset within the residue. For instance, in some cases the position of the residue charge might be more appropriate, in others the alpha carbon, or center of the side chain, etc.
Since interactions are be distance dependent, the user can explore this dependence by multiplying or dividing each value by the distance between its two sites. This scaling can help the user determine which interactions are unusually strong or weak.
Matrix values are not calculated at by Grasp. They must be imported via a data file, the format of which is described in appendix A.
2.14 - Stereo/Split Screen Operations
Stereo viewing has traditionally been achieved by duplicating the view, separating the views by a certain distance so that there is no overlap, and then giving the right- most view a twist of about 8 degrees about the vertical direction. Grasp follows this approach and extends it to a 'split- screen' capability.
The stereo separation and twist are under user control (tests within our labs showed conclusively that everyone has their own preferential stereo twist). Separation and twist are under mouse and dial control and twist may also be entered explicitly.
The duplicate view can be treated as completely independent, so that nearly all display possibilities can be used either on the left or the right. This allows the user to display alternate views side by side. For instance, one might want to view the surface color coded by potential and also by curvature at the same time. The left and right views can also be superimposed. One can also manipulate either view independently. For instance, one can display the front and back of a molecule simultaneously. Formal subsets in each view are also independent, so different arrangements of such subsets can be portrayed in right and left views.
3 - Getting Started
3.1 - Grasp Environment
There are a few things one should check before running Grasp.
First is to ensure that one has write privileges in the directory the command is issued from, which can often be a problem if working from someone else's directory. Grasp needs this permission to enable it to write temporary files, which are removed upon exiting the program, and some permanent data files, such as a color map if the user alters those provided, and also "error" files if it detects odd situations (such as finding too many bonds for an atom when reading a pdb file, or fractionally charged residues upon reading a charge control file).
Second, Grasp reads in a few data files upon startup. It needs to know what directory these files are in. To do this, it reads the environment variable GRASP (note capitals) which should be set to the directory with all the files with the extensions ".dat" or ".crg" or ".siz" or ".gs". For those not familiar with Unix, the command to do this is
setenv GRASP dirnam
where dirnam is the directory name. One should place this command in the file .login in one's home directory so it is read and executed when the user logs in. One can check the value of this variable by entering,
echo $GRASP
Grasp also has a directory of "last resort" if it can not find the directory defined by $GRASP. The backup directory it looks for is ./aakdat, i.e. in a directory one lower than the user is in called aakdat. These data files are listed in the appendix and involve such things as default radii for atoms, default charge sets, and information used in surfacing molecules.
Third, Grasp will check for a file called .init_Grasp. This file can contain commands which set variables within Grasp, such as default display modes. These commands are listed in Appendix B. Grasp searches for this file in three places. First it checks the directory defined by $GRASP, second it checks the user's home directory, and last it checks the local directory from whence the command was issued to start the program. The purpose of having it check all three locations is to allow for hierarchical control of Grasp settings. For instance, one might want to set some parameters for all users, in which case they are set in the $GRASP directory. Individual users might want different parameters for their own work, and so alter the file in their home directory. Finally, the individual user might find that for some projects different parameters are better - small molecules might want one set of display parameters, large molecules others, in which case control should be via the file in each particular directory. The order the files are read is important because if two files set the same parameter, preference is given to the later file.
3.2 - Running Grasp
Now you can start Grasp simply by typing "grasp". Once this command is issued, and the appropriate files searched for and read, the default graphics window opens and shows a set of axes or cross- hairs in the X, Y and Z directions. The Z direction is towards the viewer with positive nearer and negative farther away, the X direction is left to right, with right positive and left negative, and the Y direction is up and down with up positive and down negative. The cross hairs run between +/-1 in Grasp internal coordinates. To help visualize this domain one can view the Grasp box. This is done by pressing Control O.
3.3 - Dial and Mouse Movement
One moves the view by using either a dial box or the mouse. The dials work accordingly:
The mouse moves the view by depressing the left or middle buttons or both and moving the mouse:
Left button: Rotations about the axis perpendicular to the direction of mouse motion.Hence there is a sense of "rolling" the molecule as if the molecule where resting on a solid surface in the XY plane and the cursor was the user finger.
Middle Button: Up and down moves the molecule away and towards the viewer respectively. Note that this is NOT a scaling, but an actual motion in the Z- direction and hence corresponds to pulling the molecule towards or pushing it away from the user. Left or right motion rotates the molecule about the Z axis.
Left and Middle Buttons Together: Translates the molecule in the XY plane in the direction of mouse movement.
This implementation of dials via the mouse (mouse- dials) is a little different from some programs since only two mouse buttons are used. This is partly because only two are actually required to allow the six independent rotations and translations, but more importantly because the third button, the right button, is reserved exclusively for the menu interface.
One further convention adhered to in Grasp is that where appropriate, the middle button adds and the left button subtracts. For instance when adjusting the indexed colors in Grasp the middle button increases a color component, the left button decreases it.
The rate of rotation or translation, the sensitivity to mouse or dials, can be set via the menus. It is also possible to assign different functions to the mouse, such as surface scribing, or projection plane position. These are accessed via menus.
Note that the box does not rotate with the the cross hairs. The significance of this is that box represents a space which is invariant with respect to the user. Rotations and translations do not actually affect the molecule coordinates, only the viewing of them. One way to think of this is that it is not the molecule which is moving but actually the user and the box (since both move the box appears stationary). The language used in Grasp is of "original" coordinates, which "belong" to the molecule, and "box" coordinates which belong to the user (and hence the box). One can change molecules into the users frame of reference, i.e. make rotations "real", via formal subsetting and some options for file export.
3.4 - Data Files
One can now read in one of three type of data files, atom files, surface files or maps (3- D grids). Note that instead of reading in a file once the program has executed one can give the name of a data file:
grasp lys.pdb
which will load in coordinates from the pdb file lys.pdb. Other than pdb files one can also give the names of maps, with the extension ".phi", or surface files with ".srf". If the name of the file does not have one of these three extension then the program will prompt the user as to which type of file it is.
Reading a data file from within Grasp involves using the menu system. Clicking the right mouse button, then clicking on Read and then on one of the primary data file types will prompt the user to enter the file name, select a default file, or see a list of files. The list will be all files in the initial directory which have the correct extension for that file type.
3.5 - The Textport
When character input is requested in Grasp, it is via what is called the textport, which is the character based window from which Grasp is initially launched. To enter information to the textport the cursor has to be positioned over this window. If Grasp is expecting information, e.g. expecting a file name, it tries to make this easy for the user both by automatically positioning the textport over all other windows, and by automatically placing the cursor over this window. And when the information input is complete and return has been hit, the cursor will automatically jump back to the spot on the graphics window it was before the request for information. Similarly if the user wants to type a command, the cursor will automatically place itself over the textport when the user begins to type, jumping back when return is hit.
Note that in both these examples the cursor starts over the graphics window and ends there too. The user should NOT attempt to move the cursor onto the textport except in the following two cases. Sometimes the user may have moved the textport, or resized it, and as a consequence the cursor may miss it when made to "jump" by the program. Also possible is that the cursor will come to rest upon the textport when instructions are not being entered. This causes a "change in input focus" for the program i.e. it expects input from the textport rather than from the graphics window. When this happens, for instance, the molecule will not rotate when the dials are twiddled because the program is not "listening". This question of "focus" can often give beginners the most problems in getting started with Grasp, so when in doubt check the cursor position.
Hitting return when the cursor is over the graphics window causes the textport to alternate between background and foreground, i.e. being behind all other windows or on top of them. If the user has resized the textport, for instance made it bigger to review more information, or repositioned it, hitting return will also resize and reposition the textport. Another use of this is that pushing the textport and then bringing it back will usually force a redraw. If for any reason the graphics look funny, for instance 'damaged' by the movement of some other window or some other program, or if the initial view upon starting the program looks strange, this is a simple way to redraw the view.
If one has read in a pdb file or a srf file there should now be something displayed from within Grasp, either a molecule or a surface. The default display of either of these can be altered as described later. Upon reading a structure (i.e. atoms or surfaces) a scale is assigned to the unit box, i.e. the width in Angstroms is calculated (and written to the textport). This is calculated such that the structure will fill up two thirds of the the box in its longest dimension. If the user instead has initially read a potential map the scale is such that the potential map will fill the unit box exactly, i.e. the boundaries of the potential map are at +/- 1 in each direction. This scale is now set for the duration of the Grasp session as there is as yet no facility for altering global scaling. The view can now be manipulated, quantities calculated, structures built, etc.
3.6 - Exit
Exiting the program can be done three ways. The first is NOT recommended except in emergencies (the program has inexplicably locked up) and that is to put the cursor over the textport and hit Control C. The normal way to exit is either through the main menu or via Control Q. If the program is correctly exited one should notice that the cursor is no longer yellow, which it is during normal Grasp operation, unless of course this is the user's normal color for the cursor.
4 - Menus
Menus carry most of the functionality of Grasp. All menus are accessed via the right mouse button. All selections within a menu must also be chosen with the right mouse button. Menus appear when this button is depressed and remain when the button is released. Note this first release of the right mouse button does NOT select an item. The program is essentially frozen until the right mouse button is depressed and released AGAIN.
If the cursor lies over a menu entry when the button is released the second time, then that menu item is chosen. If the user "clicks away", i.e. releases the button when the cursor does not lie on a menu entry, function will abort or in some cases will continue with a default value. For instance, when altering the molecular surface, first the user will get a submenu for the quantity displayed on the surface (potential, distance, color, etc.) and then a submenu for the draw mode (mesh, lit, points, etc.) of the surface. If one does not want to change the quantity displayed, one clicks away from the quantitiy menu and continues on to the draw mode menu. On the other hand, if the user chooses the Build entry in the main menu and then clicks away the program exits from the menu altogether.
Some parts of some widgets, such as the color scale, are sensitive to the right mouse button. This means if the right mouse button is depressed while on this area, the normal main menu will not appear and instead the user will get a menu associated with that widget. Clicking anywhere else in the graphics window will bring up the main menu.
For ease of description, this document will use the following notation to describe a sequence of menu operations: "Display: Stereo/Split Screen: Dials to Both" means choose Display from the main menu, then Stereo/Split Screen from the Display menu, then Dials to Both from the Stereo/Split Screen menu.
The menu options will be described in the order they appear in the main menu, starting with Display. Submenus will be described where they apppear.
4.1 - Display Menu
Show
Alter
Hide
Hide ALL
Stereo/Split On
Show displays a structure, Alter changes the display of a structure, and Hide causes a structure to disappear from view (this is not the same as causing a structure to disappear by coloring it 0 - when a structure is hidden in this manner, it retains all its characteristics including color). All of these options produce a submenu which allows the user to choose from the following structures: Molecular Surface, Atoms, Bonds, Cavities, Objects, Contours, Vectors, and Interaction Matrix.
For Molecular Surface, the user may choose from several coloring schemes: potential, curvature, discrete colors, distances, general property #1, and general property #2. Surface draw modes are rendered, rendered but not lit (pseudo-lit), mesh no rendering, points, transparent, solid/mesh mix, and solid/trans. mix.
For Atoms, the color options are atom type, charge, potential, distances, property #1, and property #2. Atom draw modes are flat circles, full spheres (CPK), flat patterns, little bond-atoms, line spheres, and point spheres.
For Bonds, the coloring choices are user defined, which lets the user set them (default color=1), atom colors, which adopts the underlying atom colors, and saved set, which applies an internal color scheme. Bond draw modes are lines, sticks, and rods. Rods are very slow to draw.
For Cavities, one has the option of coloring as the molecular surfaces, coloring by number, or coloring by number patches.
For Objects, the user must first select the type of object: backbone worm, backbone boxes, DNA bases, DNA backbone, DNA sugars, DNA axis, ellipsoids, DNA H-bonds, or distance line. DNA objects come with several possible options. Most of these are only appropriate if data in the form of a Curves file has been read in, because the options refer to which of the many Curves parameters are to be displayed.
For Contours, colors as well as values are set when contours are built. Contour draw modes are the same as surface draw modes. Control of depth cueing for contours is controlled by "Set Parameters: Depth Cueing".
For Vectors, the possible types are electric dipole, which is a large 3- D arrow of length 0.3 box units, electric field vectors, which can be drawn of constant length or with length dependent on the field strength, and electric field lines, which can be drawn as lines or tubes. The user selects a color for the molecular dipole vector when calculated. For field vectors the user can specify the maximum vector length and the field strength this should correspond to, but only when these quantities have been calculated. Note that it is necessary to calculate a vector quantity before displaying it. The cylinder mode for field lines can be very slow to draw.
For Interaction Matrix, the choices are lines, cylinders, width-encoded cylinders, and extras. The width of the width- encoded cylinders depends upon the absolute value of the interaction. This value is divided by a "maximum strength" value which can be changed, rounded off to unity if greater than one, and multiplied by an internal width to give the resultant cylinder thickness.
The extras option presents a submenu with several entries. One is to refine residue centers, which alters the exact coordinates of the point within each residue each strand emanates from. Upon choosing this option, the user is prompted for a selection on the command line. The user could then input the command "a=ca" whereupon the strands would begin on each residue's alpha carbon. If more than one atom is selected for a residue, the strand begins at the average position of those atoms. Another option is to set the maximum interaction strength for width- encoding as described above. Also included are options to multiply or divide the interactions by the distance between interaction sites. The new maximum and minimum values are written to the textport upon each use of these options. Note that if the draw mode is set to variable widths then this can affect the relative widths of the strand cylinders. To maintain a similar spread of widths the following process of rescaling the maximum cylinder width value is enacted. The ratio of the largest (absolute) interaction value (before distance scaling) to the value set for the maximum width is found. Then the largest (absolute) value is found after distance scaling, and the value for maximum cylinder width set so the ratio just calculated is maintained.
Hide ALL clears the view completely.
The Stereo/Split On controls the stereo display options. It produces a submenu with entries Dials to Both, Dials to Right, Dials to Left, Right- Hand Twist, Stereo Parameters, and Stereo/Split Off. This menu can be accessed directly with Control S. The first three entries decide which side is going to be "attached" to the rotations and translations as entered by the mouse or dial box. The default entry for this menu is Dials to Both - both views are moved equally. In this mode, the two views differ only by an imposed separation of 0.5 box units in the X direction, although the views may not appear identical due to the perspective automatically included in all Grasp views. Choosing Dials to Right or Dials to Left allows one view to be spatially manipulated independently of the other. Note that if the user has defined one or more formal subsets, only the views of the subsets on the side for which the dials are attached can be moved.
Right- Hand Twist causes the right hand view to be twisted in an axis running through the center of its world coordinate system in the Y direction (vertical) by a certain angle This twist is set to 8 degrees by default. This value can be altered in several ways. If the user has a dial box, the left bottom dial will alter the stereo twist. The user can also fix the Z- rotation function to stereo twist via "Mouse Functions: Alternative Z- Trans. Alternative".
Stereo Parameters presents a submenu to allow the user to restore twist to the default value, enter a twist value, enter a separation value, or remove twist and stereo separation altogether and superimpose the left and right views.
Even if the user is in "twist" mode the user can still independently manipulate the two views spatially. This is not recommended since the purpose of twist mode is to allow stereo viewing which requires the two views to be essentially identical except for the vertical twist.
If while in split screen mode, the user attempts to change display properties, Grasp will prompt the user on which "side" the changes should be made. For instance, if the user attempts to hide the bonding display the choice is left, right or both. Thus the display on the left can be representing one facet of a molecule (such as electrostatic potential on a surface) while the right represents another (such as atomic B- value).
Stereo/Split Off quits stereo/split screen mode. The left- hand orientations (world and subset) are the ones retained for the single- screen view. All differential display characteristics the user may have applied to the right view are lost. However, the stereo twist value is still stored and may be retained throughout a session.
4.2 - Build Menu
Molecular Surface
Accessible Surface
Backbone Worm
Backbone Boxes
Cavities/Connectivities
DNA Boxes
Contours
Consensus Volume
Ellipsoidal Objects
The build and calculate menu options are easy to confuse. For instance, does one build a contour or calculate a contour? Are field lines built or calculated? In general, build deals with calculating the data intrinsic to a display structure, such as a surface or backbone representation or internal cavities, whereas calculate provides numbers which may or may not be related to such structures, such as potential maps or volumes of surfaces.
A Molecular Surface or an Accessible Surface is made by essentially the same algorithm. When choosing whether to construct one or the other, the user has to consider two options. The first is which atoms to use in forming the surface, and the second is whether to add this surface to previously constructed surfaces, or to overwrite them. Note that this is the only way to delete a surface within Grasp. The menu for selecting a subset of atoms is: All Atoms, A Molecule, A Format Subset, and Enter String. All Atoms selects all stoms, A Molecule presents a menu containing all molecule numbers, A Formal Subset presents a menu with the names of all atom- based subsets, and Enter String will cause the cursor to jump to the textport and wait for the user to enter a subsetting command. If no atoms are chosen at the end of this procedure, the routine aborts.
The process of constructing the molecular surface occurs via the construction of a temporary accessible surface. A correspondence between the vertices of this intermediate surface and the underlying atoms improves the accuracy of the final surface. It also allows for a unique mapping between atoms and molecular surface such that each accessible surface vertex is assigned an underlying atom, and each molecular surface point is assigned an accessible surface point. The combination of these two assignments leads to the association of each molecular surface point with an atom, an association which is termed "contact" within the program.
The process of surface formation will cause plenty of information to be written to the screen, including the scale at which the surface is constructed and the number of vertices and triangles in the completed product. The information here can be useful in debugging (for example the total number of vertices might exceed the maximum allowed number).
Surfaces should appear automatically after being calculated. They will not be colored however. This must be done by the user via whatever method chosen, by calculating potentials at the surface, calculating curvature, etc.
The Backbone Worm and Backbone Boxes are built for all current molecules. The only options associated with these objects are for the backbone worm, which allows the worm to be built for all CA atoms or a subset. If these objects fail to appear after construction, go through the Display menu explicitly. The backbone worm can be slow to display. Sometimes this can be put to good use. For instance, if the user switches to single buffer mode (Control R) while the worm is being drawn, the path of the chain from N terminus to C terminus is nicely illustrated. The backbone worm only requires the carbon alpha positions to be correctly produced, while the backbone boxes require also the carbonyl oxygen and amide nitrogen positions to successfully complete construction.
Building Cavities/Connectivity causes the program to check all vertices for connectivity. The first point, or seed point, is chosen at an extrema, and so can not belong to a cavity. All points associated with it, those which can be reached by travelling along triangle edges, are deemed the "non- cavity surface". All others belong to cavities. Note that this will give an incorrect assessment if there is more than one disconnected constructed convex surface. For this reason the user should calculate cavities on the surface of the whole molecule, not subsets. Printed to the screen are the number of triangles that make up each cavity found. Cavities are automatically displayed in the same display mode as the molecular surface. They can be sequentially colored.
Building DNA Boxes requires that a DNA PDB file has been read in. (Note that mixed files containing DNA and protein are fine.) Display should be automatic. Grasp can handle structures with up to four independent backbone strands.
Contours can be made in 3-D, 2-D with an interpolation plane, or 2-D with a molecular surface. These all require two inputs by the user: the isopotential value, and the color to be assigned to that contour. The latter should be a color index, an integer between 1 and 99. One can enter more than one isopotential value to create more than one contour at a time, as long as one enters the same number of colors. For instance:
enter 3-D contour value
>> 1.0,2.0,3.0
enter 3-D contour color(s)
>>2,3,4
will create contours at one, two and three kt, and give them colors 1, 2, and 3 (red, green, and blue). To delete a contour (which may be necessary to make room for new ones), one goes through the same procedure as making a contour of the same isopotential value, one gives it color 0. Note that this remove is NOT the same as hide or uncolor, as it actually removes the contour data from the program.
Although the usual use of building contours will be isopotential contours, it can be used for more varied purposes, since the actual contents of the map are irrelevant to the contour facility. For example, one can contour a DelPhi "eps" map if one has read one in, or one can contour a consensus volume map (see below) if one is calculated. One should remember that there are two internal maps in Grasp. The contouring proceeds on whichever map is "current". This is usually map 1, but will be map 2 if one has just read in a map. Set the current map with "Miscellaneous: Change Current Map".
Consensus Volume produces a map - a 3D lattice of values. It is calculated by adding the value 1.0 to each grid point which lies within the Van der Waals volume of each molecule. Thus if there are five molecules and a grid point lies within all five, it will be assigned a value of 5.0. Some points will fall within only some molecules. This map can then be contoured at any level desired. For instance contouring at the level of the number of molecules will give the surface of the volume common to all molecules. At present there are no options to this facility and all atoms are included in the calculation. The map is stored as map 2.
Ellipsoidal Objects constructs ellipsoids enclosing the Van der Waals surface of the atoms, residues, or surfaces selected. This selection can be all residues, an atom subset with one ellipsoid, an atom subset with many ellipsoids, a surface subset with one ellipsoid, and a surface subset with many ellipsoids. For the atom options, the user is given the choice of all atoms, a molecule, a formal subset, or entering a subsetting string. For surfaces, the choices are all surfaces, a single constructed surface, a surface formal subset, the currently scribed surface, or entering a subsetting string. If ellipsoids have already been constructed, the user has the option of adding to the current set or replacing them.
4.3 - Calculate Menu
New Potential Map
Pot. via Map at Surfaces/Atoms
Surface Curvature (+Display)
Simple Property Math
Dipole Moment
Field Lines
Field Vectors
Volume of a Surface/Molecule
Area of a Surface/Molecule
Distance Array
H-Bonds (DNA Bases Only)
The calculate option does much that is unique in Grasp. It allows the user to quickly calculate electrostatic quantities like maps, fields, and site potentials, as well as curvatures, distances and volumes, and manipulate fields of information previously calculated or imported to the program.
Calculating a New Potential Map causes the program to execute its internal Poisson- Boltzmann solver. The size (in Angstroms) of the map produced is automatically determined. Only the linearized Poisson- Boltzmann equation is solved. Such parameters as the probe radius, ion exclusion radius, salt concentration and inner and outer dielectric values can all be set via "Set Parameter :Electrostatic Parameters". The map produced is stored in internal map 1. If no charges are assigned, then the procedure will inform the user and abort rather than calculate a null map.
It is important to realize that by default all atoms and therefore all charges are used in the calculation. If the user wants to perform a calculation on a subset of atoms, those atoms not required must have their radii and charges set to 0. The algorithm will ignore any atoms with radius 0 so that they will not contribute to the water exclusion (=low dielectric) volume, however, it will NOT ignore the charges on these atoms. Therefore one needs to neutralize the charges on the unwanted atoms as well. Since changing radii to 0 also causes atoms not to be displayed, the user ought to remember to reset those atoms to their correct radius after the calculation, for instance by reading in a default size file.
A typical use of the above procedure for removing some atoms from an electrostatics calculation is one where the original crystallographic coordinates are included for several water molecules. It is always an interesting question as to whether such waters should be treated as low dielectric, and constrained in their motion, or high dielectric, and bulk water. A good rule to use is that if a water is highly coordinated to the protein, so that it makes two or more hydrogen bonds, a case can be made for low dielectric, otherwise set it as high by setting its radius to 0 in the calculation and turning off any assigned charges.
As with building surfaces, much information is written to the screen during the calculation, some of which is useful to the user in verifying the accuracy of the calculation, that it has converged, that the correct total charge has been assigned, that the scale of the final map is approximately correct, etc. A typical calculation should take about five seconds on a Personal Iris.
Pot. via Map at Surfaces/Atoms calculates the potential at all surface vertices and all atoms from the current map. If one has just calculated a new potential map, this is map 1. The algorithm uses trilinear interpolation from the eight grid points which make up the map grid cube which an atom center or surface vertex falls within. If it lies outside the map, a 0 value is assigned. Note that this process will overwrite any previous potentials. If this is a problem, the user should first store the previous array in one of the other variables, as described under Simple Property Math.
Surface Curvature (+Display) will cause the program to calculate the curvature, as defined in Nicholls et al., for a set of surface points and a set of atoms. As our definition of curvature is related to accessibility of water to a single water placed in contact with a particular surface point, the set of atoms chosen is crucial, since the hard sphere radii of these atoms will determine this accessibility (note that a 0 radius atom does not affect accessibility). Thus, for instance, if one wants to compare the curvature of two surfaces which make up an interface, one should choose surface 1 and the atoms which made surface 1 for the first calculation of curvature, then choose surface 2 and its atoms for a second calculation.
Curvature calculations can sometimes take a long time. This is due to the choice of test sphere used to determine accessibility - more points take more time. The choice of this density is made automatically relative to the scale employed in the surface creation. Because Grasp has only a fixed number of test densities, the time taken in calculation will vary considerably.
Upon completion of a curvature calculation, the display should automatically switch to displaying this quantity. The values are scaled to +/- 100, such that 100 would imply that the surface point is completely accessible, which will never happen since this would imply that one could put a water molecule anywhere in contact with the original water molecule touching the surface. However - 100 implies that the surface water is completely isolated from other water molecules, which is quite possible, for instance in a deep cleft or if the surface is enclosed inside the molecule or is part of a molecular cavity.
Simple Property Math is one the most useful options in Grasp. Its submenu gives the user these choices: Potential Maps, Atom Properties, Surface Properties, and Map Atom Value to Surface, and Map Atom Value to Worm.
Potential Maps allows the user to perform an operation (add, subtract, multiply, divide) between maps and store the result in either map , to add or multiply by a scalar value, to perform a function on a map (square root, reciprocal, raise to a power, exponentiate, absolute value, natural log, sine, cosine, hyperbolic cosine, hyperbolic sine), or to swap maps (put map 1 into map 2 and map 2 into map 1).
One of the scalar map options is to apply a "convex" correction. This was added after it was noticed that potential maps generated on the the Convex used for most of our DelPhi calculations where misread if transferred onto an Iris. To be more precise, all real numbers (but not integers) were exactly four times too large. This includes the potential map center and scale as well as the potential values. This option then will rescale all those values to their correct value. In addition, if the Grasp box scale has been derived from a potential map, then the user is prompted as whether to reduce the box scale by one quarter as well.
One should note in "map math" that no checking is done to see if the grids actually have the same center and scale, i.e. whether they refer to the same part of physical space. The values of corresponding grid points are just added, multiplied, etc. The inclusion of a division operation was prompted by the desire to calculate effective dielectrics, the ratio of the potential calculated with Coulombs Law to that via the Poisson- Boltzmann equation. If 0 is found in the denominator of a division, then the new grid value is set to 0.
Math on Atom Properties and Surface Properties are the same in that the same basic operations can be applied to either. These operations are add, subtract, multiply, divide, multiply by a constant, add a constant, maximum, minimum, average, sum, and special functions (square root, reciprocal, raise to a power, exponentiation, absolute value, natural log, sine, cosine, hyperbolic sine and hyperbolic cosine).
Add, subtract, multiply, and divide require selecting three properties (two properties for calculation and a third to store the result). Multiplying by a constant, adding a constant, and special functions require two selections (the property acted upon and storage). Maximum, minimum, average, and sum return a single value printed to the textport. Maximum and minimum also print the atom or vertex number with with the value is associated.
Properties for each step of the math calculation are selected from a property list for either atoms or surfaces. The user is also prompted for a subset of all atoms or vertices to do the math upon, which is then common to each array. The user should take some care in using this simple math facility to ensure that the property arrays are entered in the correct sequence.
Map Atom Values to Surface requires that the user select a surface, a set of atoms, an atom property, and surface property. The connection between surface and atoms is via the original construction process, i.e. which atom is responsible for which part of the surface. If the responsible atom for a particular vertex in the surface selection is not included in the selection of atoms made, then no value is set in the property array for that vertex. Most typically the user will apply an atomic property universally, i.e. choose all atoms and all vertices, to the surface.
Map Atom Values to Worm requires that the user select a surface, a set of atoms, an atom property, and surface property. The connection between surface and atoms is via the original construction process, i.e. which atom is responsible for which part of the surface. If the responsible atom for a particular vertex in the surface selection is not included in the selection of atoms made, then no value is set in the property array for that vertex. Most typically the user will apply an atomic property universally, i.e. choose all atoms and all vertices, to the surface.
The flexibility of operations on atoms and vertices greatly exceeds that of maps, which is mainly because the uses so far imagined for the former greatly exceed those for the latter. In time it is hoped that Grasp will support a math interpreter rather than use the menu system which should more fully realize the potential for on-the-fly analysis it is hoped this function makes possible.
Dipole Moment takes all the charges on all atoms and calculates a dipole and, if necessary, monopole. The latter is necessary if the total charge is not zero. The procedure is to find the sum and charge weighted average position of all positive charges and the similar quantities for the negative charges. If the two sums are not the same, then there is a monopole equal to the sum of the sums acting at the charge weighted average position of the larger (in absolute terms) of the sums, plus a dipole of magnitude determined by the smaller (in absolute terms) sum multiplied by the distance between charge- weighted centers. These values are printed to the screen, plus once calculated the user can display a dipole "arrow" centered at the average of the charge weighted centers, and of length 0.3 box units. This is displayed via "Display: Show: Vectors".
There is as yet no option to display or calculate multiple dipole vectors.
Field Lines are a difficult quantity to visualize. This is mainly because they are infinite in number and it is difficult to visualize an infinite number of lines. In a "correct" implementation the number of lines within a given volume is proportional to the average field strength. Hence one could imagine discretizing this concept so that there are a finite number of such lines. However this is NOT the approach followed in Grasp. Instead one chooses a set of starting points, or seed points, and projects the direction a positive or negative charge would take from each such point, the field direction, as found from the current potential map. A line segment is drawn a certain distance in this direction and then the field at the end of this segment calculated. This process is repeated up to a fixed number of times to give a field "line". Typically one hundred segments are calculated. If the length of each segment is small enough, the line appears smooth.
Seed points are determined by the first submenu of this selection. The choices are: Center of Atom Set, Surface, Atom Set, Origin, and Enter Coordinate. Center of Atom Set will prompt the user for a set of atoms. The average of these coordinates will then be found. If the number of lines chosen in a later menu is greater than one, then that number of random positions within half an Angstrom of this position are found and used as seed positions for field lines.
In selecting Surface, one can obviously choose all surface vertices, but often a more useful selection is some patch of surface selected by surface scribing. Once chosen, a number of points equal to the number of lines chosen are found at random over the selected surface as seed points.
Choosing Atom Set will cause the center of each atom selected to be initial seed points. If more than one field line is selected, that number of seeds will be formed within 0.5 Angstroms of each atom center. The user should note that there is a maximum of 100 field lines and should be careful not to exceed this limit or the process will not run to completion.
Choosing Origin causes the initial seed point to be at the center of the Grasp box. This number of seed points can be multiplied in the same random manner as described above.
Finally, Enter Coordinates allows one to enter the absolute coordinates for the initial seed. Again this can be multiplied by random scatter about this point.
The next menu deals with field line directionality. Clearly one has a choice of whether to use a positive or a negative "test" charge when plotting the field line. Traditional electrostatic lines begin on positive charges and end on negative charges (or infinity). In Grasp they can go either way depending on the sign of the test charge, or go both ways! Note that by choosing bidirectional lines one actually creates two field lines, one in each direction. If one has chosen to create the field line seeds from a surface then one has yet another choice, whether one would like to force the direction of the field line into or away from the molecular surface.
Next one can choose the number, or multiplicity, of field lines. As mentioned above, this will multiply the initial seed positions by finding random positions in the vicinity of the initial seed point(s). The default value is one. As mentioned above, bidirectional lines count as two. Thus if one chooses the atom centers of 20 atoms, with a multiplicity of 2 and choose bidirectional lines one actually gets 80 field lines.
Finally, the user gets a choice of colors for the field lines, the default being white. If one has previously created some field lines, then one has the choice of adding to those already created, or replacing them (Note the 100 field line limit applies to the total number of field lines). Field lines can be drawn as lines or as cylinders. The latter display is more dramatic than the former but is very slow to draw.
Currently in Grasp the line segment length of the field line is constant. This means that sometimes the lines will exit the potential map i.e. for which there is no interpolated field. Lines will then terminate. Another problem is that around charges field lines will not actually terminate, rather they oscillate. This is due to the nature of the field around a charge mapped onto a grid. There is also no method of illustrating the field strength at any point along a field line. These shortcomings will be addressed in future releases.
Field vectors can be calculated at up to 100 sites. Sites of interest are chosen as either a set of atoms (each atom center), the center of a set of atoms, at a random selection of points from a surface, or from a point whose coordinates are entered by the user. Once the points of interest are selected, the magnitudes and directions are calculated from the current potential map. Each result is displayed as a field arrow similar to that for the molecular dipole, originating from each chosen point.
The user is given the option of giving each field vector either a constant length, which is then entered in Angstroms by the user, or a variable length, where the user enters both the maximum vector length in Angstroms and the maximum field strength to which this corresponds. In the latter case field vectors of strength less than the maximum representable field strength are assigned a proportionally smaller vector and those greater than the maximum the maximum length. Note that these lengths can not be altered once set and neither can the color for which the user is prompted for each set of vectors. As with field lines, one can delete current vectors when making new ones or one can add them, with the same maximum of 100 total vectors.
One should note that, as with field lines near charges, field vectors may be less than reliable. One should bear in mind the scale of the grid used in calculating the potential map. Fields are calculated by first estimating the fields at the eight corners of the grid cube that encloses the chosen point and then using trilinear interpolation on that set of vectors. The relative error of the field when a point is near a charge is greater than that of the potential because it involves quantities closer to the charge (i.e. higher order derivatives). For this reason one should be very careful in interpreting field strengths quantitatively from any such interpolation when near atomic charges.
The Volume of a Surface/Molecule is relatively simple to calculate, given a tessellation of the surface. One merely chooses a point, preferably close to the surface or molecule, and then calculates the volume of each pyramid formed by this point and the three points of each triangle in the tessellation, being careful to have the order of the points in the triangle base consistent with the surface normal. One can calculate the volume of any closed surface, such as a contour, a cavity, a molecular surface, or an accessible surface. The volume of a set of atoms may also be calculated this way, by tessellating the Van der Waals surface of that set of atoms and calculating the volume of that closed surface. Alternatively, one can map the atoms onto a fine grid, find which grid points are outside and which inside, and form a lattice approximation that way. Since both are simple, Grasp does both and answers are written to the textport.
An Area of a Surface/Molecule is also simple given a tessellation, since it is just the sum of the areas of all triangles. The area may be of any subset of surface one can categorize. The area of a set of atoms is calculated using the surface area algorithm of Grasp which is an efficient version of "Shrake and Rupley", which places points on a test sphere about each atom and finds which are inside and which outside. The density of points, and hence the accuracy used in the calculation, can be altered by the user via "Set Parameters: System Miscellaneous: Surface Area Probe Density". The user also has the choice of whether to calculate the accessible area, as if the radius of each atom is increased by the diameter of a probe, or the Van der Waals surface, with probe radius 0. This probe radius may be set by the user via "Set Parameters: Probe Radii Values", the default being 1.4 Angstroms.
When a subset of atoms is used, the area is calculated as if other atoms do not exist. As with curvature calculations, other atoms are not used to determine accessibility. All results from the calculation are placed in the accessible area array, which can be manipulated via the simple math options. Hence if one wants to know the total accessible area of all lysines in a protein one does not want to select just lysines, rather choose all atoms, then go through "simple math" to calculate the sum of the accessible areas of that subset of atoms. On the other hand one might want to know the total accessible area of a subunit of a quaternary molecule if it were isolated from the total structure. Then it would be appropriate to select just this set of atoms.
A Distance Array can be calculated for any subset of atoms or vertices to any other set of atoms or vertices. It represents the minimum distance for a "from" set to a "to" set. Since atoms have radii, it is often useful to take account of this in the "distance" quantity and subtract it so that the distance calculated is the distance to or from the Van der Waals surface of the atom. Note that this can result in negative distances.
The results of the calculation enter the atom or surface array for distance only for the "from" subset selected, not for both. For instance, if one wishes to calculate the distance map between two surfaces, one should choose this function for the first surface against the second and then repeat it for the second surface against the first. Note the user should be careful that the second set does not contain some of the same points as the first set or the minimum distance will clearly be 0 for these points (or negative if Van der Waals radii are being subtracted).
Distance calculations are quite slow if many points are being checked against many points. At this stage of the program, these calculations have not been optimized. A rough estimate of the time taken for a calculation to complete is to multiply the number of points in each set (the "to" and "from" sets), divide by one million and multiply by two. This is then an estimate in seconds of CPU time. If one is calculating for a 10,000 vertex surface to a 15,000 vertex surface, sit back and wait!
Note: if one wishes to remove the Van der Waals radius from the "to" set, the set of atoms not having distance calculated for, then strictly each distance comparison should involve a square root. Because this is very slow on the Iris, and because this is already a slow calculation, Grasp actually calculates the minimum center-to-center distance first and then subtracts the Van der Waals radius of the atom found closest. This is not strictly correct and may result in inaccuracy at small distances (i.e. of the order of a few radii). This limitation will be removed when more efficient distance algorithms are installed.
Calculating H-Bonds (DNA Bases Only) requires that a DNA PDB file has been read in.
4.4 - Mouse Functions Menu
Atom Information
Surface Information
Measure
Scribing
Command Line Mouse
Z- Trans. Alternatives
There are three different ways information can be sent from the mouse to the program, namely holding a button down and releasing it without moving the mouse ("picking"), which usually returns information on the underlying object, holding a button or buttons, down and moving the mouse, which typically causes rotations or translations, and moving the mouse without any buttons depressed, which usually in Grasp has no effect. These methods can be affected with the menu options within this menu.
Atom Information and Surface Information allow the user to choose whether the left or the middle button is associated with returning surface information or atom information when either an atom or vertex is "picked". The default arrangement is that the left button gives atom information, the middle button returns surface information.
Measure allows the user to associate certain measurement functions with the picking mode of either the left or right buttons which are set as described above. The measures for atoms are InterAtom Distances, Interbond Angles, and Interbond Torsions. These measurements require two, three and four atoms respectively as data. As an example, suppose the user links InterAtom Distances to the left button. The user then "picks" an atom. The next atom picked by this button will cause the distance to be calculated between the first atom and this atom, and the result written to the textport. The next atom chosen after that will cause the distance between it and the second atom to be calculated and presented. This "chaining" of distance calculations continues until the user either double-clicks on the last atom or "clicks away" (clicks on empty screen). This resets the "memory" of atoms so that the next atom picked does not cause a distance calculation but acts as the first atom chosen for a new chain of distances. The same procedure is followed for Interbond Angles and Interbond Torsions, except that the angle calculation occurs for the last three atoms picked, and torsion for the last four. Clearing the "memory" is done as before. Note that atom information is still written to the textport with each individual pick.
The measurments for surfaces are Surface-Surface Distance, Surface-Surface Angle, and Surface-Surface Torsion. These work similarly to the above measurements for atoms. One can turn off the measurement function for the chosen button by reassigning it to Atom Information or Surface Information.
Scribing turns on the "scribing" function. This is a way to select parts of a surface by drawing the outline of an area onto the surface. Selecting this option turns the mode on and disables other functions of either button while the cursor lies over a molecular or accessible surface. When either the left or the middle button is held down while the cursor is over such a surface, and the mouse moved, the triangles under the cursor that make up that surface should "respond" by changing color to bright blue. Upon releasing the cursor, the "track" of the cursor should remain visible as a chain of bright blue triangles. Note that to move the surface while in scribing mode, one has to either use a dial box or position the mouse off of any surface before attempting to move the view by mouse.
When the user has outlined an area of interest with a blue border, the area can be "filled" by double- clicking anywhere inside the area. This will cause the initial triangle under the cursor to turn green, then the triangles adjacent to that triangle turn green, then those adjacent to those turn green, etc. Thus a green "wave" expands outward from the initial point. However, a blue triangle previously selected as part of the border will not turn green. Hence if the blue triangles form a complete circle about the selected area, the green expansion will halt inside the circle. If the border is not "water- tight", the green triangles will "spill" out and eventually cover the entire surface.
If the user clicks with either the left or middle mouse button while the wave is still expanding, it will immediately stop "growing". This can be used to highlight a region by double- clicking on the approximate center of the region, waiting for the wave to cover the desired area, then clicking again to make it stop.
The surface selection is now all the triangles colored green. This selection is referred to as the "Currently Scribed Surface" in all menus which prompt the user for a surface selection. For instance, "Calculate: Surface Area: Molecular Surface" path will give the user a menu with this option, which will result in the calculation of the surface area of the selection. The user can make this selection permanent by making it a formal subset. It will then be assigned a name which can be used to refer to it at any future time. This is described in detail under the Formal Subsets menu.
There are further options available if the user selects the Scribing option while scribing mode is already on: Initiate Fill, Undo Fill, Add Contiguous Border to Fill, Change All Border to Fill, Clear All Marks, and Turn Scribing Off. Undo Fill removes all green markings but leaves the blue ones. Add Contiguous Border to Fill changes to green only those blue areas which are next to green areas. Change All Border to Fill changes to green all blue areas. Clear All Marks removes all green and blue markings from the surface. Turn Scribing Off also removes all green and blue markings and also exits scribing mode.
One should exercise a little care when scribing for several reasons. First, if the cursor starts on the surface when a button is depressed but ends up off the surface before it is released (which should not really happen when scribing), one can get unexpected results (e.g. the mouse is "locked" into a rotational mode). Second, if the surface is at a coarse scale, e.g. a large molecule has been surfaced, then one should not scribe too fast because occasionally the program may get confused as to where it is on such a surface. Furthermore, if one is trying to trace a boundary on a complicated surface one may have to rotate the molecule to get over some surface features with the border intact.
Note that scribing does not work if the surface is rotated by dial while holding a mouse button down with the cursor on the surface. Also note that clicking on the same triangle twice causes the "greening" to begin, so be careful not to accidentally start this process by starting at the same site twice in a row. Finally, remember that, other than a well formed blue border, only a further mouse click will halt the expansion of the green triangles.
Command Line Mouse means the user can fix a certain written command to be automatically enacted when an atom is "picked". These commands can only refer to atoms at present. For instance, if the user enters "c=2" after selecting this item, then every atom picked after that will be colored 2. This procedure works by finding the atom number of the atom picked and then appending this to the entered command and sending it to the command interpreter. So if the user clicks on atom 55 then the command actually sent to the inperpreter is "c=2, an=55". Note this will not work with the projection command ("c=2 >r,an=55" will not color 2 the residue containing atom 55). One use of this function is to assign charges to a picked atom, or to remove certain atoms from view using "c=0" or "alt(r=0)". Choosing this entry again turns off the automatic command function.
Z- Trans. Alternatives affixes alternate functions to the Z- displacement mouse function, which is holding the middle mouse button down while moving the mouse up or down. There are three such functions: Z-Translate (Default), Z-Value of Pot. Plane, and Stereo Split/Twist. Z-Translate (Default) is the default and is used to reset this function. Z-Value of Pot. Plane alters the position of the projection plane, which is the plane colored coded by the potential from the current map. Stereo Split/Twist alters the separation of a stereo pair. This latter function is normally taken care of via the dial box, but is included since not all users will have one. Also in the latter case the stereo twist is fixed to the left- right motion of the mouse. This menu also returns the button to its usual functions.
4.5 - Read Menu
GRASP Surface File
DelPhi Potential Map
DelPhi Epsmap
GRASP Property File
PDB File
GRASP Script File
Radius/ Charge File (+Assign)
Curves File (.lis)
Pair Wise Interactions
Grasp .init File
Grasp Macro File
This menu deals with the input of data to Grasp, and the operations performed on it as a consequence. Formats for many of these files are described in Appendix A.
Upon choosing one of these options, the user will get up to three choices: a default file name, a menu list, or the option to enter a file name. When a file name is entered, Grasp checks first to see whether that file exists in the current directory. If it does not, then it then checks all the directories in the user's $PATH. If the file is not found, this will be reported in the texport and the read aborted.
To check the $PATH, type "echo $PATH". Grasp only checks $PATH at startup. The user can use this variable to point to any direcories which contain desired files. Some people have complained that Grasp has a hard time "seeing" certain files, claiming they don't exist when they do. If you have this problem, you may have $PATH set incorrectly. Even if Grasp is able to list (on a menu) files in your current directory, it will not be able to open them unless the first two characters of your $PATH are ".:" (dot-colon). If they are not, type "setenv PATH .:{$PATH}", or else type in all filenames in your current directory and prefix them with "./" (dot-slash). For example, a file in your current directory called lys.pdb would be typed as ./lys.pdb.
A Grasp Surface File contains the information necessary to reconstruct a surface. It is an unformatted, or binary, file and can not be read as an ascii file. It contains the surface scale and midpoint, plus a list of vertex coordinates, vertex normals, accessible surface points and a list of triangles, which are vertex numbers of each triangle. Also, any surface variable which has been calculated or assigned is also written to this file: surface potential, distance, curvature, and general properties 1 and 2. Upon reading this file, the surface is automatically displayed in the default surface mode. The surface display quantity is usually set for potentials. Since there are memory limits on the number of vertices and triangles current in the program at any one time, the program checks to see whether there is space for the new surface and the input is halted if there is not.
The program will write to the textport the number of vertices and triangles read, as well as which properties were also included in the file. Surface files may contain more than one distinct set of surface points, in analogy to a PDB file containing more than one molecule. Each surface read in is assigned a sequential integer, as if each had just been constructed anew - if the user has built two surfaces and two more are read in they are assigned surface numbers 3 and 4. These numbers can be used in surface subsetting. These numbers also appear in menu lists of constructed surfaces.
Grasp surface files should have the extension ".srf". They are one of the three primary data files for Grasp, by which is meant that the program can set the view center and scale, and can display the structure upon input.
A DelPhi Potential Map file, or phi map, can be produced by DelPhi or by Grasp. It is also an unformatted file and one of the three primary data files for Grasp and should have the extension ".phi". The program keeps a menu list of all such files in the current directory, which is accessible to the user when choosing a file. As well as containing the potential at every point of a 65 cubed lattice, phi maps contain a scalle (lattice spacing), and a mid- point (the absolute coordinates of grid point (33,33,33)). Extended phi maps may also contain a rotation matrix. A phi map is read into internal map 2, overwriting any resident map. This map is set to be the current map, and so is the one automatically used for such operations as contouring. If no scale and midpoint has been set for the Grasp unit box, it is set from the scale and midpoint of the phi map, so the map exactly fits the Grasp box.
A DelPhi Epsmap file (default extension ".eps") is the final unformatted file type Grasp will read and contains the information on the dielectric map used in a DelPhi calculation (eps is short for epsilon, the symbol for the dielectric value at each point in space). The dielectric map is defined at the grid mid- points, i.e. the points half way between every grid point and its six nearest neighbors. There are 3*65 cubed of these. Eps maps have a center and scale associated with them, though they can not be used as primary data files for Grasp. They also contain a list of which grid points were assigned as being in salt, which is referred to as the "Debye" map. When reading in an eps file, the user can choose to read in just the X or Y or Z component of the eps map, since these are each individually 65 cubed maps. The grid values are either set to one or zero, one if inside the low dielectric, zero if outside. The user can also opt to make a composite map of these three components, where the values of the eps map at each of the six midpoints associated with a grid point are added together and assigned to that grid point. Finally the user can select to read only the Debye map from the epsmap. Here the values assigned to each grid point are one if in salt and zero otherwise.
These maps can be used to check the actual surface used in a calculation, relative to the underlying atoms. They can also be useful in calculations. For instance, one can use the eps map to set all potentials inside the molecule to zero, or the Debye map can be used to calculate excess salt concentration from a DelPhi phi map.
A Grasp Property File is an ascii file which contains a list of values to be assigned to either atoms or vertices. The format of the file is especially simple, namely a number of comment lines, then a line with the letters "surface=property" if the values belong on a surface, or "atoms=property" if they belong to atoms, where property can be "potential", "distance", "curvature", "gproperty1", "gproperty2", "accessible", or "charge", followed by a list, one value per line, of the values to be assigned to vertices or atoms in sequential order - value 1 goes to atom 1 or vertex 1. When this file is read in, the maximum and minimum values for that property array are recalculated and the color coding altered if necessary if currently displayed. These files can be created by Grasp, or by the user via external programs.
A PDB File is the final primary data file for Grasp. The correct extension is ".pdb", and a list of all such files in the current directory is maintained in menu form. Grasp supports several variations on the format laid down by the Brookhaven Protein Data Bank, in that the field after the coordinates can be used to contain Grasp atomic property information. The original such variant was the "modified" PDB file output by DelPhi. This substituted the occupancy and B- factor information with radius and charge for that atom, since this is information was necessary and sufficient for a DelPhi calculation. Grasp supports this type of file and will recognize the format when the file is read and assign the values in these fields to the radius and charge of each atom. Grasp also supports files where this information is actually meant for general atom properties 1 and 2 (for instance if the values really do represent occupancy and B values), and where these properties are written in higher precision. To alert the program to the correct interpretation of these fields the user should insert the correct headers to these files, as described in section A.5. All of these file types are written by Grasp, in which case the correct header is automatically inserted.
Upon reading a PDB file, Grasp automatically constructs a bonding pattern for those atoms based upon proximity and atom type. This procedure is not always perfect but works well for high resolution structures. The exception to this is if the file contains alternate atoms, such as if some atoms are multiply represented in the file due to ambiguities in the original electron density map. The program will not at present take account of this in bond formation and inappropriate bonds will probably be made due to proximity considerations. Multiple structures can be entered within one file if they are separated by "TER" lines. Otherwise the same problem of inappropriate bonding patterns may occur. If Grasp detects what it thinks is such a pattern, like a carbon bonded to five atoms, it writes out that atom's information field, plus the number of bonds being made, to a file called bonding.dat. This can help the user check the validity of the assumed bonding by viewing this file after a structure has been read. Grasp will also write to the textport the number of atoms and molecules read.
Radii are assigned from the data file default.siz unless the file type has embedded radius information. Charges are not assigned automatically, unless they are also embedded in the file. If charges are assigned within the file the maximum and minimum charge values are (re)calculated for use in color coding of this variable. If no scale has been calculated, Grasp calculates the maximum X, Y or Z dimension and makes the Grasp box size 50% greater so that the molecule fills at most two thirds of the box. (Note that Grasp includes the atom radii in this assessment so that small molecules do not appear too large).
To do operations on DNA, it is necessary to read in a PDB file which contains DNA information. Mixed files with proteins and DNA are fine.
A Grasp Script File is an ascii file where that each line is read and sent to the command interpreter as if the lines were typed on the command line. As the file is read , each line is written to the textport at the same time it is processed. Lines which begin with the symbol "!" are treated as comment lines and written to the screen but not acted upon. An example of the use of such a file is to enact a default color scheme for atoms the user favors, or as an alternative method of setting radii or charges from DelPhi control files. The user has the option of writing all textport commands entered, via the Write menu, to an external file history.dat, which is often a good starting point in constructing a script file.
A Radius/Charge File deals with the input and processing of DelPhi style control files for these variables. Several such files are located in the Grasp data directory, and the user may place their own there too if they wish them to appear in the Radius/Charge File menu. These files should have the correct file extension: radisu size files are ".siz", charge files ".crg". Alternatively, the user can input the name of a file, which will be processed according to the file extension. Upon reading a charge file, the total assigned charge will be reported and the maximum and minimum values found, which may alter the display if charge is a current display variable. Upon reading a radius file, the program reports the number of distinct radii amongst all atoms. This value may not exceed 100.
A Curves File contains information on DNA parameters, and at present must be in the same format as that put out by the program "Curves", (which must have extension ".lis"). Future versions of Grasp will support other DNA structure program output.
A Pair Wise Interactions file is an ascii file which can come in two formats as described in Appendix A. These files contain information on which two residues each matrix interaction is between, and the strength of the interaction. If the program can not assign the given value to a pair and cannot find one or both of the described residues, that line of the file is written to a file called int.pair.not.assigned.dat. That there have been such failures is written to the textport after the file has been read in. There can be at most 10,000 interactions in the program at any one time. Note that reading in a new file will overwrite old values.
A Grasp .init File is an ascii file that contains one or more of the commands described in appendix B.
A Grasp Macro File is an ascii file that contains a series of definitions of commonly-used functions as described in section A.8.
4.6 - Write Menu
Grasp Surface File
Atom (PDB) File
Potential Map
GRASP Property File
History File
Surface Points as PDB
Macro to File
RGB/Snapshot File
Grasp can export most of its internal data structures to external files. The format of some of these files can be found in Appendix A. Files are written to the current directory (unless the file name specifies otherwise). If the file exists, the user will be prompted as to whether to overwrite the file or not. In some cases, the user may have the option to append to a file of the same name.
A Grasp Surface File contains information sufficient to display and manipulate a surface. Any property array which differs from zero in any of its entries is also written automatically to the same file. One can append surface files to other surface files when writing. When this is done the equivalent of a "TER" line is inserted so that upon subsequent input, different surfaces remain distinct, just as different molecules would from a properly constructed multiple- molecule PDB file.
When writing a surface file, the user is given the same choice of surface subsetting as in any other operation involving surfaces, so that one is not restricted to exporting whole surfaces. For instance, the user may wish to save only the part of a surface involved in making an interface with another surface. Note that the user can immediately read a surface just written, which provides a mechanism to duplicate a surface subset.
An Atom (PDB) File is a PDB file but with the four different possible formats mentioned in the Read menu section: no extra data, radius and charge data in the occupancy fields, another pair of properties in these fields, or a pair of properties to higher precision. In the latter two cases, the user is prompted as to which atom properties to export. As with surface files, the user may select any subset of atoms to be exported rather than all atoms, and the user has the choice of four different coordinate frames. As with surface files, the user can export a molecule or part of a molecule and then read it in as a way to duplicate those atoms.
For both surface and atom files, the user has four choices for the frame of reference used to calculate the coordinates written to file. These appear on a menu which has the entries: Absolute Centering, And Rotated, Box Centered, and And Rotated.
Absolute Centering, which is the default, is to write out the coordinates unchanged from the original PDB file. Box Centered writes out the coordinates after adjusting them so that the center of the molecule is (0,0,0). If a molecule has center (average) coordinates (4.203, 3.123, 5.011) and this is the first file Grasp reads in, it will set the scale of the Grasp box by it and also make it the center of the box. The box centered option subtracts 4.203 from each X coordinate, 3.123 from each Y coordinate, and 5.011 from each Z coordinate. The two And Rotated entries apply the current rotation/translation matrix to the original coordinates before writing. The first rotation entry applies just the rotation matrix, and the second applies the matrix and then centers the molecule at (0,0,0).
These options can be used to compare surfaces or molecules, or parts thereof, which have radically different centers and/or orientations. They can also be used to restore an orientation so that the exact same view can be examined again.
For Potential Map, Grasp will write out either internal map in DelPhi form. This file will contain the values at each grid point, along with the grid spacing and coordinates of the central point. Such files can not be concatenated. A default file name of fort.14 is provided because that is the default Fortran unit to which potential maps are written by DelPhi.
For a Grasp Property File, the user is given the choice of surface or atom property, and then the particular property to be written (if the user wishes to add comment lines to this file this must at present be done by hand - editing the file externally). One should note that the user does not get to choose which vertices and which atoms have their properties exported as all such are exported in Grasp property files. The reasoning behind this is that since the files do not contain any atom or vertex information other than the sequential position in the file, selecting a subset of, for instance, atoms, would not necessarily be sequential. Writing a property file for such a selection would create a file almost impossible to interpret, and which certainly could not be read back in. If a subset of properties is required, the user should export a property in a PDB file, or list the properties to to the textport with the "list" command and capture them using the cut and paste feature of the window manager.
The History File option will write all the commands processed by the program via the textport to the file history.dat. Note that only commands will be written, not selections passed to the program via the textport in the context of a menu request. The user can then edit this file and add comment lines by making the first character of that line a "!".
Cavity Surface Points as PDB will write a list of accessible surface points which belong to cavity surfaces (assuming these have been calculated) as if each such point was an atom, i.e. in PDB file format. The file is always named cav.pdb. One use of this file has been to add these pseudo- atoms to a pdb file and prevent this volume from being assumed high dielectric by DelPhi. (Note this is not assured of achieving this goal if the cavity could accommodate a sphere of diameter twice that of a water, but this rarely ever occurs).
Macro to File writes the definition of an already exisiting macro to a file. The user is asked for a filename and then to pick an entry from the Macros menu.
RGB/Snapshot File writes the currently displayed picture to an Iris "ipaste" rgb file.
4.7 - Formal Subsets Menu
Fix Dials to World
Fix Dials to a Subset
Make a Formal Subset
Remove a Formal Subset
Remove a Subset Rotation
Fix a Subset Rotation
Formal subsets may be a selection of atoms or surface vertices or both. If both, we refer to the subset as being of mixed type. Mixed type subsets come in two flavors - those where atoms were selected on the basis of proximity to a set of surface vertices, or those where surface vertices were selected on the basis of proximity to a set of atoms. Up to 100 formal subsets may be created. Upon creation, each subset is given a unique name by Grasp, or the user may provide a name. Formal subsets are formed to enable independent rotations and translations of a subset of a structure or to provide a unique label for a certain set of atoms and/or vertices.
The "world" has one transformation matrix associated with it and each formal subset has an additional unique such matrix. By "world" is meant the entire view including all atoms and vertices. The total transformation matrix for a subset is the product of these matrices. All subset rotations and translations of a formal subset change the subset's own private matrix, but have no effect on the world matrix. If newly defined subset is itself part of a formal subset which has been moved relative to the world, then the new subset will inherit the matrix of the previous subset.
Fix Dials to World and Fix Dials to a Subset allow the user to attach dials either to the world or to any formal subset. Once a formal subset is created and named, the dials are automatically assigned to that subset to the exclusion of all other atoms and/or vertices. If the user opts to connect the dials to another formal subset, the user is presented with a list of the subsets created so far. If active formal subset rotation mode (Control A) is in effect, the dials are still automatically attached to any new subset, however this is no longer significant, unless the user quits the mode immediately, since manipulations are only applied to what the cursor first lies upon. Note that choosing the world or a formal subset for the dials turns off the this mode.
Make a Formal Subset creates a formal subset. Grasp will prompt the user with the standard options for selecting a subset: command line selection, a particular molecule, a scribed surface, etc. These atoms or vertices then become the new formal subset. If the user want to make a mixed subset, the criteria used in associating surface with atoms or atoms with surface is distance. This can be distance in terms of atom center to vertex distance, atom center to vertex distance minus the Van der Waals radius of the atom, or "contact", which means that the surface and atom are related in that the atom was used in the creation of that bit of surface.
The names of formal subsets are derived from the constructed surface number of the surface, or the molecule number of the atoms, and any previously named subsets. For instance, if the user has selected atoms from the molecule 2, and it is the first such subset, then the name suggested would be "m2:a", "m" for molecule, "2" for molecule number, and "a" for the first such subset. If it was the second subset from molecule 2 and at least one atom in this selection is not contained within "m2:a", then the name suggested is "m2:b". If it is totally contained within "m2:a" then the naming becomes hierarchical and the name is "m2:a:a". If the atoms make up exactly all of one molecule then everything from the colon to the right is dropped, so that a subset containing all of molecule 2 is simply "m2". Note that molecules are not automatically formal subsets, they have to be defined as such. If the atoms are from more than one molecule then the "m" number is set to 0, so that the first such subset would be "m0:a", the second, if not included in m0:a, would be "m0:b", etc. The same rules apply to surfaces, where the surface number substitutes for molecule number. For mixed subsets, the rules for atoms with associated surface are applied as if there