This document was written with Bill Barton's help while we were both at MSKCC. Bill is now at VCU.
Ah, the joys of the arcane GRASP command syntax.
About half of the trivial operations in GRASP can be done using the pulldown menu. Press the right button and rummage around for the desired option. However in order to do anything more elaborate you will have to use the GRASP command line language, which is unparalleled in it's terseness. This tutorial is some sort of attempt to give you an idea of how to do simple things in GRASP, and handle some of the command-line syntax.
In what follows, anything that looks like Read->PDB File->Show List is a menu traversal (PDB File option within the Read menu, Show List option within the PDB File menu). Menu selections/traversal are handled using the right mouse button.
Reading and Displaying PDB files
Start GRASP. It may already be set up as an alias for you (type which grasp) to check, and if not use /usr/people/programs2/grasp/grasp on the SGIs. We don't have GRASP for Linux. Nobody has.GRASP pops up with a graphics window and a small terminal window. Arbitrary text typed into the terminal window will be ignored, just to frustrate you.. There's a trick to getting command text accepted, and we'll talk about that later (for the impatient: type the FIRST character of the command over the graphics window, type the rest of the command in the text window once it pops up). In version 1.3, you type the whole text in the graphics window instead of the textport.
Read your PDB file using the menus. Click the right mouse
to bring up the menu. Traverse the menu Read->PDB File->Show
List, select your PDB file. GRASP displays it as CPK. You can
hide the CPK using:
Display->Hide->Atoms
and restore then using:
Display->Show->Atoms->YES!
and you can show the bond representation by:
Display->Show->Bonds->YES!
(and Display->Hide->Bonds to get rid of them)
You can manipulate the molecule (rotation) using the left mouse button. GRASP also responds to the dials on the SGI.
Displaying Molecular Surfaces
Most of the usefulness of GRASP lies in it's abilities to display molecular surfaces around the molecule. First draw the bond representation (for speed) using:Display->Hide->Atoms
Display->Show->Bonds->YES!
now calculate the molecular surface using:
Build->Molecular Surface->All Atoms
which will display a plain gray/white surface on the molecule.
Coloring Molecular Surfaces
The plain molecular surface is not a particularly attractive object to behold. You usually want to color it using some residue property. The related HowTo page tells you how to color according to sequence conservation, but many simpler options are available within GRASP.To display surface curvature, first build the molecular surface, then Calculate->Surface Curvature->All Surfaces->All Atoms. The coloring scheme can be tweaked by moving the mouse arrow over the coloring bar and using the left and middle mouse buttons to change the values associated with that color.
One of the basic tricks is to understand that you can color the residues any way you feel inclined, and then color the surface using the atom color. In order to do this last step you need to issue the command vc=a (vertex color = atom color). To issue this command, put your mouse over the graphics window and type the first letter of the command "v". The text window will pop up and let you type the rest of the command "c=a". GRASP executes the command "vc=a". Although this seems like the dumbest user interface idea known to mankind, this is actually how GRASP handles user text input. In v1.3 or later you just type vc=a in the graphics window, which is somewhat friendlier. If GRASP seems not to respond to things you type at the textport, you've probably forgotten to type the first character in the graphics window. Note that you don't type the "v" twice - GRASP copies it from the graphics buffer to the text buffer.
Coloring Residues and Atoms
If you want to color residues, you need to know some simple GRASP syntax. Generally the syntax is PROPERTY=VALUE or PROPERTY=-VALUE to select everything except the value. Values are case insensitive. Numerical values can be specied as ranges PROPERTY=(FROM,TO) or by comparisons PROPERTY=>x or PROPERTY=<y.Coloring: the command c=N (N is an integer) causes the atoms to be colored according to color N (see below for the definitions). The related commands vc=n, bc=m, kc=n, ic=n set the colors for surfaces bonds, backbone boxes and pair-wise interactions. Setting the color to zero makes the object disappear. vc=a colors the surface from the atom color. Just typing c=1 will color ALL atoms white, for instance.
Subsetting atoms: the command a=string selects only those atoms that match "string". E.G. a=oe1 selects atoms "oe1" or "OE1", a=oe? selects "oe1", "OE1", "oe2" and "OE2". a=ba selects backbone atoms. a=sch selects non-backbone atoms (a=-ba does the same thing). an=n selects a range of atom numbers e.g. an=(1,500) selects the first 500 atoms. For obvious reasons this is not the most useful command.
Subsetting residues: the command r=string selects only those residues that match "string". E.G. r=lys selects residues "lys" or "LYS". r=crg selects residues that are formally charged (Lys, Arg, Glu, Asp). r=hyd selects hydrophobic residues. r=pol selects polar resides. You can always negate the selections (r=-hyd, r=-pol). rn=num selects the residue number E.G. rn=245 and can also include a range E.G. rn=(245,247). You can also specify a chain via ch=a.
You create atom colorings by combining these commands with a comma as a separator:
ch=a,c=2 colors all of chain A red (color 2) r=hyd,c=3 colors all hydrophobic residues green (color 3) vc=a map the color changes to the surface
The application of commands is sequential: if you color 1:100 as red and then 50:250 as green, 1:49 are still red at the end of the command.
Other commands that we have little or no use for include:
| Command | Meaning |
|---|---|
| q | Assigned charge |
| R | Assigned radius |
| p | Assigned potential |
| x | PDB x coordinate |
| y | PDB y coordinate |
| z | PDB z coordinate |
| X | Screen x coordinate |
| Y | Screen y coordinate |
| Z | Screen z coordinate |
| m | Molecule number |
| S | Acc. surface area |
| d | Distance |
| cd | Assigned color |
| vn | Vertex number |
| C | Surface curvature |
| s | Surface number |
GRASP Coloring Scheme
^P (Control-P) brings up the color palette| Index | Color | Red | Green | Blue |
|---|---|---|---|---|
| 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 | Gray | 125 | 125 | 125 |
| 9 | Orange | 200 | 100 | 50 |
The next 9 colors are accessed by the space bar, and so on, and so on. User colors can be defined in the range 10-89. Colors 91-99 are always reset to the values above for 1-9 irrespective of defcol.dat.
Coloring By Potential
One of the major uses for Grasp, historically, has been the display of the electrostatic potential calculated by the quick-and-nasty implementation of Grasp's Poisson-Boltzman potential calculator. The way to do this is as follows:
- Read in your PDB file
- Calculate the molecular surface
- Read in and assign charges
- Calculate the potential map
- Assign the potential to the surface
You already know how to do the first two things. To read in and assign
charges go under the Read menu and do:
Read->Radius/Charge File->full.crg
which reads in the contents of full.crg and assigns these charges to the
atoms in your PDB file.
To calculate the potential do:
Calculate->New Potential Map
To finally display this, do:
Calculate->Pot. via Map at Surfaces Atoms
Et viola! your molecular surface is now color-coded by the electrostatic potential. Bear in mind that it might not show an esthetic mix of red and blue blotches if your molecule is particularly acidic or basic. You can adjust the color mapping of the color bar to the electrostatic potential by using the left and middle mouse buttons while the mouse pointer is over the contour you want to change. Read the GRASP manual for more detail on how to manipulate this. Bear in mind that blue does not inevitably mean positive charge since you can quite happily manipulate the blue contour until it reads negative. Therefore you should always check the color bar for sane values (e.g. red can be far greater or lesser in magnitude than blue, depending on the pI of your molecule).
If the values in the bar read zero, you've either forgot to charge your molecule or you've forgotten to calculate a New Potential Map as above.
Making Macros
GRASP macros are relatively easy to create if you take a look at the file session_record. This file is created and updated while GRASP is running but is deleted once GRASP quits. Inside this file is a description of everything GRASP has done during the session, so it can be used to recreate a session and to modify it.To preserve session_record, copy it while GRASP is running or kill the program with ^C. The file looks like this:
GRASP HISTORY FILE Wed Sep 18 11:35:40 2002 DRAW DRAW Menu Cascade Begin menu :GRASP | Build menu :This Structure.. | Molecular Surface menu :Which Atoms | All Atoms Menu Cascade End DRAW ROT: Z= 15.945408 ROT: Y= 2.886174 ROT: Z= -15.945408 DRAW ROT: Z= 15.945408 ROT: Y= 5.096077 ROT: Z= -15.945408 DRAW ROT: Z= 40.426113 ROT: Y= 20.299999 ROT: Z= -40.426113 DRAW ROT: Z= 38.893940 ROT: Y= 22.961708 ROT: Z= -38.893940 DRAW ROT: Z= 31.195120 ROT: Y= 24.579870 ROT: Z= -31.195120 DRAW ROT: Z= 30.524588 ROT: Y= 10.335376 ROT: Z= -30.524588 DRAW ROT: Z= 33.281906 ROT: Y= 7.000000 ROT: Z= -33.281906 DRAW ROT: Z= 33.743591 ROT: Y= 0.700000 ROT: Z= -33.743591 DRAWThe ROT lines describe the molecular orientation. Note that these are absolute angles not relative ones so if you are looking for a specific orientation you can chop out all the intermediate ones. Notice also than any menu action is also included in the file, and GRASP can recreate that action from this description.
To create a macro from the session file you need to add Macro Name: mymacro at the top of the file and Macro End as the last line in the file. Chop out the header lines that say "GRASP HISTORY FILE" and give the date - you don't want those. Then you can edit out what you want in the macro and what you don't want in there. To get GRASP to run the macro, do:
grasp -rx grasp.macro(assuming you called the file grasp.macro) and GRASP will execute the contents of the file. Watching it do the intermediate rotations is fun at first, but it's a lot faster if you get rid of unnecessary ROT and DRAW lines once you start tweaking the macro.
You can also read a macro into Grasp using the read function in the menu (Read->Grasp Macro File), and then run it later from the Macro menu. This is especially useful for things like conservation macros from (e.g.) Annotate that don't contain instructions to read the PDB file first, for which you want to read the PDB file in yourself, then invoke the macro.
Keyboard Shortcuts
| ^A | Toggle active subset rotations |
| ^B | Toggle color scale widgets |
| ^C | Change current map (^C over textport kills program) |
| ^F | Toggle full screen view |
| ^L | Fix/free light source |
| ^M | Toggle texport depth (RETURN also does this) |
| ^O | Toggle GRASP boundary box display |
| ^P | Bring up color palette (see above) |
| ^Q | Quit |
| ^U | Toggle unhooking of dials |
| ^V | Repair surface |
| ^X | Toggle cross hairs |
| ^Z | Launch Unix shell |