Preparing RasMol-Saved Scripts for Teaching

Provided for the NSF Educational Molecular Visualization Workshops
Eric Martz, PD.
http://www.umass.edu/microbio/rasmol/workshop.htm

If you are reading a paper version of this document, it is also available at http://www.umass.edu/microbio/rasmol/prssft.htm
Software, molecules, and visualization help is at the RasMol Home Page, http://www.umass.edu/microbio/rasmol

  1. What this document is about.

    Crucial Preliminaries:

  2. Installing RasMol so it can find your scripts and PDB files.
  3. Troubleshooting your installation & PDB-opening.
  4. Give your PDB and script files portable filenames.
  5. Saving portable scripts!

    The Main Event:

  6. Save scripts of desired views from RasMol, then play them back!
  7. Troubleshooting script playback.
  8. What RasMol forgets to save! (And how to fix it.)

    Optional Enhancements for RasMol:

  9. Manually type script calls into a master script, with a text editor.
  10. Add echoed captions to the master script.
  11. Gather several master scripts into a super-master script.

    Delivering your RasMol Scripts through the Web via Chime

  12. Install your scripts in a Chime web page with buttons, color keys, and descriptive text.


1. What this document is about.

For an introduction to RasMol, see the Quick Start at http://www.umass.edu/microbio/rasmol/rasquick.htm.

This document assumes that you already know how to obtain PDB files of the desired molecules (http://www.umass.edu/microbio/rasmol/whereget.htm ), and to use RasMol to get the views you need of these molecules for teaching purposes. (By a "view" we mean a particular representation, color scheme, orientation, and magnification of a molecule.)

This document explains how to save the views you wish to show your class, and how to play them back smoothly in the correct order. It also explains how to deliver these views through the Internet/Web via Chime.

2. Installing RasMol so it can find your scripts and PDB files.

It may be best to create a new folder to receive your saved scripts. Put the needed PDB files (or copies of them) in this folder.

Now you must install RasMol so that this folder is RasMol's working/local directory. Otherwise it will not be able to find either the scripts or the PDB files.

3. Troubleshooting your installation & PDB-opening.

To test your installation, run RasMol and use its File, Open menu to open one of the PDB files in your scripts folder.

4. Give your PDB and script files portable filenames.

One of the big advantages of a Chime presentation is that, with a smidgeon of foresight, it will play on any platform (Windows 3.1, Windows 95, Macintosh, unix). We strongly recommend that you give your PDB and script files names which will be acceptable on all platforms. If you don't bother, sooner or later you are likely to regret it. (It is much more work to fix this after the fact: after renaming your PDB files, you'll need to change the load commands in each script file.) The rules are that the name should consist of not more than 8 characters including only lower case letters, digits, and the underscore character. Only one period is allowed, just before the "extension": PDB files should end in ".pdb", and script files in ".spt". These "file extensions" are highly desirable in all situations and are mandatory in some situations, such as when the presentation is on a web server (and see notes for other situations). One platform, unix, treats filenames as case sensitive; this is why we strongly recommend all lower case for filenames. When you put your presentation on the web, some people WILL view it in unix, and they'll complain if it doesn't run (trust me). Here are some examples:

Filename Comments
1d66.pdb OK
gal4_dna.pdb OK
gal4_dna BAD: ".pdb" missing
Gal4 DNA.pdb BAD: upper case letters and imbedded space
gal4.dna.pdb BAD: only one period is allowed
gal4_dna_complex.pdb BAD: more than 8 characters before the period
a010.spt OK
a010 BAD: ".spt" missing
View One.spt BAD: upper case letters, embedded space

5. Saving portable scripts!

There is a crucial trick for making RasMol-saved scripts portable. Instead of using RasMol's File menu to Open your PDB file, type the command load "filename.pdb". The result of this trick is that scripts you save from RasMol will be portable, provided that you always have the scripts themselves, the requisite PDB files, and RasMol (or its working/start-in folder) all in the same folder. If you open the PDB file from RasMol's menu, it remembers the full absolute pathname of the file, and saves it into the script. When you put the script in a different folder or system, it can't find the PDB file. The 'load' command, given without a PDB filename path prefix, causes RasMol to save the PDB file 'bare', with no path prefix.

If you forget to 'load' your PDB file, the symptom will be that your script will run in the original RasMol folder, but will not run when the script + PDB files are in a different folder or system, and will not run in Chime. You can fix this easily by using a text editor to delete the absolute pathname prefix from the load command in the 7th line of each RasMol-saved script. For example, change

load pdb "C:\M1\RASDAT\SCRIPTS\DNA-RSS\1D66.PDB"
to
load pdb "1d66.pdb"
Note that we also changed the filename to lower case! You may need to do this even if you don't need to delete a pathname prefix. Failure to change the filename to lower case will cause your presentation to fail on case-sensitive operating systems such as unix.

6. Save scripts of desired views from RasMol, then play them back.

Save each view into a script file by typing the RasMol command save script filename, where filename is a filename of your choice. We strongly recommend organizing your presentation into sections called Page A, Page B, etc. If you name your first script for Page A a010.spt, your second script a020.spt, and so forth, then these scripts will play in the Chime template immediately, since it expects this script naming convention.

Typing the command script filename into RasMol plays back the script (for example script a010.spt).

7. Troubleshooting script playback.

Sometimes when you type script filename into RasMol's white command line window, the view you saved fails to appear. Here are the possible reasons and the solutions.

Note: This document troubleshoots RasMol-saved scripts only. Troubleshooting of manually typed/edited scripts is beyond the scope of this document.

8. What RasMol forgets to save! (And how to fix it.)

RasMol (version 2.6 beta 2a) fails to save certain information into the script: the selected subset of atoms, the center of rotation, background colors other than black, and any new terms you have defined with RasMol's "define" command.

This explains some results which might surprise you. Suppose you have only the sulfur atoms selected when you save the script. After playing back the script, you will get the same view as when you saved the script. However, commands which operate on the selected subset will operate on all atoms (since after playing back a script, all atoms are selected). Just before you saved the script, the command 'color yellow' would color only the selected sulfur atoms. After playing back the script, the same command would color all atoms yellow.

You can fix these problems if you wish by manually editing the script you have saved from RasMol. Instructions are in the Appendix.


9. [Optional] Create a Master Script.

If you are planning to present your scripts with Chime, you may skip this step and the next two [Optional] steps.

Suppose you have saved a dozen scripts from RasMol, and now you want to be able to show them quickly to a class, without typing script filename for each one (and without remembering all the filenames!).

You'll need a text editor. Word or Simple-Text are recommended on the Macintosh; Notepad or Wordpad is recommended on Windows95. The goal is to save your typed commands into a plain text file, not a formatted word processor file. (If you use Wordpad or Word, be sure you save files as plain text!)

Create a master script file (let's call it master-a.spt) containing a list of script commands, each followed by a pause command. For example, depending on the names you gave your scripts, your file might contain:

script "a010.spt"
pause

script "a020.spt"
pause

script "a030.spt"
pause
The command script "a010.spt" causes RasMol to show the first image. The pause stops script execution until you press any key. While the script is paused, you can rotate, zoom, and translate with the mouse. When any key is pressed, the first pause is released, and the second image comes up, and so forth.

10. [Optional] Add echoed captions to the master script.

When you run the script master-a.spt, nothing appears in RasMol's command line window until the script is finished. However, the command line window need not be wasted: you can use it to display captions. All you have to do is use RasMol's echo command to write lines of text to the command line window. (Unfortunately, you have no control over the font size or color. Chime has the advantage in this regard!)

To clear old commands or captions out of the command line window before displaying a new caption, use a series of echo commands with no text.

Here is what you might put after the first script in master-a.spt:

script "a010.spt"
echo
echo
echo
echo
echo
echo
echo "Here is the view from my first script"
pause

Actually, you should put something more useful in the caption -- something which will remind you what to say in lecture!

If you plan project your saved images to a class, you will do better to install your scripts into the Chime template, (see below) and play them back in Netscape with Chime. This gives better control (you can back up, use large fonts, and color keys), and allows you to deliver your scripts to your students via the web. If you are going to use Chime, don't bother to add echoed captions to your master scripts.

However, it may be worth adding captions to your master script if (1) you are going to have students play your scripts in a computer lab, and (2) they know how to use RasMol fairly well. That way, the scripts can be pre-installed, and the students have the full power of RasMol at their disposal. They can stop after any script (if at a pause, with Ctrl-D), and apply RasMol commands to the view. The Chime template provided at http://www.umass.edu/microbio/chime/prsswc/template.htm has no command-line interface, and thus limits what students can do. If you are ambitious, a template with a command line can be downloaded from http://www.umass.edu/microbio/chime/chimehow/fs_cmdln.htm

11. [Optional] Gather several master scripts into a super-master script.

If you have saved a lot of scripts, they can be grouped into topics A, B, C, .... Scripts for topic A will be displayed by master-a.spt, for topic B in master-b.spt, and so forth.

You can avoid having to type each master script into RasMol's command line window during your presentation. Use your text editor to create a super-master script named supermas.spt. Typing script supermas.spt once into RasMol runs all of your master scripts, showing your many views in proper order. For example (the comments preceded by # can be tailored to your topics):

script "master-a.spt"     #Chain A (protein)

script "master-b.spt"     #DNA

script "master-c.spt"     #Chain A plus DNA

script "master-d.spt"     #Zinc (Cadmium) ions and Cysteine sulfurs

script "master-e.spt"     #Contact atoms

You can kill this many-script sequence at any point by holding down the Ctrl (control) key while pressing D (Ctrl-D).

The super-master script (or any individual master script) can be adapted to a given audience easily. If you wish to omit some images, just comment them out (precede the script command with #). If you wish to show views in a different order, simply rearrange the sequence in the master script.

RasMol provides no mechanism to back up during a master-scripted sequence. Again, Chime solves this problem.

12. [Optional] Install your scripts in a Chime web page with buttons, color keys, and descriptive text.

Instructions are in a separate document, How to Install Your Scripts into the Chime Template, available at http://www.umass.edu/microbio/chime/prsswc/2fc-how.htm


Technical Notes

It is not necessary to read these notes in order successfully to save and play back RasMol scripts. These notes are provided for those interested in technical details.

  1. RasMac's PDB filename/signature requirements for Opening a PDB file from the File menu. This assumes that the PDB file's contents are correct. If the filename contains characters other than letters, digits, spaces, and the underscore character, it may not appear on the menu or may not load. Characters known to cause such problems include /<>%[]?. The filename need not end in ".pdb". The signature type must be "TEXT" in order to appear on RasMac's File, Open menu.

  2. RasMac's PDB filename/signature requirements for loading a PDB file from a script. It is strongly recommended that the filename be quoted (either single quotes or double quotes will do). While sometimes quotes can be dispensed with, sometimes they cannot (e.g. if a comment follows the filename on the same line), so it is best to play safe. A subtle mismatch between the filename in the script load command and the actual filename, such as an extra space character, will cause the PDB file to fail to be found. The load command seems to have no requirements for the file signature; for example, a PDB file with signature type "????" and creator "????" can be loaded. However, the naming requirements specified under Note 1 should be adhered to.

  3. RasWin's PDB filename requirements for opening a PDB file from the menu. The filename must end in ".pdb" in order to appear on the open-menu spontaneously. However, in Win95, you can type "*.*" in the "File name" slot (with no file selected), click on "Open", and all files will be listed. You can then open a file whose name does not end in ".pdb". In 32-bit RasWin under Win95/NT4, the above strategy can display and successfully open a long filename. However, if the filename contains one or more imbedded spaces, RasWin32 will display it on the open menu but not load it. (In Explorer, at least, Win95 removes leading/trailing spaces from a filename.) Failure to load produces no error message, but can be verified by using RasWin's File, Information menu: "Number of atoms ... 0" means nothing was loaded. Unlike with the Mac, any Windows-legal filename characters seem OK. For example, RasWin32 can open a file named "1..,,`~%!@#$^&()[]{}p.pdb". Nevertheless, we strongly recommend following the portable file naming conventions outlined above.


Appendix. [Optional] Fixing what RasMol forgets to save in your scripts.

These fixes require that you use a text editor to modify the script file saved by RasMol. Windows: use Notepad or Wordpad. Macintosh: use Word (not SimpleText). Be sure to save files from Wordpad or Word as plain (ASCII MS-DOS) text.

Selected subset of atoms. At the very end of the script file, add a select command(s) which will select the desired atoms.

Center of rotation. At the end of the script file, add a select command(s) to select the atoms which should be the center of rotation, then add the command 'center selected'. If these atoms are NOT those which should end up selected, this section must precede a final selection command(s) at the very end of the script file.

Defined terms. Add commands to select groups of atoms for which you wish to define terms, following each set with the command 'define term selected', where term is the term you wish to define. If the resulting selected atoms are NOT those which should end up selected, this section must precede a final selection command(s) at the very end of the script file.

Nonblack background color. If your view uses a background color other than black, the script RasMol saves will fail to change the background color due to a sequence bug in RasMol's script writing process. RasMol erroneously specifies the background color before loading the PDB file (a bug). This order needs to be reversed. Here is an excerpt from the beginning of a RasMol-saved script with a white background:

zap
background [255,255,255]
load pdb "1d66.pdb"
This will work if you simply change the order of these lines to:
zap
load pdb "1d66.pdb"
background [255,255,255]


* Macintosh users: Use Word to edit RasMol-saved scripts or PDB files, being sure to save the edited scripts as plain text. Open the script after you select All files from the Open menu (since these are not Word documents). You can create short scripts (such as master scripts) with SimpleText. However you cannot edit scripts saved from RasMol, or PDB files with SimpleText (because they don't have a SimpleText signature/icon, and they may be too long).