I. Design Concept: Presentation Contents Go Within the PDB File Header

In a scheme begun in 2003, the entire contents of a presentation are within the header of the PDB file(s) that contain the atomic coordinates needed for the presentation. The presentation contents are specified in a PiPE block inserted at the top of the PDB file header. Here is a schematic illustration of this.

This departs from the design used in pilot presentations made in 1999-2000 and in the initial ConSurf Server in 2001-2002. In these earlier designs, each presentation resided in a directory containing numerous .htm, .js, and .spt files. A disadvantage of this was the complexity of downloading a local copy of a presentation. Frustratingly, in the first several years of the operation of the ConSurf server, it was not feasible to download a result for display off-line.

The in-PDB-header scheme occurred to us only when we had begun to work with the PDB header within PE in late 2002. Access to the PDB header within PE (javascript) was problematic until Jean Holt of MDL kindly implemented a new feature in Chime 2.6 (released December 2000) at the request of Eric Martz. This new feature is a command "show pdbheader" that conveys the entire PDB file header to javascript via Chime's messageCallback() mechanism. Jean-Philippe Demers implemented the initial code that obtains the header from the message stream and parses it (September 2001).

(The "show pdbheader" mechanism works extremely well in Netscape 4 and the Gecko browsers (Netscape 7.1 or later, Mozilla, Firefox), but a bug precludes the use of this mechanism in Internet Explorer, where an alternative and more cumbersome mechanism must be employed.)

II. Format of the PiPE Block in the PDB File Header

What is the "PiPE block"? Ordinary PDB files can be thought of has having two "blocks" of different kinds of infomation: the "header block" and the "atomic coordinate block". PDB files used in PiPEs are modified by adding a third block, the "PiPE block", to the beginning of an ordinary PDB file. The "PiPE block" is a block of text lines that specify what your Presentation looks like, and what views it produces. It contains the html, javascript, and PE/Chime command scripts that make up your Presentation. Here is a schematic diagram of the PiPE block.

Structure of the "PiPE block":. The PiPE block is a single, uninterrupted block of lines inserted into the PDB file header that specifies a presentation. Although the PiPE block can be located anywhere within the header, it is recommended that the PiPE block be first, followed by the original PDB file header. The format of the PiPE block is as follows.

• "!" is the first character of each line in the PiPE block, thereby identifying the line as part of the PiPE block.
  Since no record name in the PDB format begins with "!", software that uses PDB files (other than PE) will ignore lines beginning with "!".
• The PiPE block is typically placed at the beginning of the PDB file header, followed by the conventional header which begins with a record line named HEADER.
• The PiPE block must be a single group of lines, not interrupted by any other kind of lines.
• Each type of content within the PiPE block begins with a segment-type identifier in which the leading "!" is followed, without an intervening space, with a word indicating the segment type as listed below. With exceptions noted below, the remainder of the segment-type line is taken to be content of the type specified.
  • !html In-line hypertext mark-up language.
    Example:

    !html Here is some <b>bold text</b>.

  • ! (space must follow "!") A "continuation line".
    Continues adding content of the previous type, where permitted (exceptions noted below). (Content type changes when a new segment-type is specified.) Example:

    !html This sentence is completed
    ! on a continuation line.

  • !! A comment.
    A "comment" is a line with information for the person building a program (or PiPE block) which is ignored when the program is executed -- in this case, comments are ignored by Chime and by PE. Comments can be embedded in other segment types, in which case continuation lines following the comment(s) continue the previous segment type. Example:

    !html This sentence is completed
    !! (this comment line is ignored)
    ! on a continuation line.

  • !js // In-line javascript.
    Javascript to be written into the PE control panel in the position in which it occurs in the PiPE block. (Anything in a javascript line following "//" is a javascript comment.) Example:

    !js put_button("@spt view05", "details_view05",
    ! "1d66.pdb");

  • !js.init // Javascript to be executed prior to displaying the first control panel of the presentation.
    Example:

    !js.init pipe_background_color = "black";
    ! pipe_start_spinning = true;

  • !spt #name=script_name # A script of Chime commands.
    Command script segments ("!spt") are a special case in which the segment-type line specifies the name of the script. The script name must be preceded with "#name=". There must be no spaces before or after the "=" and none in the name. Script names may not contain any characters except letters, numerals, and the underscore character. Information following the script name on the same line is ignored. Example:

    !spt #name=view03_uncertainty
    ! select all
    ! color temperature # uncertainty of atomic position
    ! spacefill

    In command scripts, anything after "#" (until the end of the line) is a comment when processed by Chime. The "#name=whatever" is ignored by Chime, but it is not ignored by PE, which uses it to assign the specified name to the script. "# uncertainty of atomic position" is ignored by both Chime and PE.

  • !color color_name color_value
    Named color values may be used in command scripts and to color HMTL text (see Using Named Colors). Each "!color" line must have two words following the segment-type identifier "!color ": a color name, and a color value. All color names must begin with "color_". Color values are typically hexadecimal RGB values, e.g "FFA080" (see RasMol/Chime Color RGB Values), but may be color names recognized by Chime, e.g. "violet". (For a list of color names recognized by Chime, click on Chime's MDL frank to open Chime's menu, then "Select, Change Color To".) Color lines cannot be continued on additional lines. Anything after the color value is treated as a comment and is ignored. Examples:

    !color color_medium_blue A0A0FF
    !color color_dark_red D00000 #optional comment here

  • !details #name=details_name
    Optionally, additional details (text, possibly with hyperlinks, html tags, color keys, and/or static images) can be attached to each molecular-view button. The details pop-up in a small window at the lower left when the button is pressed. Each "!details" line must be followed by "#name=" and then a single word (letters, numerals, and underscore only) naming the details. The name is required to begin "details_". The details are attached to a button by giving their name in the second parameter in the parentheses of a "!js put_button()" line. Example:

    !details #name=details_EF_hand
    ! <center><big>
    ! The EF Hand
    ! </big></center>
    ! 
    ! The EF hand of recoverin binds calcium with oxygens of two ASP's, one GLU,
    ! one THR, and one ASN. Mostly sidechain oxygens are involved, but
    ! also two backbone oxygens.
    ! 

• The maximum length of a line that Chime can process correctly from the PDB file header has not been determined, and may be browser dependent. To be safe, lines should not exceed the standard PDB format length of 80 characters.

III. Using PiPE Elements.

Don't worry about the details of Chime command script language lines shown in the examples below. The command language is documented at MolviZ.Org, but you don't need to learn it. PE's Recorder will record the commands you need, and you can simply paste them into named scripts in the PiPE block, and then call them as explained below.

1. Chapter Title and Subtitle. Javascript variables are provided for specifying the chapter title and subtitle. The title is required, and is used in links in the PE Site Map and QuickViews for returning to the presentation control panel. The subtitle is optional. By default, the title will be displayed centered at the top of the control panel in large, boldface font. If the title is rather long, you can specify that the font not be enlarged. The syntax is as follows:

   !js.init pipe_title = "Structure of Collagen";
   ! pipe_title_enlarged = true; // set to false for smaller title
   ! pipe_subtitle = "Chapter One";

   Warning: The titles themselves must be quoted as shown. Failing to quote them will produce a javascript error that will cause PE to stall during startup! In contrast, the variable named "pipe_title_enlarged" can be assigned values of true or false, and these words must not be quoted (they are Boolean values).

2. Initial appearance: background color, spinning, message box. Several javascript variables control the initial background color (black or white), spinning of the molecule, and whether or not the message box is visible. All of these can be changed at will after the presentation starts. Background color can be toggled with the Bkg button in PE cluster of convenience buttons, present in the PiPE control panel. This cluster also has a Spin toggle button. Typically, the message box is hidden at the outset, leaving only a small frame at the lower left for the Presentation Controls. However, the top edge of this frame can be dragged up or down at will to show or hide the message box, command input slot, PE Recorder control buttons, and access to Preferences, Command Aliases, etc.

   By default, the background color is white, and the message box is hidden. A PiPE chapter will start with a black background and a visible message box when:

   !js.init
   ! pipe_background_color = "black"; // default is white.
   ! pipe_show_commands = true; // default is hide message box, etc.

   It is a good idea to leave the molecule spinning at all times during a talk. Your audience is not familiar with the structure, and when it stops spinning, the 3D structure becomes flat and dead. Therefore, PE's default is to start spinning. However, to conserve computer CPU resources (especially when concurrent PE sessions are running), spinning stops by default after 3 minutes. (Of course it can be turned back on by clicking the Spin button, but only for 3 more minutes per click.) PE has a Preference setting that determines whether spinning will be on or off at the outset of a new session. This preference setting can be overridden in a PiPE chapter. To guarantee that the molecule is spinning at the outset, and to prevent spinning from stopping automatically after 3 minutes, use these javascript assignments:

   !js.init
   ! pipe_start_spinning = true; // default is PE's Preference setting.
   ! top.nonStopSpin = true; // default: spinning stops after 3 min.

   A mechanism is also provided to guarantee that a particular molecular-view button will always start its view spinning (or not spinning). Include these lines at the end of the command script.

   ... [script starts above] ...
   ! spin on
   ! javascript top.spin = true;

   Note that the last line is a script command, not a !js statement. ("javascript" is a command to Chime, causing Chime to execute the specified javascript command.)

   Similarly, a mechanism is provided to guarantee that a particular molecular-view button will always produce a view with a specified background color, regardless of the background color prior to pressing the button. To guarantee a black background, add this line to the end of the command script:

   ... [script starts above] ...
   ! javascript top.force_background_color("black");

3. Named command scripts. Naming a script of commands for Chime enables it to be called from multiple locations, permitting improved structuring of script code. Many Chime websites do this by using files of command scripts (.spt files). These work in Netscape but not Internet Explorer (IE). To work around a bug in Chime's handling of files in IE, PE puts most scripts in javascript strings instead of .spt files. All scripts for PiPE must be included in the PiPE block of the PDB file header, which has the additional advantage that only one file (the PDB file) need be downloaded to capture the entire presentation.

   A script named, for example, active_site_spt, is invoked in another script with the syntax "@spt active_site_spt;".

4. view01 (or for backward compatibility, frontispiece_view_spt) is a special script name reserved for one script in each chapter. This script will display automatically as the initial view for the Chapter. Typically, it is called by the first molecular-view button. Whichever button calls it will be checked at the outset, while all other molecular-view buttons will be unchecked.
   If no script is named "view01", the molecular image frame will be blank (no molecule shown) when the Chapter starts, but the molecule will be loaded and ready for molecular-view buttons to display.

5. Molecular-View Buttons and How They Call Scripts, Popup Details, and Employ Secondary PDB Files. A molecular view button is placed on the PiPE control panel using a javascript function call, as shown below. In this case, the button changes the color of chain A to purple without using a named command script.

   !js put_button("select :a; color purple;");

   Alternatively, the button can call a named command script, for example (assuming a script named "view01" has already been defined)

   !js put_button("@spt view01;");

   The word "@spt" preceding the script name signals calling a named script. Scripts can call other scripts, for example

   !spt #name=view02
   ! @spt view01
   ! select :b
   ! backbone

   Similarly, calls to scripts can be included among other commands in a molecular-view button script, for example

   !js put_button("@spt view02; select :c; cartoon;");

   In addition to changing the molecular view by sending commands or command scripts to Chime, the put_button() function can specify a named block of details to be displayed in a popup window. The details must always be defined and named earlier in the PiPE block with a "!details" line (see above) The details-name must always be the second parameter, for example:

   !js put_button("@spt view01;", "details_view01");

   All the above examples of "put_button()" employ the atomic coordinates ("molecule") included in the primary PDB file -- the same file that includes the PiPE block. However, a third parameter to "put_button()" may specify that the script be applied after a different PDB file (a secondary PDB file) is loaded into Chime. For example:

   !js put_button("@spt view03;", "", "1d66.pdb");

   Note that in the above example, when no details were specified, the second parameter must be given as "" (an empty string of characters) in order to make the PDB filename the third parameter. Alternatively, the name of a details block could have been given in the second parameter.

   Once a secondary PDB file has been loaded, any "put_button()" that does not specify an explicit PDB file will re-load the primary PDB file coordinates before applying its script.

   If a molecular-view button's script should be applied to whatever PDB file is loaded when the button is pressed, the third parameter in that "put_button()" must be "*".

   Only one copy of a large PDB file need be present. This is illustrated by the following hypothetical example:

   1. A very large PDB file "huge.pdb" is the primary (and perhaps only) PDB file used in Chapter 1. It will thus include the PiPE block for Chapter 1, in which form we shall refer to it as "huge_pipe.pdb".

   2. Chapter 2 needs the coordinates in "huge.pdb" as a secondary PDB file. No problem: it can use "huge_pipe.pdb", because a PiPE block is ignored when the PDB file containing it is used as a secondary PDB file.

   3. Chapter 3 uses the coordinates in "huge.pdb" as its primary (and perhaps only) PDB file. The following trick can be employed to avoid duplicating huge.pdb. The primary PDB file for Chapter 3 can be 03_pipe.pdb, containing the PiPE block for Chapter 3 plus, as atomic coordinates, the 2-atom placeholder found in the template PDB files. These two atoms need never be displayed. All molecular-view buttons can specify "huge_pipe.pdb" as a secondary PDB file, including the first button, which could be for example !js put_button("@spt view01", "", "huge_pipe.pdb"); Of course, some of the molecular-view buttons could specify different secondary PDB files if appropriate.

6. Using Named Colors. Assigning a name to a set of RGB color values means that you have to specify the RGB values in only one place. Then you can use the color by name whenever it is needed. The big advantage of naming the color is that if you want to change the color later, you need only change the RGB values in one place, where the name was defined. All subsequent uses of the name will then obey the changed RGB values. The syntax for naming a color was explained above. Below are examples that assume a color named "color_dull_green" was defined earlier. You can use named colors in two ways:

   1. In scripts, to color selected parts of the molecular image, wherever "@color_name" occurs, it is replaced by [x000000] (where 000000 is the RGB color value).

      !spt #name=dull_green_ligand
      ! select ligand
      ! color @color_dull_green
      !
      !spt #name=color_ssbonds
      ! color ssbonds @color_sulfur

   2. Named colors can also be used in HTML to color text to make a matching color key.

      !html <font @color_dull_green><b>Ligand</b></font>

      The above html fragment writes the word Ligand in color_dull_green and boldface.

7. Using "for" loops. For supporting ConSurf (see ConSurf Examples), there is a "for" loop mechanism that works as follows. There are actually ten ConSurf grades ranging from 0 to 9, but to keep the example shorter we'll show only 0 to 2.

   !spt #name=c1
   ! @for $=0, 2
   ! @spt select_grade$
   ! @spt select_and_chain
   ! color @color_grade$
   ! spacefill
   ! @endfor

   Formatting requirements are as follows. Failure of any of these requirements will generate an appropriate fatal error message.

   • "@for $=" must be exact, including exactly one space before the "$=".
   • Following "$=", two integers are required separated by a comma.
   • A space is permitted, but not required, after the comma.
   • The first integer cannot exceed 99.
   • The second integer must be larger than the first.
   • "@endfor" must be present in a line after "@for $=".

   When properly formatted, the above script will be expanded to the following. Note that a copy of the segment between @for and @endfor is repeated once for each iteration, and that in each copy, $ is replaced with the number of the iteration.

   !spt #name=c1
   ! @spt select_grade0
   ! @spt select_and_chain
   ! color @color_grade0
   ! spacefill
   !
   ! @spt select_grade1
   ! @spt select_and_chain
   ! color @color_grade1
   ! spacefill
   !
   ! @spt select_grade2
   ! @spt select_and_chain
   ! color @color_grade2
   ! spacefill

   In order for the above script to work script must have been defined with names select_grade0, select_grade1, etc. and colors must have been defined with names color_grade0, color_grade1, etc.

Again, most of the elements described above are illustrated in the PiPE Template.