Prerequisite Knowledge
- 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.
- 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."
Easy downloadability is one of
the key goals of the PiPEs mechanism. With the exception of my own legacy
(pre-PiPE)
molecular structure tutorials (at MolviZ.Org), very few of the authors of
hundreds
of other Chime-based interactive molecular structure tutorials
have made them downloadable. I believe this is mostly because of the
extra effort involved in making legacy-style tutorials downloadable, and
in supporting the downloaders, although some authors may prefer not to
make their tutorials downloadable.
- 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.
- Be clear about what a PiPE is, and is not, by looking at a good
example.
- To get an idea what is involved in constructing a PiPE, first please take a look at the
Overview.
- 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.
- 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.
- If you are using a copy of PE downloaded some weeks or months ago,
check this document on-line at proteinexplorer.org
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.
- Take a preliminary look at the
PiPE Template,
trying all links.
- 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.
- Windows
- NotePad (provided in all Windows systems) is excellent because it can only save plain text. Find it
on the Start menu under Programs, Accessories. Right click and Send To Desktop
to create a shortcut onto which you can drop documents to open them.
Unfortunately, NotePad cannot handle large files, such as some PDB files you may need to edit.
- WordPad
(provided in all Windows systems)
is good and can handle fairly large files. You must be sure always to save
the PiPE PDB files as type "Text Document" (or "Text Document - MS-DOS Format", equally good).
Every time you save a file, WordPad may whine annoyingly
about losing your formatting. Make sure WordPad doesn't tack ".txt"
onto the end of the name of your saved file (see below under Word for
how to control this).
- MS Word (and probably the free workalike program Open Office) can handle very large
PDB files. Here you must save as "Plain Text (*.txt)". You may
also have to persuade Word not to add ".txt" onto the names of files
you save (which will prevent them from working in some circumstances).
This is done by quoting the filename in the save dialog, e.g. "01_pipe.pdb".
In order for you to be able to tell whether you've persuaded Word
to save the filename without tacking on ".txt", you will need to
unhide file extensions. In Windows Explorer, open the Tools menu,
select Folder Options, View tab, and UNCHECK "Hide file extensions for
known file types".
- Apple Macintosh OS 8-9 / OS X
- BBEdit is recommended, available from
barebones.com. A 30-day free
demo is downloadable.
- 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.
- Taking a look at the Molecular
Structure Presentation Design Guidelines now is likely to
save time later, and result in a better product.
-
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
- 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!
- 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
pdb.org.
- 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.
- 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.
PDB filenames longer than 31 characters will
not work properly on Macintosh computers. See
Broken PiPEs.
- 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!
MAKE ONLY ONE CHANGE AT A TIME,
then
TEST THE PiPE BEFORE MAKING THE NEXT CHANGE!
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.
- 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.
- 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.
PDB filenames longer than 31 characters will
not work properly on Macintosh computers. See
Broken PiPEs.
-
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).
Make backup copies of your work early and often!
There is an important reason why the file mypipes.htm and the folder
my_pipe1 do not exist in the downloaded PE, and must be created by you.
When you upgrade to a new version of PE by downloading and installing it,
the included files in my_molecules
will be overwritten with the downloaded versions. Thus, your own work could
be inadvertantly destroyed. Because your own work is in files and folders
that do not exist in downloaded PE, it will survive upgrading.
Never put any of your own work in the "Protein Explorer N.NN" folder (where
N.NN is the version number) because that entire folder may be deleted
once you have downloaded a newer version.
Make backup copies of your work early and often!
- 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".
- 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).
- 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
- 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.
- 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.)
- 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.
- 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.
As explained in the PiPE Reference Manual,
you can put as many scripts in a chapter as you wish. Usually it works
best to name each script, and call it by name in the appropriate
molecular-view button. view01 is a special
name reserved for one script in each chapter. This script will display
automatically as the initial view for the Chapter. Typically, it is
called in button #1.
Finishing your PiPE: Options, More Views, More Chapters,
Contents Page, Web Server
- 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.
- 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.
You may use different PDB files for different buttons as needed. The
PDB file we pasted into 01_pipe.pdb is called the primary PDB file
for Chapter 1. Other PDB files used in Chapter 1 are called secondary
PDB files (for Chapter 1 -- one could be the primary PDB file for
Chapter 2). If secondary PDB files have a PiPE block (which they would if
they serve as primary PDB files for other Chapters), it will be ignored in
Chapter 1. All scripts, buttons, and text for the control panel of Chapter
1 must be in the PiPE block of its primary PDB file.
Put a copy of each secondary PDB file in the folder my_pipe1.
Here are instructions
for how to modify the "!js put_button()" line
to specify that the command script called in that button be applied
to a secondary PDB file.
- 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.
- 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.
- 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.
-
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!
- 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:
- .pdb chemical/x-pdb
- .spt application/x-spt
- .js application/x-javascript
- Publicize your PiPEs by submitting an entry
at the World Index of Molecular Visualization Resources,
molvisindex.org.
Or if that is premature, at least send an email to
me (emartz@microbio.umass.edu)
to let me know you've made PiPEs, their topics, and how you plan to use
them!