-
What this document is about.
Crucial Preliminaries:
-
Installing RasMol so it can find your scripts and PDB files.
-
Troubleshooting your installation & PDB-opening.
-
Give your PDB and script files portable filenames.
-
Saving portable scripts!
The Main Event:
-
Save scripts of desired views from RasMol,
then play them back!
-
Troubleshooting script playback.
-
What RasMol forgets to save! (And how to fix it.)
Optional Enhancements for RasMol:
-
Manually type script calls into a master script, with a text editor.
-
Add echoed captions to the master script.
-
Gather several master scripts into a super-master script.
Delivering your RasMol Scripts through the Web via Chime
-
Install your scripts in a Chime web page with buttons, color keys,
and descriptive text.
1. What this document is about.
For an introduction to RasMol, see the Quick Start at
http://www.umass.edu/microbio/rasmol/rasquick.htm.
This document assumes that you already know how to obtain
PDB files of the desired molecules
(http://www.umass.edu/microbio/rasmol/whereget.htm
),
and to use RasMol
to get the views you
need of these molecules for teaching purposes. (By a "view" we mean
a particular representation, color scheme, orientation, and magnification
of a molecule.)
This document explains how to save the views you wish to show your class,
and how to play them back smoothly in the correct order. It also explains
how to deliver these views through the Internet/Web via Chime.
2.
Installing RasMol so it can find your scripts and PDB files.
It may be best to create a new folder to receive your saved scripts.
Put the needed PDB files (or copies of them) in this folder.
Now you must install
RasMol so that this folder is RasMol's working/local directory.
Otherwise it will not be able to find either the scripts or the PDB files.
- On the Macintosh, the RasMac application (not an alias to
it!) should also be dragged into this folder before running it.
(Other methods may work under just the right circumstances, but
sooner or later will fail for a variety of technical reasons. Therefore
we strongly recommend the above method.)
- For Windows 3.1/NT 3, make a separate RasWin icon to run your
scripts. In Program Manager, select the RasWin icon, then use the
File menu to Copy the icon (putting it wherever you wish). Now, with the
new icon selected, use
File, Properties (i) to change the name of this icon to "RasWin Scripts",
and (ii) to
change the Working Directory to the folder
containing your scripts. Always run RasWin from this icon when you plan
to save or run scripts.
- For Windows 95/NT 4, copy the RasWin application (not a
shortcut!) into your script folder. To force a copy (rather than
the creation of a shortcut), hold down the Ctrl key before you drag
and drop the RasWin icon into the scripts folder. Alternatively, if
you prefer to make a shortcut to RasWin in your scripts folder, you
must change the "Start-in" folder for this shortcut. Right-click
on the shortcut icon and select Properties, then Shortcut, then change
the Start-In folder to be that containing your scripts.
3.
Troubleshooting your installation & PDB-opening.
To test your installation, run RasMol and use its File, Open menu to open
one of the PDB files in your scripts folder.
- If the PDB file is not listed on the open menu, here are the
possible reasons and solutions:
- The PDB file is not in the correct folder. Display the folder
you have reserved for your scripts and double-check whether the PDB
file of interest is present. Solution: copy or move the PDB file to
the correct folder.
- You are running a RasMol which was not installed as
instructed above, and hence RasMol is looking in the wrong folder. It is
easy to get confused when you have more than one RasMol icon in different
folders. Solution: quit ALL running RasMol's, and restart RasMol
from the correct icon installed as above.
- Windows (any version): your PDB file's name does not end
in ".pdb". Solution: rename your PDB file to end in ".pdb".
See also the section below on portability.
- Windows 95/NT 4 only: Your PDB file appears to have a name
ending in ".pdb" but it really doesn't. Windows 95 loves to fool
you. Open "My Computer", or run Windows Explorer (from the Start
menu, Programs section). Pull down the View menu and select
Options. Make sure that "Hide MS-DOS file extensions" is NOT
checked, then click OK. Now examine the folder
containing the PDB file. Depending on how the file was downloaded
or handled, it may have inadvertantly received a name such as
"1d66.pdb.txt" for example. If "hide extensions" was checked, you
can't see the real name. Solution: Uncheck "hide extensions" and
then rename the file.
- Macintosh only: the PDB file does not have a signature type of
"TEXT". This occurs, for example, when you use Netscape 3.01, and
force downloading of a linked PDB file by holding down the Option
key when you click on the link.
Solution 1. Open the PDB file in MS Word, using the "all files"
option on Word's open menu. Save the file as plain text.
This will give it a new signature with a type of "TEXT".
Alternative Solution 2.
Change the signature directly.
Download a copy of
FileBuddy from any shareware web site. Drop the PDB file on
FileBuddy. If the type and creator (signature) are shown as "????"
and "????", or the type is not "TEXT", RasMac will not list it on the
open menu. Solution: In FileBuddy, change the type to TEXT
and the creator to RSML (both all upper case), and click on
save. For more information on Mac signatures, see
http://www.umass.edu/microbio/rasmol/distrib/macsigs.htm
- The PDB filename appears on RasMol's Open menu, but when clicked,
no molecule appears. Here are the possible reasons and solutions:
- The filename is indigestible. Filenames containing odd characters
or (on Windows95/NT4) imbedded spaces may display on the Open menu but
fail to load. (See notes.) Solution: rename the file following
the portable naming conventions described below.
- The PDB file is empty. One possibility is that you attempted to
save the file from Netscape before it finished downloading and it
may have no content at all. Check the size of the file. On
Macintosh, display your script folder with View, Name. If
the PDB file is listed as "Zero K", it contains no data. On
Windows 3.1/NT 3, use File Manager to check the size of the
file.
On Windows 95/NT 4, right click on the PDB file icon and
select properties. The size is displayed on the General tab; if 0
bytes, it is empty. Solution: Download this PDB file again,
making sure Netscape says Document Done before you use
File, Save As.
- The PDB file is not empty, but nevertheless
contains no atomic coordinate
data (ATOM records). Use a text editor or MS Word to view the
contents of the PDB file. Make sure that the file contains lines
beginning ATOM, followed by Cartesian coordinate values, such as
this line:
ATOM 1054 CA PRO A 42 26.232 52.193 48.226 1.00 52.62
If no ATOM records are visible, either the file is gzipped, or it is
simply corrupted.
If you got this PDB file as part of a downloaded file set for
display in Chime, the PDB file may be gzipped. Chime (but not
RasMol) can automatically g-unzip such files. Solution 1:
Run the Chime package either from your local hard disk or from the
web. When the molecule of interest is displayed in Chime, use
Chime's File, Save As menu. This will save the plain-text (not
gzipped) PDB file. Solution 2: Download gzip from any shareware
web site, and "gzip -d" (decompress) to g-unzip the gzipped PDB file.
You may first have to rename the file to end in ".gz" so gzip will
recognize it. (Gzipped PDB files still have names ending ".pdb" so
the file server can serve the file as the correct MIME type for Chime
to recognize. Thus, you can't tell a gzipped PDB file from its name.)
If the file did not come as part of a Chime presentation, it must be
corrupted. In this case, the solution is to download the
file again, or by some other means acquire the authentic PDB file.
4.
Give your PDB and script files portable filenames.
One of the big advantages of a Chime presentation is that, with a
smidgeon of foresight, it will play on any platform (Windows 3.1,
Windows 95, Macintosh, unix). We strongly recommend that you give
your PDB and script files names which will be acceptable on all
platforms. If you don't bother, sooner or later you are likely to
regret it. (It is much more work to fix this after the fact: after
renaming your PDB files, you'll need to change the load commands in
each script file.) The rules are that the name should consist of not
more than 8 characters including only lower case letters, digits,
and the underscore character. Only one period is allowed, just
before the "extension": PDB files should end in ".pdb", and script
files in ".spt". These "file extensions" are highly desirable in
all situations and are mandatory in some situations, such as when
the presentation is on a web server (and see notes for other situations). One platform, unix,
treats filenames as case sensitive; this is why we strongly recommend
all lower case for filenames. When you put your presentation on the
web, some people WILL view it in unix, and they'll complain if it
doesn't run (trust me).
Here are some
examples:
Filename |
Comments |
1d66.pdb |
OK |
gal4_dna.pdb |
OK |
gal4_dna |
BAD: ".pdb" missing |
Gal4 DNA.pdb |
BAD: upper case letters and imbedded space |
gal4.dna.pdb |
BAD: only one period is allowed |
gal4_dna_complex.pdb |
BAD: more than 8 characters before the period |
a010.spt |
OK |
a010 |
BAD: ".spt" missing |
View One.spt |
BAD: upper case letters, embedded space |
5.
Saving portable scripts!
There is a crucial trick for making RasMol-saved scripts portable.
Instead of using RasMol's File menu to Open your PDB file, type the
command load "filename.pdb". The result of this trick is that
scripts you save from RasMol will be portable, provided that you always
have the scripts themselves, the requisite PDB files, and RasMol
(or its working/start-in folder) all in the same folder.
If you open the PDB file from RasMol's menu, it
remembers the full absolute pathname of the file, and saves it into
the script. When you put the script in a different folder or
system, it can't find the PDB file. The 'load' command, given
without a PDB filename path prefix, causes RasMol to save the PDB
file 'bare', with no path prefix.
If you forget to 'load' your PDB file, the symptom will be that your
script will run in the original RasMol folder, but will not run when
the script + PDB files are in a different folder or system, and will not
run in Chime. You can fix this easily by using a text editor to delete the
absolute pathname prefix from the load command in the 7th line of each
RasMol-saved script. For example, change
load pdb "C:\M1\RASDAT\SCRIPTS\DNA-RSS\1D66.PDB"
to
load pdb "1d66.pdb"
Note that we also changed the filename to lower case! You may need
to do this even if you don't need to delete a pathname prefix.
Failure to change the filename to lower case will cause
your presentation to fail on case-sensitive operating systems such as unix.
6.
Save scripts of desired views from RasMol,
then play them back.
Save each view into a script file by typing the RasMol command
save script filename, where filename is a
filename of your choice. We strongly recommend organizing your presentation
into sections called Page A, Page B, etc. If you name your first script
for Page A a010.spt, your second script a020.spt, and so
forth, then these scripts will play in the Chime template immediately,
since it expects this script naming convention.
Typing the command script filename into RasMol plays back the
script (for example script a010.spt).
7.
Troubleshooting script playback.
Sometimes when you type script filename into RasMol's white
command line window, the view you saved fails to appear. Here are
the possible reasons and the solutions.
Note: This document troubleshoots RasMol-saved scripts only. Troubleshooting
of manually typed/edited scripts is beyond the scope of this document.
- Error message Cannot open script file 'filename'. The
script filename you typed is not present in RasMol's working
folder. Examine the contents of the folder. Windows 3.1/NT 3: use
File Manager. Windows 95/NT 4: use Explorer (Start, Programs,
Windows Explorer); make sure you are not hiding file extensions (see
the 4th item under Troubleshooting PDB-opening above).
- If the script file you saved is not present in this folder, then
this folder is not the working folder of the copy of RasMol from
which you saved the script. Solution: Quit all running
copies of RasMol, and start the RasMol which was installed for this
folder. (See Installing RasMol so it can find your scripts
above.) Then save the script again. You could also use Finder/Find
to find the script which was saved elsewhere, and then move it to
the desired folder.
- If the script file is present in this folder, make sure you typed its
name correctly in your script filename command. If you did not
follow portable file naming conventions (see above), be especially careful
about embedded spaces (or rename the script file to a portable name!).
- A long series of Unrecognised command! errors scrolls by.
This means that when you saved your script, you forgot to specify that
you were saving a script. That is, you typed save filename instead
of save script filename. Without the word script, RasMol
defaults to saving a PDB file. Solution: save the script correctly.
- Error: File 'filename.pdb' not found!
There are two possible reasons:
- The filename in the error message includes an absolute path prefix.
This means that your script was not saved portably and may have been
moved. That is, you forgot to use the load command to load
the PDB file before you saved your script (you used RasMol's File,
Open menu instead). Solution: use a text editor to remove
the absolute pathname prefix from your script's load command,
as explained above.
- Another possibility is simply that the PDB file
this script needs to load is not present in the working folder.
This would most likely happen if you moved the script from another
location, and forgot also to copy the necessary PDB file.
Solution: Copy the necessary PDB file into the working folder
which contains the script file. (If unsure which PDB file, examine
the load command in your script with a text editor or word
processor.
Macintosh users see note at end of document*.
It is the 6th nonblank line in the script.)
8.
What RasMol forgets to save! (And how to fix it.)
RasMol (version 2.6 beta 2a)
fails to save certain information into the script: the selected subset
of atoms, the center of rotation, background colors other than black,
and any new terms you have defined with
RasMol's "define" command.
This explains some results which might surprise you. Suppose you
have only the sulfur atoms selected when you save the script. After
playing back the script, you will get the same view as when you
saved the script. However, commands which operate on the selected
subset will operate on all atoms (since after playing back a script,
all atoms are selected). Just before you saved the script, the
command 'color yellow' would color only the selected sulfur atoms.
After playing back the script, the same command would color all atoms yellow.
You can fix these problems if you wish by manually editing the script
you have saved from RasMol. Instructions are in the
Appendix.
9.
[Optional] Create a Master Script.
If you are planning to present your scripts with Chime, you may
skip this step and the next two [Optional] steps.
Suppose you have saved a dozen scripts from RasMol, and now you want
to be able to show them quickly to a class, without typing
script filename for each one (and without remembering
all the filenames!).
You'll need a text editor. Word or Simple-Text are recommended on the
Macintosh; Notepad or Wordpad is recommended on Windows95. The goal is to save
your typed commands into a plain text file, not a formatted word
processor file. (If you use Wordpad or Word, be sure you save files as plain
text!)
Create a master script file (let's call it master-a.spt)
containing a list of script commands, each followed by a pause
command. For example, depending on the names you gave your scripts,
your file might contain:
script "a010.spt"
pause
script "a020.spt"
pause
script "a030.spt"
pause
The command script "a010.spt" causes RasMol to show the first
image. The pause stops script execution until you press any key.
While the script is paused,
you can rotate, zoom, and translate with the
mouse. When any key is pressed, the first pause is released, and the
second image comes up, and so forth.
10.
[Optional] Add echoed captions to the master script.
When you run the script master-a.spt, nothing appears in
RasMol's command line window until the script is finished. However,
the command line window need not be wasted: you can use it to
display captions. All you have to do is use RasMol's echo
command to write lines of text to the command line window.
(Unfortunately, you have no control over the font size or color.
Chime has the advantage in this regard!)
To clear old commands or captions out of the command line window
before displaying a new caption, use a series of echo commands with
no text.
Here is what you might put after the first script in master-a.spt:
script "a010.spt"
echo
echo
echo
echo
echo
echo
echo "Here is the view from my first script"
pause
Actually, you should put something more useful in the caption --
something which will remind you what to say in lecture!
If you plan project your saved images to a class, you will do better
to install your scripts into the Chime template,
(see below)
and play them back
in Netscape with Chime. This gives better control (you can back up, use
large fonts, and color keys), and allows you
to deliver your scripts to your students via the web. If you are going
to use Chime, don't bother to add echoed captions to your master scripts.
However, it may be worth adding captions to your master script if (1) you
are going to have students play your scripts in a computer lab, and (2) they
know how to use RasMol fairly well. That way,
the scripts can be pre-installed, and the students have the full power
of RasMol at their disposal. They can stop
after any script (if at a pause, with Ctrl-D), and apply RasMol commands
to the view. The Chime template provided at
http://www.umass.edu/microbio/chime/prsswc/template.htm has no
command-line interface, and thus limits what students can do.
If you are ambitious, a template with a command line can be downloaded
from
http://www.umass.edu/microbio/chime/chimehow/fs_cmdln.htm
11.
[Optional] Gather several master scripts into a super-master script.
If you have saved a lot of scripts, they can be grouped into topics
A, B, C, .... Scripts for topic A will be displayed by
master-a.spt, for topic B in master-b.spt, and so
forth.
You can avoid having to type each master script into RasMol's command
line window during your presentation. Use your text editor to create
a super-master script named supermas.spt.
Typing script supermas.spt once into RasMol runs all of your
master scripts, showing your many views in proper order. For example
(the comments preceded by # can be tailored to your topics):
script "master-a.spt" #Chain A (protein)
script "master-b.spt" #DNA
script "master-c.spt" #Chain A plus DNA
script "master-d.spt" #Zinc (Cadmium) ions and Cysteine sulfurs
script "master-e.spt" #Contact atoms
You can kill this many-script sequence at any point by holding down
the Ctrl (control) key while pressing D (Ctrl-D).
The super-master script (or any individual master script) can be
adapted to a given audience easily. If you wish to omit some images,
just comment them out (precede the script command with #). If you
wish to show views in a different order, simply rearrange the sequence
in the master script.
RasMol provides no mechanism to back up during a master-scripted sequence.
Again, Chime solves this problem.
12. [Optional]
Install your scripts in a Chime web page with buttons, color keys,
and descriptive text.
Instructions are in a separate document,
How to Install Your Scripts into the Chime Template,
available at
http://www.umass.edu/microbio/chime/prsswc/2fc-how.htm
Technical Notes
It is not necessary to read these notes in order successfully to
save and play back RasMol scripts. These notes are provided for
those interested in technical details.
- RasMac's PDB filename/signature requirements for Opening a
PDB file from the File menu. This assumes that the PDB file's
contents are correct. If the filename contains characters other than
letters, digits, spaces, and the underscore character, it may not
appear on the menu or may not load. Characters known to cause such
problems include /<>%[]?. The filename need not end in
".pdb". The signature type must be "TEXT" in order to appear on
RasMac's File, Open menu.
- RasMac's PDB filename/signature requirements for loading a
PDB file from a script. It is strongly recommended that the
filename be quoted (either single quotes or double quotes will do).
While sometimes quotes can be dispensed with, sometimes they cannot
(e.g. if a comment follows the filename on the same line), so it is
best to play safe. A subtle mismatch between the filename in the
script load command and the actual filename, such as an extra space
character, will cause the PDB file to fail to be found. The load
command seems to have no requirements for the file signature; for
example, a PDB file with signature type "????" and creator "????"
can be loaded. However, the naming requirements specified
under Note 1 should be adhered to.
- RasWin's PDB filename requirements for opening a PDB file
from the menu. The filename must end in ".pdb" in order
to appear on the open-menu spontaneously. However, in Win95, you can
type "*.*" in the "File name" slot (with no file selected), click on
"Open", and all files will be listed. You can then open a file whose
name does not end in ".pdb".
In 32-bit RasWin under Win95/NT4, the above strategy can display and
successfully open a long filename. However, if the filename
contains one or more imbedded spaces, RasWin32 will display it on
the open menu but not load it. (In Explorer, at least, Win95
removes leading/trailing spaces from a filename.) Failure to load
produces no error message, but can be verified by using RasWin's
File, Information menu: "Number of atoms ... 0" means nothing was loaded.
Unlike with the Mac, any Windows-legal filename characters seem OK.
For example, RasWin32 can open a file named "1..,,`~%!@#$^&()[]{}p.pdb".
Nevertheless, we strongly recommend following the portable file naming
conventions outlined above.
Appendix. [Optional] Fixing
what RasMol forgets to save in your scripts.
These fixes require that you use a text editor to modify the script
file saved by RasMol. Windows: use Notepad or Wordpad. Macintosh:
use Word (not SimpleText). Be sure to save
files from Wordpad or Word as plain (ASCII MS-DOS) text.
Selected subset of atoms.
At the very end of the script file, add a select command(s) which will
select the desired atoms.
Center of rotation.
At the end of the script file, add a select command(s) to select the
atoms which should be the center of rotation, then add the command
'center selected'. If these atoms are NOT those which should
end up selected, this section must precede a final selection command(s)
at the very end of the script file.
Defined terms.
Add commands to select groups of atoms for which you wish to define terms,
following each set with the command 'define term selected', where
term is the term you wish to define. If the resulting selected
atoms are NOT those which should end up selected, this section must
precede a final selection command(s) at the very end of the script file.
Nonblack background color.
If your view uses a background color other than black, the script
RasMol saves will fail to change the background color due to a
sequence bug in RasMol's script writing process.
RasMol erroneously specifies the background color before loading the
PDB file (a bug). This order needs to be reversed. Here is an excerpt
from the beginning of a RasMol-saved script with a white background:
zap
background [255,255,255]
load pdb "1d66.pdb"
This will work if you simply change the order of these lines to:
zap
load pdb "1d66.pdb"
background [255,255,255]
* Macintosh users: Use Word to edit RasMol-saved scripts or PDB
files, being sure to save the edited scripts as plain text. Open
the script after you select All files from the Open menu
(since these are not Word documents). You can create short scripts
(such as master scripts) with SimpleText. However you cannot edit
scripts saved from RasMol, or PDB files with SimpleText (because
they don't have a SimpleText signature/icon, and they may be too
long).