Step by Step Instructions for Building
a Presentation in Protein Explorer (PiPE).

Created January, 2005; revised February 2005.

These instructions have not been adequately tested. Don't hesitate to contact Eric Martz ( if something needs clarification, or if you get stuck.

    Prerequisite Knowledge

  1. In some cases, it is unnecessary to spend the time to save command scripts and install them in a PiPE, because Protein Explorer makes it easy enough to show the desired views with its generic exploration buttons and menus.

  2. Understand and accept that if you build PiPEs, and if you put them on a web server, anyone with access to the server URL will be able to download your PiPEs (with no extra effort from you, their author). Then they can run them off-line.

    Of course you can protect your PiPEs simply by stating "Copyright [year] © by [your name]. All rights reserved." (You should add a reliable way to contact you.) Attaching this simple statement to your work makes it illegal for others to copy or sell your work without your permission. You might want to add "Permission is given to use this work or redistribute copies privately for non-profit educational use, such as in a non-profit college or university class, provided no fee is charged for this work."

  3. To construct a PiPE, you will need to be familiar with using Protein Explorer. At a minimum, start with the Demo Movies and do the 1-Hour Tour.

  4. Be clear about what a PiPE is, and is not, by looking at a good example.

  5. To get an idea what is involved in constructing a PiPE, first please take a look at the Overview.

  6. Even after completing the above steps, constructing a PiPE for the first time will likely take at least a few hours, even for a simple one with a few molecular-view buttons. It will take substantially longer if you find it challenging or unfamiliar to use Protein Explorer, use disk files and folders, an HTML editor, and text editors. Regardless, adding more molecular-view buttons, or your second PiPE chapter, will surely go faster.

  7. Download Protein Explorer (make sure it is a version that Supports PiPE, meaning PE 2.7 Alpha or later), and get it running from your local hard disk. You have succeeded if it runs just fine when your computer is disconnected from the Internet. PiPEs require a local copy of PE "cheek to cheek" in order to operate. For all subsequent steps, work from the downloaded PE. You can verify that you are browsing a downloaded file if its URL in the location slot near the top of the browser begins file:///. If it begins http://, then you are getting it from a server through the network.

  8. If you are using a copy of PE downloaded some weeks or months ago, check this document on-line at to see if it has been revised (see revision dates at top under title). If yes, and a new version number of PE is available, download it now and use the newer version. If the version of PE is unchanged, view this document on-line, and if it has a newer revision date, use File, Save As from your browser to save the new version into "Protein Explorer N.NN/protexpl/pipedocs", replacing the older version.

  9. Take a preliminary look at the PiPE Template, trying all links.

  10. Text Editing Tools. Constructing a PiPE requires extensive use of a text editing program, which means a program that saves plain text, without any formatting such as boldface, special fonts, or colored text. Inadvertantly saving PDB files as "documents" (with formatting) will prevent them from working.

  11. HTML Editing Tools. You will also need to edit HTML, primarily the document my_molecules\pipes\mypipes.htm (to add a link to your new PiPEs) and the document my_molecules\pipes\my_pipe1\index.htm (the contents of your PiPEs, chapter by chapter). If you have not edited HTML before, we recommend the HTML editor built into Netscape (either version 4 or 7.1 or later). It is easy to use and works well for our purposes.

  12. Taking a look at the Molecular Structure Presentation Design Guidelines now is likely to save time later, and result in a better product.

  13. Keep your filenames all lower case and don't embed spaces. The Windows and Macintosh platforms don't care whether a file or folder (directory) is named "MyFile" (mixed cases) or "myfile" (all lower case) or "MYFILE" (all upper case); it is all the same file to them. But on unix servers, these differences in case distinguish three files. If you name all your PDB files entirely with lower case letters, you will likely save yourself frustrating and time-consuming repairs if you ever plan to put your presentation on-line. (If you use mixed cases or upper case in naming folders and files, you must be 100% consistent in all references and links.) It is also wise to avoid embedding spaces within file or folder names. The underscore character "_" is acceptable in file and folder names for all operating systems, and can be substituted for spaces. For example, we have used my_molecules instead of "My Molecules".

    Installing Your PDB File into Chapter 1 of the PiPE Template

  14. Make a duplicate copy of the folder (directory) named template located in the "my_molecules/pipes" folders that are included in your downloaded PE, side by side with the "Protein Explorer N.NN" folder. Make the duplicate within the existing pipes folder, side by side with the original. Rename "Copy of template" to a name that describes the topic of your presentation. We'll refer to this new folder as my_pipe1 -- you can actually name it that if you wish. If you give another name, all references below to "my_pipe1" will mean the name you give to this new folder. You can change the name of this folder later without causing any problems. All work below, including adding and modifying files with a text editor, should be done in my_pipe1, never in the "template" folder!

  15. Download the PDB files you need for your PiPE, saving them into my_pipe1. Hint: Display a PDB file by entering its PDB identification code into the slot on PE's FrontDoor (so it is fetched from the Protein Data Bank via the Internet). Once you see the molecule (the view doesn't matter), you can save the PDB file to disk: Click on the MDL frank at the lower right below the molecular image. Select File, Save Molecule As. This method (saving the PDB file from MDL Chime) always saves the file intact, exactly as it was received. The first line of any PDB file should begin "HEADER". If you have any trouble, you can also download the PDB file directly from

  16. The best name for an original PDB file is its PDB identification code followed by ".pdb". Using a different ending than ".pdb" will make the file fail to work properly on most servers. So the file for 1d66 should be named 1d66.pdb. This sort of name should be reserved for unmodified PDB files "as published". Modified files should be given different names, although it is OK if the name of a modified PDB file starts with, or contains, the PDB code. For example, a file containing only the DNA from 1d66 could be named 1d66_dna.pdb.

  17. Inside my_pipe1, make a duplicate copy of the file 01_pipe.pdb (the name doesn't matter -- it is just a spare in case you need it for future reference). Open 01_pipe.pdb in a text editor and get familiar with its contents. In particular, notice the last two lines which you are to replace with your entire PDB file.

  18. We are now going to start editing PiPE files. You might inadvertantly change the file incorrectly, and in some cases this will cause PE to fail to start. Sometimes an error message will tell you exactly what needs to be fixed. Other times, PE will simply stall during startup with no helpful error message.

    Avoid Frustration!
    If you need it there is Troubleshooting Broken PiPEs.

    A good strategy is to "comment out" (change to comments, e.g. prefix lines in the PDB file with "!!") the lines you plan to change so they are ignored by PiPE, and then add the new lines. If the PiPE fails to start, you know the one change you made, so you can probably find quickly what needs fixing, or if necessary restore the previous version from the commented-out lines. If you need it, refer to

    Troubleshooting Broken PiPEs.

  19. Choose the primary PDB file for Chapter 1. Each PiPE Chapter may use as many different PDB files as you wish for its molecular views. One must be the primary PDB file -- the one that contains, in its header, the PiPE block that specifies the entire content of Chapter 1. All others are secondary PDB files. (They need not contain PiPE blocks, but if they do, their PiPE blocks will be ignored in Chapter 1. A secondary PDB file in Chapter 1 could be the primary PDB file for another chapter, in which case it would need a PiPE block for that chapter.) Typically, the PDB file for the first image (view01) in Chapter 1 would be its primary PDB file.

  20. Paste your Chapter 1 PDB file into 01_pipe.pdb: Open your first saved PDB file in a text editor. Select all, and copy the entire file. Open 01_pipe.pdb in the text editor, delete (or comment out) the last two lines (which begin "HETATM"), and then paste the entire PDB file onto the end of 01_pipe.pdb.

  21. Begin a new HTML document for accessing your PiPEs. In the folder my_molecules/pipes/, find the file blank.htm and make a copy of it named mypipes.htm. Now, from PE's FrontDoor, click the link to "Presentations in PE", then the link to "Example PiPEs", then the link to "My PiPEs" (which goes to the new file mypipes.htm that you just created).

  22. In mypipes.htm, make a link to my_pipe1/index.htm. Using an HTML editor (or a text editor if you know how to edit raw HTML) make a link to my_pipe1/index.htm, and label the link with the title of the presentation in my_pipe1. You have succeeded when clicking the link displays the copy of the page entitled "PiPE Template" (with links to Chapter 1 and Chapter 2). Make sure you are not working in the master folder "template" (which thusfar looks identical) -- all changes should be in files within the folder "my_pipe1".

  23. Don't use Internet Explorer for the following steps. Use any other PE-compatible browser. When they are finished, your PiPEs will work in Internet Explorer (IE) too, but not until you have made a special additional files needed by IE (see below), which is best done when the rest of your PiPE is finished, tested, and works correctly in a non-IE browser (none of which need the additional files).

  24. Test your change to file 01_pipe.pdb: View my_molecules/pipes/my_pipe1/index.htm in your (non-IE) browser by clicking on the link you made two steps above. (Make sure this is the file you are viewing, not template/index.htm, by double-checking the address of the file being displayed in the slot near the top of the browser window.) You will see the standard template page with 2 chapters. (We will customize this page later.) Click on Chapter 1 on the PiPE Template page. PE should start up, displaying Chapter 1 with the template control panel, but with your molecule displayed in the molecular image frame. The first three molecular-view buttons should work on your molecule. (If this does not happen, re-check that you did all the steps above correctly.)

    Installing Your First Molecular-View Button (Command Script) into Chapter 1 of the PiPE Template

  25. PiPE Block Syntax. Our next step (below) will be to paste the command script for your first molecular-view button into the PiPE Block of the header of 01_pipe.pdb. Before doing this, you should understand the basics of how molecular-view buttons, HTML, command scripts, and javascript are formatted in the PDB file header. Please take a careful look at Format of the PiPE Block.

  26. Load into PE the PDB file you pasted into 01_pipe.pdb. Don't load 01_pipe.pdb; load the original downloaded PDB file. At PE's FrontDoor, click on Empty Explorer. PE will open with a Load Molecule control panel. Use the Browse button there to load the saved PDB file. (Next time you run Empty Explorer, this PDB file will be on the "Select Previously Loaded PDB File" menu in the Load Molecules control panel.)

  27. Save your first molecular view command script. Use PE's buttons and menus (probably in QuickViews) to achieve a view that you want to show in your PiPE. If you try several things that don't end up as part of the view you want (digressions from achieving the desired view as directly as possible), it is best to close PE and start a new session. Now, achieve the desired view with few or no "side trips". (If you save a script with a lot of "side trips", even though the final view will be correct, the script will be unnecessarily long, and take unnecessarily long to produce the final view.) After you achieve the desired view efficiently, following the start of the PE session, click on the button "Save this view.." below the message box. It may be sufficient to hold the script in the clipboard, but it will be safer to paste it into your text editor and save it to a temporary file.

  28. Paste your script into 01_pipe.pdb: Open the file my_pipe1/01_pipe.pdb in a text editor, and locate "!spt #name=view01", and just below it, where you are invited to paste in your first script. Replace the template's placeholder script with yours. Run your PiPE. Your first view should appear automatically -- and whenever you press molecular view button #1.

    Finishing your PiPE: Options, More Views, More Chapters, Contents Page, Web Server

  29. Options: Background Color, Spinning, Message Box, etc. Near the top of the PiPE block in my_pipe1/01_pipe.pdb is a list of js.init statements that are commented out. Take a careful look at these and enable any that you wish to use in your PiPE. A good way to understand them is to un-comment one at a time, then start Chapter 1 and note the effect.

  30. Add additional molecular views to my_pipe1/01_pipe.pdb by repeating the above steps: load a PDB file into a new PE session, achieve the desired view with minimal "side trips", save the script, paste it into my_pipe1/01_pipe.pdb as a "named script", and call the script name in a molecular-view button. Test the PiPE chapter after each change.

  31. Add Popup Details to Your Molecular-View Buttons. Replace the text in the first example (details_view02) in the template file 01_pipe.htm with details you wish to have popup. Rename these details to match the name of the script they go with (but all names of details must begin "details_"). Here are the Details on !details. Here are instructions for how to connect the details to the put_button() line. You can have details popup for as many or as few buttons as you wish. You can have the same details popup for different buttons if appropriate.

  32. Customize the Presentation Contents page, file my_pipe1/index.htm. Use your HTML editor to replace "PiPE Template" with the title of your presentation. Replace "Chapter 1" with a description of what the first chapter shows, etc. See the example contents page for Antibody 2G12. Add an introductory paragraph if desired, references, acknowledgements, etc. Inserting small snapshot graphics can dress up the contents page.

  33. Create additional chapters if desired. Copy the spare "Copy of 01_pipe.pdb" (that you made before it was customized) and name the copy 02_pipe.pdb. Proceed as above, testing with the Chapter 2 link. You can make as many chapters as you wish, adding additional chapter links to the contents page (file my_pipe1/index.htm) as needed.

  34. IMPORTANT: Enable your PiPEs to work in Internet Explorer: Your PiPEs will work fine in all PE-compatible browsers except Internet Explorer, for which you need to copy the headers of your PiPE PDB files into properly-formatted files named *_h.htm (e.g. for my_pipe1/01_pipe.pdb, add my_pipe1/01_pipe_h.htm). Here are the instructions.

    Be sure to test your PiPEs in Internet Explorer!

  35. Publish your PiPEs. In order to make your PiPEs viewable from a web server, you will need to copy both the "Protein Explorer N.NN" file tree, and the "my_molecules" file tree, side by side, onto the server (just as they are side by side on your hard disk). (Cross-domain security barriers in some browsers preclude having my_pipe1 operate in PE from a different server domain.) See also troubleshooting a moved PiPE.

    You may need help from an expert to configure the file permissions etc. so they will work in a client browser.

    If not already done, your server administrator (who should know what this means) will need to configure these MIME types:

  36. Publicize your PiPEs by submitting an entry at the World Index of Molecular Visualization Resources, Or if that is premature, at least send an email to me ( to let me know you've made PiPEs, their topics, and how you plan to use them!

Feedback to Eric Martz.