Guide to "Movie" Script Creation for RasMol and Chime

by Eric Martz, June 10, 1996

Please send suggestions for improvements to the author. When this document has been revised, the new version will be provided on the RasMol Classic Main Page.

Contents

Preliminaries

• Is this document obsolete yet?
• Using a local, private copy of this document.
• What do you need to know before reading this document?
• What is a script?
• RasMol-created scripts vs. manually-created "movie" scripts: refresh and pause.
• How is a conventional movie different from a "movie" script?
• Isn't there an easier way to make a script?
• Should I use RasMol or Chime?

Creating a script

• Script files: working directories, nomenclature, transportation, running scripts.
• A script for all molecules.
• How do I start a writing a new script?
• The translation bug.
• How to write a well-structured script.
• Captioning script images.
• Providing titles.
• How do I spin or rock a molecule?

• Working in the middle of a long script.
• Allowing user interaction or backing up.
• How can script timing be contolled?
• How can two molecules be docked?
• How can a "within" operation be speeded up?

Appendices

• I. What does RasMol need for better script management?
• II. How can I extract portions of a PDB file?
• III. Revision history of this document.

Preliminaries

This document was written in June 1996 for RasMol version 2.6 beta-2. If a later version is now available, this document is likely to be obsolete, at least in some parts. Check Getting RasMol on the RasMol Web Site to find out what version is currently available. See also below regarding easier ways to write scripts.

Using a local, private copy of this document.

If you have a fast, reliable connection to the Internet, we recommend that you save a bookmark to this document, and read it within your web browser (e.g. Netscape). If you prefer to use a local copy, you should check the version on the web periodically for revisions and updating.

To save a local copy, in Netscape select File, Save-as, and specify a filename such as "makescrp.htm". To read your local copy, in Netscape select File, Open and then select your copy of the document. You can read it just fine on a computer which has no Internet access, but you must first install a web browser in addition to a copy of this document.

What do you need to know before reading this document?

We'll assume that you know how to use RasMol's pull-down menus, the mouse, and RasMol's command-line interface. We won't explain the RasMol commands mentioned below; you can look them up in the RasMol manual by clicking on Help, or in the manual on the web. (You can use your browser's Find command to search the latter!)

If, under Windows, clicking on Help in RasMol doesn't work, you need to put the file "raswin.hlp" in the same directory as your "raswin.exe" program. Alternatively (for Windows) you can set the environment variable RASMOLPATH to tell RasMol where to find the RASMOL.HLP file. You can get the help files at the RasMol web site under Installing RasWin.

If you don't have the background described above, a good place to start is with one of the tutorials for beginners which takes you step by step through the features of RasMol. The tutorial by David Marcey is a good place to start and will be sufficient preparation. The tutorial by Andrew Coulson is excellent for a more extensive and advanced tour.

For script creation, you'll also need a plain-text editor; that is, an editor which saves what you type as plain ASCII text into a disk file. This is in contrast to a word processor (such as WordPerfect or MS Word) which (unless you tell it otherwise) saves what you type in a proprietary format inscrutible to RasMol. However, most word processors provide an option to save text as plain ASCII (aka DOS) text -- you must then be sure to remember to use this option.

What is a script?

A RasMol script is a plain-text (ASCII text) disk file containing a series of RasMol commands. Suppose the script disk file is named "myscript.spt". Then the RasMol command 'script myscript.spt' will run the script. It is as if you had typed each command in the script file into RasMol's command-line window.

RasMol-created scripts vs. manually-created "movie" scripts: refresh and pause.

rotate y 3
refresh

repeated 30 times will rotate the molecule about the Y axis in 3-degree increments (3 degrees between frames), then stop after a total of 3x30 = 90 degrees of rotation. (See spinning below for how to do this most easily.) In contrast, the command "rotate y 90" has the same effect at the end, but does not show any intermediate positions.

RasMol 2.6 beta-1 also provided the "pause" command. It does a refresh, but in addition waits for any keystroke before continuing. A "paused" script is an excellent way to accompany a lecture. RasMol 2.6 beta-2 allows script execution to be cancelled with Ctrl-D (or Ctrl-Z) issued at a pause. Prior to this, there was no way to stop execution of a script under Windows short of rebooting! There is still no way to stop a script which lacks pauses (see below). We shall refer to a manually-created RasMol script which contains refresh or pause commands as a "movie". The quotations indicate that it is not a conventional movie.

How is a conventional movie different from a "movie" script?

Conventional movies of molecules are often greatly oversimplified animated cartoons. These lack the gripping authenticity of a RasMol display, but have the advantage that complex processes are much easier to depict than in RasMol. Another major difference is that a RasMol "movie" script is considerably easier to create than is a conventional movie.

Isn't there an easier way to make a script?

At present no such easier way is available. Moreover, it is likely that such a "movie"-making interface will produce a RasMol script, which may often need fine adjustments made by manual editing of the script file itself. Therefore, it seems likely that the skills involved in creating scripts manually will remain useful even when automation is available, and especially during the transition when early beta-test versions of these automation programs first become available. So, read on!.

Should I use RasMol or Chime?

If you are thinking seriously of writing scripts for RasMol, you must install Chime and look at some of the impressive tutorials already written with it.

Chime version 1.0 is a free program, the creation of Tim Maffett, Mitch Miller and coworkers at MDL Information Systems, Inc. Although about 1/2 of RasMol's 30,000 lines of source code were used in Chime in heavily modified form, MDLI has invested over two person-years in Chime's >80,000 lines of new source code. Thus, less than 17% of Chime's source code is derivative of RasMol. Chime can do some impressive things that RasMol cannot do, including 2D representations and animated displays of XYZ files.

Chime requires a frames-capable browser such as Netscape version 2, and is better-supported by Netscape version 3. This means that the Netscape page can have a scrollable text window next to a molecular graphics window. Not only can the text window readily accomodate a lengthy tutorial (far surpassing the abbreviated echoed captions possible in the RasMol command line window), but the text can contain push-buttons to implement successive changes in the graphics display.

Chime does have to be downloaded and installed once (an easy process), after which is is invoked automatically. RasMol installation is slightly more difficult in that the chemical MIME types have to be configured once manually in the Netscape Options Helpers menus. When invoked in Netscape (e.g. by downloading a PDB file), RasMol comes up in a separate window, whereas the Chime graphics frame appears directly on the web page, within the Netscape window. Multiple Chime graphics can appear on a single page if desired.

Chime has the potential for great "movie" scripts. It supports the full RasMol script language, although at present it lacks a command line interface, so scripts would probably more easily be developed in RasMol and then ported. Since it can be controlled by hypertext markup language (HTML), backing-up (not now possible in a RasMol "movie" script) is easy.

Chime is becoming the preeminant vehicle for academic tutorials involving molecular visualization (see the biochemistry tutorials from the U. Kansas Medical Center). However, at present, the documentation for creating Chime tutorials is in its early stages, and several crucial script-support features are lacking (as they are in RasMol).

Bottom line: Even if you aspire to write Chime scripts, it will be advantageous and perhaps essental to write them in RasMol for now, and then port them. So, read on!.

[Caveat: the above opinion is that of one who has never written a Chime script, though he tried once.]

Creating a script

However, for scripts which are intended to be moved as a package over the web, unpacked, and then run from the local computer (as are all of my scripts released prior to September, 1996), it may be useful to use other filename types (suffixes) for subscripts called only by "script filename" lines in higher-level scripts (see How to write a well-structured script). Here are some possibilities:

Filename ending	Script category
.spt	top-level (main)
.sub	high-level subscripts
.col	single color
.cs	color scheme
.res	restore previous orientation etc.
.roc	rocking the molecule
.rot	rotations (multi-frame)
.tit	title(s)
.utl	utility (small operations not in any other category)
.win	window sizing/alignment instructions
.z	end-of-subscript image (for debugging use only)

Such naming facilitates finding the desired subscript when editing or copying existing subscripts into a new directory/folder for creation of a new script. Such a naming scheme has only come to my attension after I wrote several large scripts and found the presence of several dozen script files, all of the same filename type, rather confusing. (As of August, 1996, I have not yet used this proposed naming scheme in any released scripts.)

Working directories/folders. A script consists of a top-level script file which calls various subscript files. The PDB files which need to be loaded by the script can be in a different directory or folder, provided that the "load" commands reference that directory or folder, for example

load "pdbfiles:1lfa.pdb" #Macintosh
load "pdbfiles\1lfa.pdb" #Windows

However, having different portions of a complete set of script files in different directories/folders complicates packing the script into a single compressed file, and unpacking it so as to maintain the separate directories/folders. Therefore, it is recommended to put all files pertaining to a single script (and only those files) in a separate directory/folder given the name of the script.

The document which accompanies scripts, 00sptdoc.htm, has the most up-to-date information on running scripts under various operating systems. What follows is more general information.

Macintosh. In order to have RasMac find the script files, the RasMac program must be in the same folder as the script. Use File, Duplicate to make an extra copy of RasMac, and drag the copy into the script folder. (Be sure you are not dragging an alias -- this will not work!)

Now you can start a script by running the copy of RasMac in the script's folder, and then typing (for the example dna3.top) script dna3.top in the command line window, and pressing Enter.

For further details, see 00sptdoc.htm. Please send suggestions for improvements to yours truly.

UNIX. I suppose that script-running under unix is similar to script-running under Windows 3.x; however, I have no experience with RasMol on unix. One difference is that an auto-start script must have .rasmolrc as its name. Also, since unix makes case distinctions in filenames, load commands must refer to the files to be loaded with the correct case. To facilitate inter-OS portability, it is recommended that all PDB files be referenced with lower case filenames in load commands.

Windows 3.x. In order to have RasWin find the script files, they must be in its working directory. The "working directory" is specified in the Windows "File, Properties" dialog. Since each script typically comprises dozens of files, it helps to keep each script in its own separate working directory. This means that you need to use the Windows "File, Copy" command to make a new copy of the RasWin icon for each script. It then helps to change the "File, Properties, Description" field to the name of the script. The result is a series of RasWin icons, each with the name of the script which it runs.

Once the RasWin properties are set correctly (see paragraph above), you can start a script by typing (for the example dna3.top) script dna3.top in the command line window, and pressing Enter.

A RasWin icon can also run a script automatically. First, the RasWin icon must have its working directory set to that of the script (see above). Then, you must create a plain (DOS/ASCII) text file named RASMOL.INI which contains (in the case for example of dna3.top) the single line script dna3.top. Such a file can be created with your word processor if you save it with the plain (DOS/ASCII) text option into the script directory.

RasWin is also supposed to be able to start a script by specifying the script as a parameter in the "File, Properties, Command-line" field, for example to run script "dna3.top", "c:\raswin\raswin.exe -script dna3.top". However, RasWin 2.6 beta-1 and beta-2 have a bug which causes a script started in this way to die at an early pause. Were an unpaused script to be started in this way, you would need at least one pause to enable opening the command line window and proper positioning of the windows. Therefore, until this bug is fixed, the method in the previous paragaph is recommended if you want an automatic start.

(Can anyone supply any details which differ for Windows 95, Windows NT, OS/2, etc.?)

Transportation. It is recommended that all files comprising a single script be packaged into a single compressed file for transportation around the Internet. This is best done with a self-extracting file which checks for its own integrity during unpacking, such as a DOS EXE file made with PKZIP followed by ZIP2EXE, or a Macintosh self-extracting archive (.sea) which has been binhexed (.sea.hqx). PKZIP and Stuffit Lite can be obtained from any major shareware web site.

A script for all molecules.

#COLOR HYDROPHOBIC GRAY, POLAR GREENBLUE, AND CHARGED GREEN.
define temp selected #REMEMBER CURRENTLY SELECTED RESIDUES
select temp and hydrophobic
color [180,180,180] #GRAY = EQUAL INTENSITIES OF RED, GREEN, BLUE [MAX 255]
select temp and polar
color greenblue
select temp and charged
color green
refresh #PUT THE NEWLY COLORED IMAGE ON THE SCREEN
select temp #RESTORE THE ORIGINALLY SELECTED RESIDUES

script colorhyd.spt #FIRST, COLOR BY HYDROPHOBICITY/CHARGE
define temp selected
select temp and backbone
color [150,150,150] #DARK GRAY
select temp

The PDB file should be copied to the directory reserved for the new script. To enable the script to run on diverse computers, the "load" command should not specify anything but the PDB filename. For example,

load pdb "E:\RASWIN\SCRIPTS\DNAREG\3CRO.PDB"

load pdb "3cro.pdb"

Thus, your new script might look something like this. The italicized lines were extracted from the RasMol-written script. The non-italicized lines were added manually to recreate the desired image.

zap
load pdb "3cro.pdb"

rotate z 176
rotate y 64
rotate x -148
#refresh may be needed here to correct translation bug
translate x 5
zoom 200

wireframe off
backbone on
color group

select *a or *b
backbone 0.5
select *a
color magenta
select *b
color greenblue

Suppose that in several places in your script, you need to establish the same color scheme. Copying the series of identical color commands into each place where it is needed would be poor structuring. If you later need to change the color commands, you'd have to change them in every place where they are used. Being human, you're likely to leave one inadvertantly unchanged. In a well-structured script, you separate these color commands into a small, separate subscript file (such as the colorhyd.spt example elsewhere in this guide). Then, you call the subscript ("script colorhyd.spt") wherever you need to invoke this color scheme in your script.

The top level script of e.g. "dnareg.spt" should contain only calls to major-chapter-scripts, something like this:

script intro.sub    #INTRODUCTION: AMINO ACIDS, NUCLEOTIDES, REPRESENTATIONS
script dna.sub      #THE DNA DOUBLE HELIX (PROTEIN NOT SHOWN)
script protein.sub  #OVERVIEW OF PROTEIN BACKBONE STRUCTURE
script hbonds.sub   #HYDROGEN BONDING WITHIN THE PROTEIN
script contacts.sub #AMINO ACID CONTACTS WITH NUCLEOTIDES

Often it is desirable to rotate a molecule for a total range of 90 degrees around X, Y, or Z. For example, the script "x90-2.scr" rotates the molecule 90 degrees around X in 2 degree increments. The script "x-90-3.scr" rotates -90 degrees around X in -3 degree increments. (The script "y3.scr" should be named "y90-3.rot".)

Captioning script images.

Another method involves the use of RasMol's automatic script generation mechanism. In DNA3P, subscript dna3a.scr loads the PDB file, and the 5 subsequent subscripts dna3b.scr through dna3f.scr each continue with the previous image. A good method is to run e.g. dna3a.scr, then "save script dna3az.scr" (the Z signifying the end of the script). Then whenever you want to test-run dna3b.scr, you can first "script dna3az.scr" to establish the requisite initial image. Of course, the "Z" files are not part of the final script. (You may prefer to name these files e.g. zdna3a.z, to make it easier to locate them in a sorted directory listing.)

Warning: RasMol 2.6 beta-1 and beta-2 do not save several important items in automatically written scripts. These include the selection of the subset, the center of rotation, and any defined tokens. Therefore, these commands must be added manually at the end of the Z script if needed.

Warning: beware of the translation bug.

Allowing user interaction or backing up.

One (somewhat tedious) solution to this is to write a script so that following each pause, the molecule is re-oriented to the desired position. In general, I have not bothered to do this, but there are a few examples in the script DNA3P. For example, in the subscript dna3aa.scr, a subscript "resetatp.scr" is used in several places following a pause to guarantee the correct orientation of the molecule. The user is invited to rotate the molecule at pauses during this script (see "Operation of Script" in 00sptdoc.htm).

There is presently no mechanism to allow the user to back up in a script, that is, to re-view the current section as many times as the user wishes. Chime does allow this. Once a mechanism is provided for backing up, the image at the beginning of each section will need to be re-established. Therefore, writing scripts as described above to allow user interaction may facilitate backing up with a future version of RasMol.

How can script timing be contolled?

Delays are needed in unpaused scripts, and have been implemented as in the files "delay5.scr", "delay1.scr", etc. which can be found in the DNA3P script. These use repeats of "rotate x 360, refresh" commands which consume CPU time but have no effect on the image. The resulting delays are unsatisfyingly machine-dependent.

Lacking built-in support to make delays and movements machine-independent, a number of tricks are possible to ameliorate the situation. Increasing the size of the graphics window, or increasing the resolution (e.g. a change from 640 x 480 pixels/screen to 800 x 600) slows down a script. In Windows, the 32-bit version of RasWin is several-fold faster than the 16-bit version.

If necessary, the script itself can be modified to change the overall speed. For example, rotations in 3-degree increments can be changed to 2- or 1-degree increments to slow down a script, and the number of delay cycles can be changed. However, adjusting the timing of a long (one- to two-thousand line) script in this manner takes several hours.

How can two molecules be docked?

There is an unfortunate bug in UCB-RasWin which prevents its use in complex scripts. A "zap" command in a script causes the program to hang, although zap works fine when issued from the command line window. Until this bug is fixed, little script development can proceed in UCB-RasWin.

How can a "within" operation be speeded up?

• Fix the translate bug.
• Fix the bug which causes RasWin to die at the first pause when a script is invoked as a command line parameter in the Windows Properties dialog.
• [Obey CONECT records even when only a few are included in the PDB file to indicate double bonds.] THIS IS FIXED IN 2.6 BETA-2! See the FAQ for an example.
• A 'set group selected' mode which would make group coloring apply only to the selected residues. This would avoid having protein coloring continuous with hetero residues such as phospholipids or waters.
• A 'set coordinates fixed' option to prevent RasMol from changing the atomic coordinates when saving a PDB file.
• An environment variable which allows RasMol to find the help file in a directory other than the working (script) directory.
• "Show defined" should list all defined tokens with atom counts and and also all chain designations with atom counts.
• "Esc" should erase the current command line.
• "Slab" should be enhanced to accept relative movements of the slab plane, such as 'slab +2' or 'slab -5'. This would allow a script to move the slab plane more easily.
• Keep the center centered during zooms.

96/09/20 Further important revision to the Script files nomenclature section and related sections (e.g. .spt).

96/08/31 A large number of mostly minor changes and updates. Substantial revision to the Script files and Chime sections.

96/07/10 Fixed broken link to PDBTOOLS.

96/06/19 Revised section Script files: working directories, nomenclature, transportation, running scripts. Included Macintosh details in this section.

96/06/14 Added link to instructions for configuring Netscape for chemical/x-pdb helper application RasMol.