MolScript v2.1: How to use MolScriptHow to use MolScript
Running MolScript
Command-line options
Environment variables
A minimal input file
Some useful tips
How do I...?
Common problems
Running MolScript
The MolScript executable (molscript) should be directly available as a command,
that is, it should be located in your path. To test this, try the following
command, which will just output all command-line options available:
% molscript -h
If the program does not seem available, ask your system administrator or whoever
installed it.
To get a first input file, use the MolAuto program. This takes a coordinate file
as input, and produces a first-approximation input file for MolScript:
% molauto pdb1crn.ent > input.file
By default, MolScript reads the input file from the stdin (standard input) and
writes the result to stdout (standard output), while execution messages and
error messages are output to stdout (standard output). For example, to produce a
PostScript file, give the command:
% molscript -ps < input.file > output.ps
The interactive OpenGL mode produces no output, so there is no need specify an
output file:
% molscript -gl < input.file
The best way to use the interactive OpenGL mode is to use an explicitly named
input file (using the -in command-line option). This allows re-reading the input
file after the user has modified it with a text editor, which speeds up
preparation of input files. See the documentation on the mouse button functions.
% molscript -gl -in input.file
Using UNIX pipes, one can get quick visualizations of a coordinate file using
MolAuto and the interactive OpenGL mode:
% molauto protein.pdb | molscript -gl
Similarly, a VRML 2.0 file can be created quickly with MolAuto:
% molauto protein.pdb | molscript -vrml
Command-line options
Only a single option controlling the output mode may be specified. An output or
input file different from the default may be defined only once in the command
line. The other options may be specified in any combination. If conflicting
options are used, then the last one on the command line determines the result.
Note that in previous versions of MolScript (v1.4 and older) it was possible to
specify the output format by giving a keyword in the input file. This is no
longer possible.
command-line option action
-ps
-postscript Chooses the PostScript output mode. This is the default mode,
so these options are actually rather useless.
-r [alias]
-raster3d [alias] Choose the Raster3D output mode. The optional aliasing
parameter controls the aliasing scheme: 1 = no antialiasing, 2 = compute
2x2 pixels for each pixel output, 3 = compute 3x3 pixels for 2x2 pixels
output. The default value is 3. The file produced is suitable as input for
the render program in the Raster3D package.
-vrmlChoose the VRML 2.0 output mode.
-gl
-opengl Choose the interactive OpenGL mode. This may or may not be
available in your executable, depending on whether your installation
includes the OpenGL implementation or not.
-eps [scale]Choose the Encapsulated PostScript (EPS) image file output
mode. The optional scaling parameter value affects the conversion of the
OpenGL rendering image size in pixels to to the PostScript default units.
The default value is 1.0. Any positive, non-zero value is valid. This mode
is available only if the OpenGL mode is.
-epsbw [scale]The same as the -eps option, except that a black-and-white
image is produced, by interpreting the pixel colour values in the OpenGL
rendering image as luminance values. This mode is available only if the
OpenGL mode is.
-sgi
-rgb Choose the SGI (aka RGB) image file output mode. This mode is
available only if the OpenGL mode is.
-jpeg [quality]Choose the JPEG image file output mode. The optional
quality parameter can be any integer in the range 1-100 inclusive, and
controls the degree of compression used for the image: lower values use
more compression, giving lower image quality. The default value is 90.
This mode is available only if the OpenGL mode is.
-png [compress]Choose the PNG image file output mode. The optional
compress parameter can be one of the literal values default, speed, size
or none and determines the algorithm used by the PNG library routines when
creating the image file. The default value is default. This mode is
available only if the OpenGL mode is.
-accum numberUse the accumulation buffer for OpenGL rendering, i.e. for
the interactive OpenGL mode and all image file output modes. The image is
rendered multiple times (with a slight shift each time), summed and
averaged, thus producing an antialiased image. The quality improves with
the number, but so does the execution time. The parameter value can be any
positive, non-zero integer, but is actually always set to the immediately
higher value in this list: 2, 3, 4, 8, 15, 24 or 66 (maximum).
-prettyThe output file is formatted (indented) to increase the
readability. This is useful when the file is to be modified manually.
Currently this affects only the VRML 2.0 output mode.
-size width heightSet the size of the image for the Raster3D, OpenGL, EPS,
SGI, JPEG and PNG modes. The values are the width and height of the image,
in pixels. The default value is 500 by 500 pixels. The maximum value
allowed is 4096 by 4096 pixels.
-s
-silent Do not produce any run-time diagnostic messages. This may be
useful when no output except the graphics is wanted, and the input file
needs no debugging.
-out filenameThe output from the program is written to a file with the
given name, instead of to stdout (standard output).
-in filenameThe input file (script) is read from the file with the given
name, instead of from stdin (standard input). This is particularly useful
with the interactive OpenGL mode.
-log filenameThe run-time diagnostics are written to a file with the given
name, instead of to stderr (standard error output).
-tmp filenameUse a temporary scratch file with the given name. The
execution process must be allowed to create, write to, read from, and
delete the file. The default is the file used by the ANSI C library
standard tmpfile routine. Currently, this is relevant only for the
Raster3D output mode.
-hOutput a listing of the available command-line options to stderr
(standard error output). No other output is produced.
Environment variables
The MolScript program can use one environment variable: MOL3D_PDB_DIR. If this
is set to the name of the directory where the local copy of the PDB database
distribution is located, it allows one to use just the PDB code in place of the
complete file name in the read command. See this command for more information.
A minimal input file
Here is a minimal input file, which will show the trace of the amino-acid chain
for the molecule in the coordinate set, after centering all atoms.
! --- This is a minimal MolScript input file; this line is a comment.
plot
read mol "protein.pdb"; ! Read the coordinate file.
transform atom * ! Xform all atoms so that the centre-
by centre position atom *; ! of-gravity is placed at the origin.
trace amino-acids; ! Output a CA trace of the chain.
end_plot
! --- Here the minimal input file ends.
Some useful tips
The MolAuto program is almost always the best starting point for making a good
image of a molecule. The input file produced by the MolAuto program will contain
commands to render both the secondary structure and the ligands. However, there
will be no transformation to get a good view.
To prepare a good image of a molecule, the main problem is to find a good view.
It is usually not a good idea to work on details such as label positions or
colours unless at least an approximate view has been found. With the interactive
OpenGL mode, it is fairly easy to find a good view, which is output from the
program, and then incorporated into the input file by the user.
If you do not have the OpenGL implementation available, you must adopt an
iterative method instead: Use a PostScript display program such as xpsview or
ghostview to view the output from the MolScript program. Then edit the input
file with an ordinary text file editor, changing the transformation by adding
rotations and/or translations. Note that any number of rotations or translations
may be used in the transform command. Re-run MolScript, and view the results.
Continue until a good view has been found.
Jane Richardson has listed some general points on the design of schematic images
of proteins (Richardson 1985). These guidelines are still perfectly valid,
although they were formulated for hand-drawn images. Look at her drawings for
inspiration and guidance (Richardson 1981, 1985).
An important point to make is that 90 degree views of a structure, if carefully
selected, can be very instructive. In fact, such views can often bring home the
message better than stereo plots. With MolScript, 90 degree views are
ridiculously easy to prepare. Stereo plots, however, are trickier to make.
When displaying superpositions of structures (for instance, sets of structures
derived from NMR data), then the store-matrix and recall-matrix commands must be
used, rather than the ordinary ways of getting a good view. The reason is that
if the position command is used, this will give a slightly different
transformation for different coordinate sets, thus destroying the least-squares
fit that (almost certainly) has been done previously using some other program.
In the display of superimposed NMR structures, this will give plots where it
looks as if the structures superimpose better at the center of the plot than
they actually do. By using the command store-matrix after the first coordinate
set has been transformed, and then recall-matrix for the other coordinate sets,
you ensure that the original least-squares fit is kept intact.
How do I...?
Disulfide bonds
Per-residue colours
Rainbow residue colours
Select residues close to a residue
Stereo plots
Disulfide bonds
Why are not disulfide bonds output by default?
The reason is that the sulfur atoms in disulfide bonds typically have a covalent
bond distance of about 2.0-2.1 Ångström, while the default value for the
bonddistance parameter is only 1.9 Ångström. So in order to get a bond between
two sulfur atoms, this parameter has to be increased to, say, 2.5. Note that
this may cause spurious bonds in other parts of your structure, so reset the
parameter back to its lower value once the disulfide bonds have been created.
bonds in amino-acids;
set bonddistance 2.5;
bonds atom SG;
set bonddistance 1.9;
Why is the default value of the bonddistance parameter so low? It is a
compromise value intended to avoid problems of spurious bonds in e.g.the
five-membered rings of heme groups, while giving reasonable results for other
moieties.
Per-residue colours
Per-residue colours were introduced in MolScript v2.0. By switching on the
colourparts parameter, all schematic residue-based graphics objects (for example
helix and strand) will be coloured according to the current residue colours.
These are all white by default. They can be changed with the residuecolour
parameter.
Rainbow residue colours
You want to colour the schematic residue graphics objects from blue at the
N-terminus along the rainbow colours to red at the C-terminus.
Solution 1:
set residuecolour amino-acids rainbow, colourparts on;
helix from 1 to 10; ! or whatever
Solution 2:
Use the MolAuto program to create the commands for the schematic residue
graphics objects. By default, these will be coloured in a rainbow fashion, but
on an object-to-object basis, not residue-by-residue.
Select residues close to a residue
If you want to display all residues close to another residue, then use the close
selection expression. However, since this expression takes an atom selection as
argument, and produces an atom selection, the result must be converted to a
residue selection using the contains expression.
As an example, to draw bonds for all atoms in all residues having an atom within
5.0 Ångström of a residue of type RTL, use the following:
bonds in contains close in type RTL 5.0;
Stereo plots
There is no specific command to make MolScript create stereo plots. Instead, a
stereo plot can be made by creating two similar plots in two different output
images, the only difference being a slight rotation of all coordinates (about
4-6 degrees) in one of them.
Alternatively, in PostScript output it is possible to make two plots on the same
paper (position them with the area command) and draw the same objects in both,
adding a small rotation to one of them.
Common problems
"Error: parse error"
You may have forgotten the semi-colon ';' that must be present to finish the
previous command, or you may have used an invalid or misspelled command, or you
are trying to use a keyword or reserved word as an identifier without using
quotation marks. Check the input file at or before the line and item indicated
by the error message.
Weird helices or strands
If you use a too generous definition of helices and strand, then most likely
there will be strange effects at the terminii. To reduce or remove the problem,
just shorten the secondary structure elements by one or two residues. The
secondary structure determined by the -ss_hb command-line option in the MolAuto
program is usually good, while the command-line option -ss_ca may occasionally
be too generous.
The algorithm for helix graphical object generation assumes reasonably good
alpha-helical geometry, but can usually handle deviations like proline bends
gracefully. Of course, it cannot take care of all kinds of irregularities.
Sometimes, a beta-strand may flip over on its back. This is most often due to
prolines or cross-over in the strand, and is difficult to do anything about.
Sometimes it may be best to split the strand up to handle the problem.
Difficulty to position label strings
Since parameters such as labelcentre and labeloffset are part of the graphics
state, and hence persistent, it is a common mistake to set an offset for a
particular label, but forgetting that all labels after that in the input file
will also be affected. Just change these parameters appropriately.
Coils/turns not connected to helices/strands
This is most likely due to not giving the proper residue selection for the
relevant commands. If residues 1-4 and 7-10 are strands, then the turn in
between should be given as "from 4 to 7", not "from 5 to 6". The graphical
objects begin and end at the given residues.
Coil radius is not depth-cued
In the PostScript output mode, the coil radius is depthcued only when slab is
set explicitly in the input file.
Top page
Penn State Milton S. Hershey Medical Center ?004
This page was last updated on May 09, 2005
Contact Us