Reference Manual for Contruction of
Presentations in Protein Explorer (PiPEs)

  1. Design Concept: Presentation Contents Go Within the PDB File Header.
  2. Format of the PiPE Block in the PDB File Header.
  3. Using PiPE Elements.

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.

A large advantage of the in-PDB-header scheme for PiPE is that only the PDB file(s) need to be downloaded in order to have a local copy of a presentation that can be used off-line. Chime contains a mechanism for saving the PDB file currently displayed. This means that no special arrangements need be made to enable downloading of an in-header presentation -- if you can see it in your browser, you can save it!

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).

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.

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.

Most of the elements described below are illustrated in the PiPE Template.
  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:

      ! 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:

      ! 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.