Design and Methods
ProtSecS/Linear Control Structure 2

This Chime-script was originally written for RasMol (September, 1996). It was never put on the web in the RasMol form because of the importance of having a color key legend which could not be implemented satisfactorily in RasMol. It was ported to Chime in several stages late in 1996 while Chime itself was under rapid concurrent development to version 1.0. The advantages of Chime over RasMol for this kind of presentation are numerous. This implementation involves both html and javascript. My favorite introductions to html and javascript are listed below. Below you will also find introductions to script-writing for RasMol and Chime.

The control structure skeleton of this tutorial is designated Linear Control Structure version 2 (LCS2) for Chime presentations. (Version 1 utilized Chime version 0.99 and was put on the web November 6, 1996.) Detailed instructions are provided for building your own linear tutorial about the molecule(s) of your choice by substituting new content into the control structure provided here. A development/debugging mode has been provided to assist in this process.

The RasMol/Chime-script which generates this presentation consists of over 400 commands (lines). Amazingly, the javascript which controls the presentation consists of over 700 lines. The HTML which accompanies the presentation consists of over 650 lines (excluding the 400-some lines in this design document). Overall, this presentation, which lasts about 5 minutes if the pauses are minimized, comprises over 2,000 lines (about 10,000 words), exclusive of the PDB files involved. The amount of programming involved shows why you will likely find it worthwhile to use LCS2 should you wish to create a linear presentation of your own. You will still have to write hundreds of RasMol/Chime commands (see below for help), but you will be spared having to invent the javascript and most of the HTML.

Design Goals

Mechanisms are provided to enter the Chime-script at any of five major sections, and to replay the current section. A continuous-play mode is provided for situations in which unattended operation is desired. A development/debugging mode is provided to assist when new content is installed into LCS2.

640 x 480 Pixel Projection Window

The 640x480 window is created by the javascript (js) function show64() in the file show64.js. Higher resolution could be achieved easily by changing the pixel dimensions specified in this function.

The display window is created without a menu (although one is present during debugging). This conveniently prevents bookmarking somewhere in the middle of the Chime-script.

Five Sections

It turned out that if the startup script were handed to Chime as part of its invocation (as the src in the embed tag), the Chime-script began executing before other parts of the frame containing Chime were ready (at least in debugging mode), e.g. the message display area was not yet in place when the first messages began arriving. The solution adopted is to invoke Chime with a dummy script file which does nothing. Upon exiting of the dummy script, detected by the MessageCallback function, the main script is sent to Chime (see msgcall.js).

Chime 1.0 does not report name of the Chime-script file used to invoke Chime in an <embed debugscript=on src=...> tag with a script filename.spt message. In contrast, all Chime-scripts called after Chime is invoked with a script command are so-messaged. This means that the monitor which displays the currently executing Chime-script is never informed of the invoking Chime-script file. In LCS2, neither the dummy invoking Chime-script file startup.spt nor the dynamically generated main Chime-script startup_script are reported in the Chime-script execution monitor. This seems acceptable since we are really only interested in the section-scripts (e.g. alpha1.spt) and their subscripts anyway.

Starting in the Middle

Each of the five Chime-script section files starts by clearing the previous atomic coordinate file (zap), and loading the requisite PDB file. Although the last 4 sections all use the same PDB file (lysozyme.pdb), it was deemed unnecessary to avoid reloading this file since the time involved was hardly noticeable.

Pauses

or Next or

In order for the javascript to be able to take appropriate action when Chime executes a pause, Chime calls a javascript function each time it encounters a pause in the Chime-script, and each time a pause is released. The function to be called is designated when Chime is invoked with <embed ... > (see chime.js) with the syntax

PauseCallback="OnPauseCallback"

Debug mode provides a monitor frame at the top of the window. The monitor frame displays the name of the script file (and subscript files) being executed and the number of the script section which will be executed if the replay button [<] is pressed. The latter is set periodically by the RasMol/Chime script itself as it progresses. For example, to specify that section 3 should be the entry point if the replay button is pushed, the command is javascript set_replay(3).

An html form textarea shows each script command as it executes. Trace modes are provided for stopping after each script command (single stepping), stopping as each new script file is entered, or stopping when any user-specified word or phrase is encountered (trap mode). Upon stopping, an option is provided to interrupt the script, whereupon manually typed commands (including javascript commands!) can be executed.

Since the first script file will have started playing before access to the single-step trace button is provided, single-step tracing in the first script can be invoked by including the command 'javascript toggle_single_step()' in the script file.

In debugging mode, the dummy frame needed for javascript to be able to send scripts to Chime for immediate execution (see chiimmed.js) is large enough to be seen. (In lecture mode it is invisibly small). If immediate-mode script execution fails, you can view the source of the dummy frame to proofread it. Also, in debug mode, the immediate script button in the dummy frame is not hidden so that it can be clicked for test purposes.

Building Your Own Tutorial about the Molecule(s) of Your Choice

1. Create a RasMol/Chime script in sections. This can be done in the following steps.

   1. Select and explore the PDB file(s). Search for a PDB file (or files) which illustrate the structural features you wish to teach. It is probably easier to explore these molecules in RasMol, rather than Chime. Chime is capable of much more effective presentations, but is more complicated to use for preliminary explorations.

   2. Outline the presentation and divide it into major sections. Outline the presentation. Divide it into major sections each of which deals with a single topic or a few closely related topics. Note the five sections in this Protein Secondary Structure (ProtSecS) Tutorial. For review purposes (after seeing the entire script), the student or lecturer will be able to start playing the script at the beginning of any section. Each section should probably use a single PDB file. Most likely you will want at least several sections, and even in a very long tutorial, you probably won't need more than a dozen to twenty sections.

   3. Write a script for each section.. See the Guide to Script Creation in RasMol and Chime. Most of the content of each script will be RasMol commands (all of which work in Chime). Chime's command language includes a few additional commands, not available in RasMol, which are particularly important for controlling presentations. Most notable are clock-timed delay and move commands, and view-save, view-restore commands. Therefore it may be simplest to develop each script initially in RasMol, using pauses where later (in Chime) you will add smooth movements (such as rotations and zooms) or delays.

      Each of your section-scripts should be a self-contained module which will run from start to finish on its own. Therefore, each should start with a 'zap' command followed by a 'load' command to load the relevant PDB file. If more than one section uses the same PDB file, each section should load the file redundantly (at least during development). This makes it easy to start running any section at random. If the PDB file is very large and slow to load, and was used in a previous section, you can adjust the final scripts to inherit the PDB file when moving from one section to the next, loading it only when jumping into a middle section. The 5 sections in ProtSecS range in length from 75 to a little over 100 lines of commands each. Their filenames are given above. Yours can have any names you wish. Test: Make sure each script runs properly.

2. Embed the section scripts into Linear Control Structure version 2. The steps for putting your section-scripts into LCS2 are as follows.

   1. Download ProtSecS and make a copy in a new folder. Instructions for downloading are provided. Make a new folder named according to the subject of your tutorial, and copy the ProtSecS files into it. Bookmark both the original ProtSecS (file index.htm) and your new copy separately. This will allow you to run either for comparison, or inspect the files in the original as needed. All operations below are, of course, to be done in the new folder, leaving the original ProtSecS folder intact.

   2. Revise the Table of Contents. Edit the file index.htm to reflect the contents of your tutorial. Please include an acknowledgement to Eric Martz with a link to http://www.umass.edu/microbio/chime/protsecs. Each section should be started with the javascript enter_section(n) where n is the number of the section.

   3. Revise startup_script creation. Edit the file startup.js, supplying the names of your section-script files. If you developed your scripts in RasMol, now is a good time to insert Chime-only commands (such as move and delay) to make full use of Chime. Use debug mode to help fine-tune your scripts. Test: At this point is should be possible to play the tutorial from start to finish, or beginning with any section, but the legends will be missing. It will not yet be possible to start in the middle or replay a section.

   4. Add legends. Each legend may consist of a color key plus some text (as in ProtSecS) or, if you wish, you can write html/javascript to create a different kind of legend. In the existing legend format, the color keys are one-cell tables generated by javascript functions in the file legend.js, Modify these functions to provide the color keys you need. The text for each legend is specified in the Chime-script by assigning quoted character strings to javascript variables. For example, the first legend is created with the following series of commands in the file alpha1.htm:

      
      javascript legend_key = "chon"
      javascript legend_text_centered = false
      javascript legend_text = "9-amino acid alpha helix.  "
      javascript legend_text += "Backbone atoms only (no sidechains)."
      javascript put_legend_globals()
      

      The function put_legend_globals() writes the legend html into the legend frame. Test: It should now be possible to play the tutorial from beginning to end with all legends being changed at the correct times. It will not yet be possible to replay sections.

   5. Specify sections to replay. Insert commands in your Chime-script files to specify which section to replay when the yellow button is pushed. For example, the command to set section 4 as the target of the replay button is javascript set_replay(4). You may not always want to change the replay target section immediately after the section begins. That would mean that pressing the replay button after the first image of the section would simply regenerate that image. Often it may make more sense to delay changing the replay target to the current section until after the second or third image into the section. You can watch the replay section monitor at the upper right in debug mode. Test: You should get an appropriate replay response from any point in your tutorial.

   6. Describe your design and methods. Replace the file design.htm with a new one which acknowledges and provides a link to the original Linear Control Structure version 2 and describes any new methods or design goals which you have introduced.

   7. What did I forget? I think you should be finished now, but I haven't tested these instructions yet. If I forgot something, please email me!

References

1. Lemay, Laura. Teach yourself web publishing with HTML 3.2 in 14 days, Sams.net Publishing, Indianapolis IN US. 1,054 pages. Good overview of html, html serving, CGI, javascript, and java. Published June, 1996.
2. Wagner, Richard, ed. Javascript unleashed, Sams.net Publishing, Indianapolis IN US. Published October, 1996. Coverage up to Netscape 3.0. 869 pages plus CDROM. Thoroughly indexed.