3 Getting Started

4 Menus

5 Command Line

6 Control Keys

7 Worked Examples

8 Future Developments

Appendix A File Formats

Appendix B .init_grasp Commands

Appendix C Grasp Data Files

Addendum for Version 1.2

References

1 - Introduction (By Anthony Nicholls)

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 modeled 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, surface 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 correlation. So one might want find all residues which are a certain distance from the molecular surface AND charged.

The second method 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: