The Grasp Primer
Written by Ben Hitz, for frustrated Grasp users everywhere
This primer was written for casual or non-users of Anthony Nicholls 'GRASP program. Its purpose is to teach a user the basics as well as some handy tricks that can be used with the GRASS Molecular Surface Viewer, or with your own GRASP projects. It is not a complete manual. The current manual can be found here.
Table of Contents
This section will demonstrate how to access various Grasp menus, as well as manipulate the primary images in the display window.
Grasp doesn't do much of anything unless you read some atoms in first. Either use the menus (see below) to read in a pdb file, or run Grasp with the name of a pdb file on the command line. If the filename does not have the extension .pdb, Grasp will prompt you for the file type (which should be "atom") for a PDB file.
There are three ways to input commands in the current version of GRASP. One is by using the menu cascade - to access the menu right-click anywhere on the screen, repeat as necessary to descend into the menu-cascade hierarchy. In this primer a menu cascade will be written with the names of the 'buttons' separated by colons - each colon represents a separate level in the cascade of right-clicks. Sometimes menu options require you to type in input, usually these are under the button 'Enter Selection'. The second method is the command-line. This is how you make selections, as well as issue other important commands. Note that in general, menu cascade commands cannot be directly typed on the command line.
Handy Example: To quit Grasp, chose the 'quit Grasp' option in the menu cascade. Or in code: Cascade : Quit Grasp
Handy Example: To hide the 'atoms' (CPK or other spheres, usually) try: Cascade : Display : Hide : Atoms
Handy Example: To build the molecular surface for all non-water atoms: Cascade : Build : Molecular Surface : Enter String : r=-wat
Handy Example: Calculate : Distance Array : A Set of Atoms to Another Set of Atoms : Center to Center : A Molecule : molecule 1 : A Molecule : molecule 2. This will calculate the distance from molecule 2 to molecule 1, putting the results in the 'distance' field for the atoms in molecule 1 ONLY. To get the distance for molecule 2, do the same calculation with the molecule numbers reversed.
These are the things that Grasp displays in your window. The short list is: Atoms, Bonds, Surfaces, and Worms. There are some others, but you can find them yourself (or read the manual). Basically, there are two overlapping ways to display these. One is the default - or "Discreet Colors" option. Other times it is known as "User Defined Colors". The way these work is to assign a particular selection to a particular color. For more on this see the next bullet in this section (Properties and Colors). The most important colors are color 0 (zero) and 1 (one). Otherwise known as Black and White. Color 0, however, is a trick color, it actually means UNDISPLAY this selection; similarly color 1 is often used by Grasp experts (and Macros!) to mean DISPLAY this selection. One can select any of the objects separately or in part and assign them colors, you can also transfer the colors from one object to another.
Handy Example: To color the ATOMS the same as the BONDS, type the following command: bc=a (in the English tongue: bond color = atom [color]. Wait a minute, you say, shouldn't that be bc=ac? Nope, the c is implied. Welcome to the wonderful world of GRASP syntax). This also works for vc=a (vertices, i.e., surface) , and wc=a (worms, i.e., ribbons).
Colors in grasp are defined in terms of RGB values - each component varying from 0 to 255. There are also 100 'slots' for which particular colors are defined. Normally only the first 9 or 10 are used - but you can mix your own colors in the Color Palette. Type Control-P to enter the color pallet, 'space' to switch to the next block of 9 colors, and Esc to exit. This is covered in greater detail in the manual. The first 10 grasp colors are:
|
# |
Color |
RGB definition |
|
0 |
Black |
(0,0,0) |
|
1 |
White |
(255,255,255) |
|
2 |
Red |
(255,0,0) |
|
3 |
Green |
(0,255,0) |
|
4 |
Blue |
(0,0,255) |
|
5 |
Magenta |
(255,0,255) |
|
6 |
Cyan |
(0,255,255) |
|
7 |
Yellow |
(255,255,0) |
|
8 |
Grey |
(127,127,127) |
|
9 |
Steel Blue Orange |
(50,100,200) (200,100,50) |
Using these color numbers, each object or selection can be assigned a color using the following typed commands:
c= # (set atom colors)
bc= # (set bond colors)
wc= # (set worm - or ribbon - colors)
vc= # (set surface vertex color)
This, however, is not how surfaces are usually colored! Usually they are colored by a totally different mechanism - color by property.
Surfaces, atoms, and worms (AKA Ribbons) can be colored by property, but Bonds cannot. The Grasp surfaces created by the GRASS viewer are colored by property, not by 'Discreet Colors'. The way this works is the following. Grasp allows atoms, surface vertices (the discreet components of a surface), and "worm sections" to have numerical properties associated with them. These are - for atoms and surfaces - Potential, Distance, and two 'General Properties'. Atoms have the additional "inherent" properties of Charge, Area, and X, Y, and Z coordinates. Surfaces have the additional property of Curvature. Ribbons ("worms" in Grasp parlance) have some additional properties as well. In General these properties are just labels - any real number can be assigned to them, but there are some important exceptions. After the potential is calculated (or read in from an external Delphi file), it can be mapped to the surface points and atoms. This will always overwrite the Potential field. Similarly Distance and Curvature calculations overwrite their respective fields. The General Property fields are designed to be 'catch all' categories - for instance the Occupancy and Temperature Factors in a PDB file can be read into General Properties 1 and 2, or the Charge and Radii (from a Delphi-formatted PDB file) can be stored there. Also, various quantities can be calculated and stored there via the Calculation and Simple Property Math cascades. This will be explained in detail in the Tricks section of this primer.
When surfaces, atoms, or worms are colored by property, Grasp displays a color-property scale (one for each property) at the top of the display window.
Not only is this a handy display item it also has some
nice features: First you can change the displayed scale by middle or left-clicking
on the 
at the right end of
the scale. Left clicking widens the scale by shifting the end points out
to more extreme values, while middle-clicking narrows the scale. Also,
by right-clicking the Label 
to
the left of the color scale you initiate a short-cut menu, which allows
the following:
Reset scale to absolute values.
Input new relative values for the scale.
Change the colors assigned to the scale (enter in RGB units).
Change the property displayed.
Change the representation of the object displayed. (for example, to a transparent or 'dot' surface, or tubular worms instead of flat ribbons.)
Of these options, changing the colors is probably the most important, as this is the ONLY time this option is available. Please be aware that these menus are a little buggy, and may not always work. Particularly, they have a tendency to fail in 'Stereo' mode - so usually I turn off the stereo, change the color (or whatever) and turn stereo back on.
Selections and using the command-line interface is one of the hardest things to do in Grasp. Unfortunately, it is also one of the most useful. I will not try to cover every command here - just the one I find most useful. For a more complete treatise see The Grasp Manual. The basic concept is simple: You want to apply a command (via command line _or_ menu cascade) to a subset of the objects that are currently loaded in the program. These commands are covered in detail in the manual under subsetting. The general syntax is:
<selection 1>,<selection 2>,<selection 3>, ... <action>
*or*
<action>, <selection 1>, <selection 2>, <selection 3> ...
No selection will select all atoms (or vertices). The selections are ANDED; there is currently NO ability to select <selection 1> OR <selection 2>, however individual object selections are OR'D with commas.
Handy Examples: m=1,2,r=hyd,a=c, c=3 --> color blue all carbon atoms belonging to hydrophobic residues ('hyd' in Grasp is defined as Ala, Val, Leu, Ile, Met, Phe or Pro) in molecules 1 or 2. vc=0,C=>-50,p=<-2,p=>-2 --> undisplay all surface vertices with abs(potential) > 2 and curvature > -50. (This will display concave surface patches that are electrostatically ~neutral.)
Known "Quirks": the surface number selection s= does not always work. In fact, you cannot color different surfaces different colors using the obvious vc=2,s=2! The work around for this bug is to first color the atoms the color you want the surfaces to be and then use the vc=a command, which works. This is, by the way, also exactly how you color the surface belonging to lysines blue; first color lysine ATOMS blue, then type vc=a. Another feature is that you cannot select part of a surface, and color it by a different property or surface type (i.e., potential and curvature or Rendered and Mesh). You can do different surface display functions on different "sides" in stereo mode (see trick).
Grasp uses several types of files. First and foremost is the PDB format file. This file contains the coordinates and names (and residue names, numbers, and chain ids) of the atoms in your molecule, or complex. Grasp handles these pdb files in it's own special way: Atoms are numbered sequentially, not as numbered in the file, and it handles residue numbers that are non-positive integers, or chain ids that are A-Z very poorly. (In case you are curious, BOTH of these options are allowed by the current definition of Brookhaven PDB files!). It also ignores the distinction between ATOM and HETATM, and ignores all non-atom records except for TER. (and special FORMAT headers, mentioned below). Atoms separated by TER lines in the PDB will be defined as separate molecules by Grasp. By default, Grasp ignores the Occupancy and Temperature Factor fields in a PDB file. There are three ways to read in these fields: In all cases, the first two lines of the PDB must read
GRASP PDB FILE
FORMAT NUMBER=N
Where N is 1, 2 or 3. Format 1 reads the two fields as Charge and Radius of each atom, Format 3 reads them as (atom) General Property 1 and 2. Format 2 is the same as 3, but with free format for higher accuracy real numbers. Details can be found in the manual, here. This is in fact how the GRASS server reads in most of the properties that is uses. Other types of files that are important: radii/charge file, surface file, and potential map.
The next type of important data file is a radii or charge file. These files are usually used in electrostatic calculations - but in reality all they do is assign a real number (charge or radius) to atoms they identify. The key to enlightened Grasp thinking is realizing that you can put ANYTHING in a charge field, and display it on the surface (or backbone, or what have you). I don't advise calculating the potential due to these 'bogus' charges... The format is simple and can be found in the manual here. You can also use the radii as dummy variables- but be careful as the current radii are read by Grasp when building surfaces or displaying atoms - also, unlike crg files you can only distinguish atom name and residue type for radii.
The next type of file is a potential or 'phi' map - this is a BINARY format file which contains potentials (real numbers) on a 65 x 65 x 65 grid. The normal use of these files is to run an electrostatics calculation with Delphi, use it to write out a phi map, and then display the phi map with Grasp. You might want to use Grasp to output these files to save them - as Grasp can only store two maps internally; if you want to compare and contrast more than that.
The last type of file is the surface file. This is another BINARY file; it contains information on how to construct the surface, as well as various surface properties (if it was created by Grasp). Also, these files can be created by Delphi and read into Grasp (instead of using the Build : Molecular Surface option.
The important thing to remember here is that Grasp was designed to display qualitative electrostatic potentials in a fast and robust manner. When using Grasp (or any other FDBP solver, for that matter!) to calculate potentials, you must always make sure that
With Grasp, any atom with a real radii will appear at 'actual' size if you Cascade : Display : Atoms : Yes! (default). Checking the charges is a little more difficult; you can color the atoms by charge, and inspect them visually, or write out a new PDB file with the charges assigned. Checking the charges becomes critically important if you are using partial charges (presumably with hydrogens). One quick way to do this is to Cascade : Simple Property Math : Atom Properties : All Atoms : Op(Array) = Array : Contraction over Residues :Op(Array) = Scalar : Sum : Charge : General Property #1. Then color the atoms by General Property #1. Most residues should appear with zero, or integer charge values.
If you are interested in more quantitative electrostatics, you should use the program Delphi. Use Delphi to write out a phi map, and simply read it in with Grasp. You will still have to build a molecular surface, and map the potentials to the surface!. Also, be sure to use the command:
out(phimap,format="grasp")
in your Delphi parameter file, if you are NOT using the standard 65 x 65 x 65 grid. Another thing to consider is that accurate LOCAL potentials, will in general require charge sets with partial charges (i.e., PARSE, CHARMM, CVFF91). In the case of proteins or nucleic acids - this probably means you will have to add hydrogens to your X-ray structure.
In general, using Delphi has no significant effect on the qualitative potentials displayed on the surface of a molecule, while using partial charge sets (either with Delphi or Grasp) can have such effects.
An interface is simply a selection of atoms (or surface vertices) that lie on the interface between two molecules (or even, parts of molecules). There are at least two ways of defining interfaces. One is by distances; all atoms (vertices) from one molecule within a certain distance of another. Another is by excluded accessible area. The 'distance' method is simple - just calculate the distance between you two selections, and then "select" (color) based on a distance threshold.
Example: Calculate->Distance->Surface to Surface (choose two difference surfaces). then: vc=0, d=>1.4.
Example: Cascade : Calculate : Area of a Surface/Molecule : Molecule : Excluded Area (2 atom selections). This area can be selected by S=>0. However, there is a bug in some versions of Grasp - you will probably need to copy the "Area" of the atoms to another (unused) property, using simple property math. Another useful technique is to contract this surface area (usually sum) over residues, so that you can select residues with excluded surface area. In order to use this to define a interfacial surface, you must map the (atomic) area to the surface.
This is a very common FAQ. Basically, the trick is that you can only alter the color of the "bounding box", which is normally invisible. To replace the "default" black Grasp background with a single color do the following:
One common use of this is to make a white background to save toner when printing screen shots.
The simplest way to do this is to color the ATOMS of each residue, or residue class with a r=lys,arg, c=4 type of command (in this case color all lysines and arginines blue). Do this for all residue types you wish to color. Then use the command vc=a to map the selected colors to the molecular surface.
There are a couple ways to do this. First you need to have a correspondence between each residue and a number (i.e., the variability at that position). You can then manually set the color of each residue as the above 'Coloring Surfaces by Residue Type' but coloring each individual residue by number as well. The second way is to create a dummy charge file, with the variability "index" in place of the charges. Then Cascade : Read : Read/Assign Crg/Siz file. Now the variability is stored in the atom charges, so you have to map the charges to the surface using: Cascade : Simple Property Math : Map Atom Values to Surface : Charge : <property> Where <property> is the surface property you wish to use as the variability. The last way is to create alter your PDB file such that the temperature factor or occupancy fields (2 fields after the x-y-z coordinates) contain your varaibility data. You will also need to add a header to your new PDB file as described in Data Files, above. Then do the above mapping of atom properties to the surface (using the appropriate properties!).
This is relatively simple. First calculate the potential. Then orient the display so that it shows the view you want. Turn on the interpolation plane using the menus, or Control-Y. The plane always appears parallel to the screen, half way through the box. You can turn on the bounding box with Control-O to see where this will be. Now display the potential on the surface - this will also display the potential on the interpolation plane (using the same scale). If you actually want to see the molecular surface with the potential, you have to Map the potential to the surface first (otherwise it will be white). You can also build 2-D contours that display on this plane (whether or not you should the plane).
The trick here is simply knowing what is possible, and using your imagination. Definitely read the sections of the manual describing simple property math. The most important things you need to know are: Copying fields (i.e. properties) - to do this you just multiply by 1 or add 0 and put the result in a second field. Also, mapping atom values to surfaces or worms is critical to display most 'atom only' based properties on the surface (or worm) - for example temperature factors, or charge, or (as mentioned above) sequence variability. You can actually calculate electrostatic energies using these functions: For example, calculate a potential map, and Map it to the atoms. Now each atom has a potential and a charge. In KT units, E = 1/2 q x phi, so you can just multiply the atom properties of potential and charge, and divide by 2. If you want to calculate energy differences, you can first subtract two potential maps!