CSB Core setup

The Molecular Surface Package is a suite of programs for computing and manipulating molecular surfaces and volumes. To use on SGI or Linux machines in the Core, type:

setup msp

This will also set up SGI Inventor on Linux systems, for viewing of optional output .iv image files via ivview. (ivview is automatically available on SGIs.)

A current PDF version of the manual is available.

In addition, the old version 3.5 documentation is retained below as HTML, though some features may have changed.

Table of Contents

Introduction

Examples

MSRoll

MSForm

MSDraw

Atom Property Commands

Standard File Formats

My File Formats

Introduction

MSRoll

• reads protein data bank format atomic coordinate file
• computes a dot surface (similar to that produced by MS)
• computes piecewise quartic molecular surface
• identifies and characterizes interior cavities
• computes molecular areas and volumes
• computes a polyhedral surface

MSDraw

• renders molecular surface and chemical model
• generates polyhedral surface plots with hidden-line elimination
• generates contours on a polyhedral molecular surface

MSForm

• measures the curvature of a polyhedral molecular surface
• computes a solvent-excluded density
• computes an interfacial surface between two densities

Examples

Volume and Area msroll -m coord.in -r atmrad.in [-p 1.4] -v surfvol.out -a atmsurf.out bca

Dot Surface with Normals msroll -m coord.in -j dots.out -o dots.inventor

PQMS surface msroll -m coord.in -q surf.pqms -o arcs.inventor

Simple Molecular Surface msroll -m coord.in -f 0.5 -t surf.vet -o surf.inventor

CPK Model msdraw -i commands.in -r image.rgb

Ball and Stick Model

   msdraw -i commands.in -r image.rgb

Ball and Stick plus Translucent Surface

   msroll -m coord.in -q surf.pqms
   msdraw -i commands.in -r image.rgb 

Backbone Worm with Internal Cavity and Translucent Surface

   msroll -m coord.in -q surf.pqms
   msdraw -i commands.in -r image.rgb [-z 0.3]

Two Interacting Surfaces msroll -m coord1.in -q surf1.pqms

   msroll -m coord2.in -q surf2.pqms 
   msdraw -i commands.in -r image.rgb

Surface Colored by Curvature in Stereo

   msform -t polyhedron -r radius -o polyhedron

The inventor files can be viewed with the Silicon Graphics ivview utility:

   ivview dots.inventor

The program reads atomic coordinates in Protein Data Bank format. The program computes a piecewise quartic molecular surface envelope surrounding the molecule of interest. The program can write this surface to disk as a binary file that is subsequently read by MSDraw. It also identifies internal cavities and computes analytical areas and volumes. It can print out the contact area, reentrant area, molecular area, accessible area and solvent-excluded volume of the entire molecule and of each interior cavity. The program can also write a disk file giving the areas of each atom. The program uses the binary surface file computed earlier and subdivides each curved face into several flat triangles for display on a three-dimensional interactive graphics display system. This gives a polyhedral surface for a protein molecule, with each internal cavity surrounded by a separate polyhedron. The edges and triangles of the polyhedral surface output disk file are labeled by component (cavity) number (the outer surface is component 1), atom number and color number. The atom coloring and tessellation fineness are determined by the atom-property file given with the -f flag. Polyhedral output can be written in WHATIF, AVS, and SGI Inventor formats. The dot surface component of the program computes a dot surface for a molecule. It is similar to the MS dot surface. The execution time increases linearly with the number of atoms, and as the cube of the probe radius. The flags are:

-a area_file [ bac | bca ]

This command cause a disk file of areas to be written. In the simplest situation, where there is no second argument for the area command, the output file contains one line for each atom. This line gives the contact, reentrant, molecular (contact+reentrant) and accessible areas of the atom. If the third argument is specified, the areas will be broken down by both atom and component (outer surface or cavity), with primary and secondary sorting fields determined by bac (by atom and component) or bca (by component and atom). The two alternative arguments given above determine whether the record order of the file is determined mainly by atom and secondarily by component, or vice-versa.


-e filename

The error message file (also contains informative messages).

-f fineness_angle | fineness_file

Either an angle, in radians, or a file name for an atom-property file.

-g grid_spacing

This command specifies the fineness of the probe-collision grid; the neighbor grid is twice this. The purpose of these grids is to speed up neighbor-finding (cube grid) and probe collision checks (bit grid). It is not possible to use one grid, but not the other. The grids are optional. If not given, no grid will be used. There is a certain amount of overhead involved with the grids, so it is not advisable to use them unless the molecule has at least one thousand atoms.

-j dot_surface_file name.

All the surface points will be written to the disk file, along with their normal vectors, if calculated. The records will be in ascending atom number order. Its format is given below, in the file formats section.

-k dot_area_file_name

This file gives the areas from the dot surface algorithm. Its format is given below, in the file formats section. The output file consists of one record per atom, and each record has three fields: contact area, reentrant area, and molecular area.

-m pdb_file

The atomic coordinates, in pdb format.

-o filename

Inventor output file name. Anything written for -d, -j, -q and -t flags will also be written to this file, but in SGI Open Inventor format.

-p probe_radius

The minimum allowed value is 0.0. This gives a van der Waals surface. Large values cause the program to be very slow. Default=1.5.

-q binary_surface_file name

The binary surface file is written to disk. Its format is given in the implementation manual.

-r radii_file

The van der Waals radii (see My File Formats).

-t polyhedral_surface_file name

The polyhedral surface file is computed and written to disk. This file is read by msdraw. Its format is given below, in the my file formats section. Currently supported formats are: "vet" (the default), "sgi" for Silicon Graphics, Inc. Inventor format (ascii), "whatif" (for Gerrit Vriend's WHATIF program).

-v volume_file

This command causes the volume output file to be written. The information includes the total area and volume of the molecule, plus a table of cavity areas, volumes and centers. Both analytical and polyhedral volumes and areas are given. Do not expect the numerical and analytical numbers to match too closely, unless the triangulation is very fine.

-y pattern file

This program reads atomic coordinate files in protein data bank (PDB) format. The program selects only those PDB input file records that begin with ATOM or HETATM. The program also replaces embedded blanks in some atom names by an underscore. The program has a default set of atomic radii, specified in the mspattern.h file. Van der Waals radii are assigned by a two-step procedure. First the residue name and the atom name in the PDB file are used to determine that atom type, which is an integer, and then the atom type is used to assign a radius. The defaults in the mspattern.h file (/srv/local/msp/v3.5/doc/) can be overridden in the following way. One prepares two files, a pattern file and a radius file, and then reads them with the -r and -y flags.

In the CSB core do the following to change radii or indroduce new atoms:

cp /srv/local/msp/v3.5/doc/* .

Edit atoms.radii and mspattern.h to suit your case, then give a command similar to the following:

msroll -m 2rns.pdb -p 1.4 -r atoms.radii -y mspattern.h -v prot.vol

For the formats of these file, see My File Formats, below.

MSForm

The density code from msroll and the density and solid angle code from msdraw have been removed and used to create a new program: msform. Looking at it another way, msform is made up of the old (version 2.9) msden and omega. The program can convert a polyhedron to a density, an vice-versa. It can also do shape measurement for either the polyhedron or the density. There are many things this program can do, and what it does is determined by which command line flags are present. Typing just the program name will print out all the different usages, but without the explanatory paragraphs below. The flags:

-t polyhedral input file in vet format

-n second polyhedral input file

-h third polyhedral input file

-d density input file

-y second density input file

-o output file (polyhedron or density)

-l density contour level (default = 0.5 for one density)

-x extension or expansion radius

-w density cube width

-r intersection sphere radius

Solid Angle Computations:

It can compute the curvature of the polyhedral surface by intersecting the polyhedron with spheres where the sphere centers are defined by the polyhedron vertices. By measuring the fraction of the region of each sphere that lies inside the solvent-excluded volume, one can quantitate surface region convexity and concavity. The program can write out the given polyhedral molecular surface with the solid angle written after the vertex coordinates.

msform -t polyhedron -r radius -o polyhedron

msform -t polyhedron -r radius -x increment -o polyhedron

This computes one solid angle for each polyhedron vertex.The purpose of this command is to measure the curvature of protein surfaces. The centers of the evaluation spheres are taken from the vertex coordinates of the polyhedron. The first vertex value field (u) is replaced by the solid angle of the evaluation sphere centered at that point. If the -x parameter is specified, the radius, radius + increment, radius + 2 * increment spheres will generate three values for the vertex (u, v, and w). If the analytical sphere-polyhedron algorithm fails, a numerical algorithm is used to compute omega. The program prints out the number of omegas computed numerically.

msform -t polyhedron -n polyhedron -r radius -o polyhedron

This computes solid angles for two polyhedra at once. This command uses two polyhedra (-t and -n). The first (-t) polyhedron is the one that will have values assigned to its vertices, and will be written as output (-o). The three vertex value fields will contain three solid angles. The first will be the solid angle subtended by the primary polyhedron as measured by a sphere centered at a vertex of the primary polyhedron. The second will be the solid angle subtended by the opposing polyhedron as measured by a sphere centered at this same vertex of the primary polyhedron. The third number will be the sum of the first two. It will be close to four pi steradians for a close fit.

msform -t polyhedron -n polyhedron -r radius -x extension -o polyhedron

This feature is used to identify surface buried in a protein-protein interface. The first (-t) polyhedron is the one that will have values assigned to its vertices. The number specified as the extension is the distance the intersection sphere is moved out along the normal vector. If one specifies for both the radius and extension parameters the same number as the probe radius used to compute the two protein surfaces, then the intersection sphere will have the same center and the same radius as the probe tangent to that vertex. The first (u) and third (w) fields in the primary polyhedron vertices will be given the value zero, and the second field (v) will be the solid angle of the intersection of the sphere with the second (-n) polyhedron. If that value is positive, that indicates that the probe collides with the opposing protein, and so that vertex is buried. The values are written into the value fields of the output (-o) polyhedron.

msform -t polyhedron -n polyhedron -h polyhedron -r radius -o polyhedron

The fifth usage style computes three solid angles, one for one protein, one for another protein, and their sum, as did an earlier style, but differs in that there are now three polyhedra. The first (-t) polyhedron is used solely to define vertices to center intersection spheres at. The second (-n) and third (-h) polyhedra are the ones that are intersected with the sphere. The output polyhedron is the first polyhedron, but with three vertex values set. The purpose of this feature is to use as the first polyhedron not a protein surface polyhedron, but an interfacial surface computed by a previous run of msform (see below).

Density Computations:

The program converts a polyhedral molecular surface into a three-dimensional array of cubes, each with a number between 0.0 and 1.0. The cubes entirely within the polyhedron receive a value of 1.0. The cubes entirely outside the polyhedron receive a value of 0.0. Cubes entirely inside the small surfaces bounding internal cavities also have zero densities. Cubes intersecting the polyhedral surface have densities somewhere inbetween 0 and 1. The solvent-excluded density file is written to disk in AVS field format.The density runs between 0.0 (no occupancy) and 1.0 (full occupancy). It is an occupancy density, not an electron density.

msform -t polyhedron -w width -o density [-v inventor_file]

This converts a polyhedron to a density. The density will have the value 1.0 inside the surface and 0.0 outside, with intermediate values at the surface. The density file format is AVS.The program reads a density file in AVS field format.

msform -t polyhedron -d density -r radius -o polyhedron

The program measures the shape of the density in the vicinity of each vertex of the most recent polyhedron. A sphere is constructed centered at each vertex and the cubes partially or entirely within the sphere are summed. The polyhedron is modified, so that the local volume normal vector is written into the normal vector fields, and the amount of two-foldness in the first (u) of the three value fields.

msform -d density [-l level] -o polyhedron

The program computes a polyhedral molecular surface from a density. The density is an occupancy density, not an electron density. The level parameter specifies what level to contour at. The default is 0.5. The radius parameter specifies what radius to use for computing the local volume and normal vector. A sphere is constructed centered at each cube center and the cubes partially or entirely within the sphere are used. The smooth=1 parameter means use smoothed density, where the average value of the density inside the sphere of the specified radius is used. For smooth=0, the value of the density at the sphere center is used as the function to be contoured. By converting a polyhedron to a density, and then converting it back again, but with smoothing, one ends up with a smoothed polyhedron.

msform -d density -y density [-r radius] [-s 0|1] -o polyhedron

The program computes a polyhedral interfacial surface between the two given densities. The two densities need to have the same cube width. A third density is temporarily created. The third density is the first density minus the second density. The contour level is always 0.0. A sphere is constructed centered at each cube center and the cubes partially or entirely within the sphere are used. The radius parameter specifies what radius to use for computing the local volume and normal vector. The smooth=1 parameter means use smoothed density, where the average value of the density inside the sphere of the specified radius is used. For smooth=0, the value of the density at the sphere center is used. The cubes near the interface will have values near 0.0 and vectors that point from the first density to the second. If the interface is not a close fit, or if the cubes are small enough to fit in the gaps between the densities, there will be holes in the interfacial surface, unless smoothing is used. The polyhedral surface created is assigned to the current molecule (which is just a dummy molecule).

msform -d density -y density -t polyhedron -r radius -o polyhedron

The program measures the shape of the two given densities (-d, -y) in the vicinity of each vertex of the given (-t) interface-bisecting polyhedral surface. The values are written in the value fields of the output (-o) polyhedron. The two densities need to have the same cube width. If a molecule has more than one density, the results are unpredictable. A sphere is constructed centered at each vertex and the cubes partially or entirely within the sphere are used. The interface polyhedron is modified, so that the local volume normal vector stored into the normal vector fields, and the shape in the three value fields. The first value (u) is the amount of two-foldness for the first density, the second value (v) is the amount of two-foldness in the second density, and the third value (w) is the local volume of the sum of the two densities. It will be close to 1.0 for regions where the fit is tight. The two-fold amounts should be similar for a close fit. The purpose of this computation is to provide input for a protein docking algorithm under development.

msdraw -i scriptfile -r rasterfile [format] -p plotfile [format] -v vectorfile

The program reads the surface files computed by MSRoll and creates three kinds of output files: (a) an image file of pixels that shows a smooth surface with hidden-surface elimination, (b) plots with hidden-line elimination, and (c) vector files in SGI Open Inventor format. Images can be written in 3 formats: sgi, sun and avsimage. The default format is "sgi" image, which is a 24-bit color format. For sun or avsimage formats, add the word sun or avsimage after the file name. The "sun" format produces the sun rasterfile format, which can be displayed under X Windows using the xview or xloadimage utilities. This is an 8-bit color format using a color lookup table. For AVS image format, use "avsimage" (for AVS field format, use "avsfield"). Plot output file format is either PostScript (the default) or "hpgl", which is HP-GL (Hewlett-Packard Graphics Language). MSDraw reads a script file in order to define the scene. The script file name is given after the -i flag. Its format and content are discussed below.

Optional Command Line Arguments

-s image_size

The image is always square, and the integer specifies its width (default 512).

-x plotx
-y ploty

This gives the plot dimensions. The default is 8.5 for plotx and 11.0 for ploty.

-b border

The argument is a floating-point number in angstroms. The window is expanded in all four directions (left, right, bottom, top) by the amount given in the border command. Default border value: 0.0.

-n alignment

Causes the window bounds to be rounded outwards to a multiple of the given parameter. Default=1.0.

-t title

Affects plotting only. This title will be assigned as a comment in the PostScript output file. I'm not sure whether embedded blanks are allowed. I'm also not sure whether embedded is spelled embedded or imbedded.

-h header

The header can be either inventor or vrml. The inventor option is the default and causes the SGI Open Inventor header to be written, while vrml causes 3D output files to be written with a VRML header.

-z zclip

The clipping plane is assumed to be parallel to the xy plane, and the argument must be in the range -1.0 to 1.0. The number is not in angstroms, but represents a fraction of the z range of the molecules. That is, a value of 1.0 clips nothing, a value of 0.0 clips through the middle, and a value of -1.0 clips everything. For plotting and Inventor output, triangles that cross the clipping plane will be truncated, and the new line that is introduced will be given the vet file's triangle color, or the polyhedron color, if specified. Bonds crossing the clipping plane will also be cut. See also the "no_clipping" command.

-a stereo_angle

This command is used for producing stereo pairs. The molecules, clipping plane (if present) and the light source will be rotated by the specified angle. It may be necessary to use a border and perhaps also an alignment parameter to make sure that the two images are drawn to the same scale.

-g shading

The argument is flat for flat or faceted triangles, and smooth for phong shading (default).

-f fineness

This parameter rarely needs to be specified. The argument is a floating point number in the range 1.0 to 2.0, controlling the fineness of the sampling in the rendering algorithm. If the fineness is too low, a few pixels will be vacant; if it is too high, the computation will take longer. Default fineness: 1.35.

Script (Scene Definition) File

-i script_file

The script file contains more complex information. A command cannot run to more than one line. There cannot be two commands on one line. Each command begins with a keyword defining the type of command. The format is free format. Any characters after a # will be ignored and can be used as comments. Blank lines are ignored. Keywords must be in lower case and cannot be abbreviated. All filenames should begin with a letter. In the command descriptions below, optional command arguments are enclosed in square brackets. When either of two alternatives are acceptable, they are separated by a pipe (|) symbol.

Global Script Commands

These commands affect the whole picture. There are three commands that, if present, should appear only at the top of the script file: rotation, shading_model, and light_source. They are optional.

rotation angle x y z

This specifiea an angle (in degrees) and an axis. The vector need not be of unit length, but it should never be 0.

shading_model depth ambient diffuse specular exponent

The arguments are all floating-point numbers. The first four numbers must add up to 1.00. They give the fraction of the intensity (gray) levels to assign to the relevant function. The last number is the exponent of the cosine for the specular reflection (highlight). The depth parameter gives the amount of depth cueing. The ambient parameter gives the brightness of the object at the regions farthest away from the direction of the light source. Default:

shading_model 0.0 0.0 0.8 0.2 2.0

light_source vx vy vz

The direction vector of a light source at infinity. The vector does not need to be of unit length. Default: 0.5 0.5 1.0

After these commands, if present, come the descriptions of each molecule. Each molecule is introduced with a molecule command, followed by commands to read surface output files from msroll and to control how the objects are displayed.

Commands for Reading Molecular and Surface Data

molecule name pdb_file [radii_file]

The name should be less than 40 characters. It becomes the name of the set of atoms read in from the pdb file, and is used in the connect command (see below). The radius file is optional; if missing, radii will be taken from the mspattern.h file. The pdb_file should be specified, except for special "pseudo-molecules" used to hold interfacial polyhedral surfaces (see below).

read_surface filename

This command will render the molecular surface in the specified binary surface file.

read_polyhedron filename

This command will render the polyhedral molecular surface in the specified vet-format file, which should be an output file from the msroll program. The msroll output file must be in vet format.

normals length

Vertex normals of the specified length will be drawn. There will be one vector for each vertex of the polyhedron. Each vertex normal is the average of the triangle normals of the triangles that meet at the vertex. Short vectors (around 0.1) will give the look of a dot surface. As always, hidden-line elimination is performed. The command should occur sometime after the read_polyhedron command. It affects the plot only, not the rendered image.

ball_and_stick

This command will render a ball and stick model for image output and it will draw a stick figure for plot output. The atomic coordinates are taken from the current molecule file, the connectivity from that created by the prior connect commands for this molecule. The radii of the balls are determined by the ball field of the atoms of the current molecule, which in turn is set by the atom-property commands pertaining to the current molecule. This command will also render a tube model, in some circumstances. If there are exactly two bonds to an atom, they have equal radii, and the value of the elbow parameter (default = 2.0) is greater than 1.0, then the atom will be drawn as an elbow (part of a torus), instead of as a sphere. This will also occur if there are more than two bonds to the atom, provided that the two fattest bonds have radii that are equal and larger than the radius of the third fattest bond to the atom. To disable tubes, so that you always get only balls for atoms, set elbow to 0.0 (see the elbow command, below). The color argument affects the plotted output, only. If the color is not specified, the plotted model will be black. The coloring for the rendered model is taken from the color fields of the atoms as specified in the atom property file commands pertaining to the current molecule.

Commands for Defining Object Coloring and Style

The colors below are predefined. The integers are used in ascii polyhedron (vet) files, while the names are used in the msdraw script files.

define_color dark_green 0.0 0.5 0.1

This command defines new colors. The color name can be up to 15 letters. There can be up to 256 colors.

input_coloring

This command applies only to polyhedral input files. The coloring is taken from the hue field in the edge and triangle records of the vet file. This command should occur after the read_surface or read_polyhedron command.

atom_coloring

This command has no parameters. The hues are taken from the color field of the atoms, as set by the atom property commands. This command should occur after the read_surface or read_polyhedron command.

uniform_coloring hue1 [hue2]

The first hue is for the outer side and the second for the inner side, which is visible only if there is clipping or transluscency. This command should occur after the read_surface or read_polyhedron command.

component_coloring hue1 hue2 hue3

The first two arguments refer to the outer and inner sides of the outer surface; the third argument refers to the inner (cavity) surfaces. This command should occur after the read_surface or read_polyhedron command.

shape_coloring contact_hue reentrant_hue

shape_coloring convex_hue saddle_hue concave_hue

This command should occur after the read_surface or read_polyhedron command.

atom_opacity

The atom opacities are set by atom property commands. This command should occur after the read_surface or read_polyhedron command.

uniform_opacity opacity1 [opacity2]

The uniform opacity argument is in the range 0.0 to 1.0. A value of 0.0 will make the surface invisible, a value of 1.0 will make it opaque. The values 0.25, 0.50, and 0.75 cause every fourth, every other, and three out of four pixels to be drawn, respectively. Other values are rounded to the nearest of these five values. The words transparent (0.0), translucent (0.5) and opaque (1.0) can also be used instead of numbers. This command should occur after the read_surface or read_polyhedron command.

component_opacity outer_surface inner_surface cavity

The component opacities are in the range 0.0 to 1.0. This command should occur after the read_surface or read_polyhedron command.

shape_opacity contact_opacity reentrant_opacity

The opacity arguments are reals in the range 0.0 to 1.0. This command should occur after the read_surface or read_polyhedron command.

outer_line_width real

inner_line_width real

cavity_line_width real

bond_line_width real

Affects plotting only. This line width is a factor that multiplies the basic line width. The basic line width depends upon the output format. It is 0.35 mm for HP-GL, and 1 point for PostScript. The outer and inner parameters refer to the outer and inner sides of the polyhedral surfaces. The cavity width applies to internal cavities, and the bond width to the stick figure. The defaults are 1.0 (outer), 0.2 (inner), 1.5 (cavity) and 1.5 (bond). These commands should follow the molecule command, but occur before the read_polyhedron and ball_and_stick commands.

elbow real

The argument is a floating point number in the range 0.0 to 10.0, controlling the ratio of the elbow torus radius to the bond radius. If the value is below 1.0, no elbows will be drawn. The purpose of the command is to control the rendering of the tube model. Default: 2.0. This command should occur after the molecule command, but before the ball_and_stick command.

ball_radius real

The argument is a floating point number that specifies the ball radius for the ball and stick model. It is possible to override this value with atom property commands assigning values to the atom's ball field (see below). Default: 0.5. This command should occur after the molecule command, but before the ball_and_stick command.

bond_radius real

The argument is a floating point number that specifies the cylinder radius for the ball and stick model. Default: 0.3. This command should occur after the molecule command, but before the ball_and_stick command.

blank

This command causes the polyhedron edges not to be drawn, but it still hides lines behind it. It should occur after the read_polyhedron command.

no_clipping

This command refers to just the current object. It should occur after the molecule command and some of the commands. It will cause the object not to be clipped by the clipping plane, if specified. It is generally used to have the chemical model protrude from a clipped surface. The command should occur after the command defining the object (ball_and_stick, polyhedron or surface) that is not to be clipped.

Script Commands for Contouring

The program computes contours for the shape function (u, v or w). It will also contour the x, y or z coordinates, to produce a stack of planar contours. The contouring can be output in one of three ways: (a) as bands of color in a rendered image, (b) as contour lines in a plot, or (c) as three-dimensional contours in an SGI Open Inventor file. contour function from to ramp

This command replaces the previous contour commands and the vertex_coloring and function commands. The from and to are real numbers (have a decimal point) and the ramp must have been defined by a define ramp command (see below). The only functions currently allowed are: u, v, w, x, y, z. The u, v and w are the first, second and third vertex value fields. The x, y and z are simply the vertex cartesian coordinates. For plotting and vector output, there will be a contour polyline at each ramp level. The ramp specifies the number of values and the color of each, but the contour command specifies the range of values (from -- to). For rendering the polyhedron, there will be a bands of color. The maximum number of contour levels is 255.define_ramp tramp orange 10 green

define_ramp  onramp  yellow 3 green 2 cyan 2 blue 2 navy

There must be at least two colors mentioned, up to as many as will fit on a line. The integers are the number of intermediate colors and must be at least 1. The total number of color levels must be less than 256.

Atom Property Commands

A file of atom-property commands is read by the "-f filename" argument to MSRoll. These commands are also read after the "molecule" command of MSDraw and are applied to that molecule. Comments begin with # and may occur on a command line or on their own line. The fields are the information that is contained in each atomic record in the program.

Some of these fields require explanation. The character string fields may be at most 6 characters long. The "atom" field means atom name in the PDB file; the "kind" field means a user-defined atom type, such as C2 for methylene carbon; the type field means the integer used to choose a van der Waals radius from the radii file; the "element" field is the atomic number. The "anumber" field is not the atomic number, but is the atom number in the PDB file. The "radius" field is the van der Waals radius; the "covalent" field is the covalent radius and is used in determining connectivity. The "ball" field is the radius for ball-and-stick figures in MSDraw. Simply reading an input PDB file sets the values of many of these fields. The values of the other fields are set by various algorithms that the program uses. They can be overridden by the user. Some fields such as kind are null if not set by the user. The van der Waals and covalent radii are determined by the header file: mspattern.h. The -r radius_file and -y pattern_file arguments to MSRoll will allow the user to read in radius and pattern files. The ball radii are set to 0.5. The angle field tells the program how finely to tessellate (triangulate) the surface. A small number generates a large number of small triangles. A large number generates a small number of large triangles. The number must be in radians. The maximum allowed value for this angle field is 1.5 radians. For a value of 1.5 radians, the surface will be crude. The default value of 1.0 gives a reasonably smooth surface. The execution time of the program increases inversely as the square of this parameter.

The atom field values not defined in the PDB input file are set by a two-step process:

(1) Define sets of atoms based upon input field values from the PDB file:

setname = field operator constant

where operator is one of:

matches initial substring

inside for spheres

outside for spheres

above for planes

below for planes

== numeric or character string

!= numeric or character string

< numeric

<= numeric

> numeric

>= numeric

The "matches" operator is used for determining atom type from atom name: "atom matches C" is true for any atom name beginning with the letter C. Case is ignored. The "inside" and "outside" operators select atoms inside or outside a sphere (see below). The "above" and "below" operators select atoms on one side or the other of a plane (see below). The "above" operator selects atoms on the side of the plane in the direction the normal vector. Note that only the "=" and "!=" can be used for character strings; the greater than and less than operators are used only for numbers.

(2) Define output field values for atoms in these sets by field assignment commands:

setname field = constant

Further commands related to atom sets and atom properties:

setname = field operator constant

setname += field operator constant

setname -= field operator constant

setname *= field operator constant

setname2 = setname1

setname3 = setname1 * setname2

setname3 = setname1 + setname2

setname3 = setname1 - setname2

sphere spherename x y z radius

plane planename x y z xn yn zn

clear setname

connect setname [tolerance ]

disconnect setname1 setname2

tolerance value

bond_radius radius

ball_radius radius

The +=, -= and *= assignment commands are similar to the simple = assignment command. The clear command causes a set to become empty. The connect command creates bonds for atoms in the specified set. Two atoms are connected if their separation is less than the sum of their van der Waals radii, plus the tolerance. The tolerance should be specified before the connect command. Only atoms belonging to the same molecule will be connected. The disconnect command removes all bonds from an atom in the first set to an atom of the second set. The bond radius is set by the bond_radius command. The general ball radius can be modified by the ball_radius command, which should occur before the ball_and_stick command.

Standard File Formats

sgi (image)

The Silicon Graphics image format is described by the rgb (4) manual page and the image.h include file. The fact that the header is 512-bytes long does not seem to be documented.

sun (image)

Sunraster formatFor the format of this file, consult the "rasterfile.h" #include file of SUN Microsystems. After the header there is a color lookup table. The color lookup table has 256 entries. The number of shades per color depends upon the number of colors actually used in the image.

avsimage (image)

avsfield (image)

The first format is a format developed by AVS specifically for images. It is also possible to write images in their more general field format. The are three real numbers per pixel, giving the amounts of red, green and blue. See the AVS documentation.

sgi (vector)

This will produce an ascii file in SGI's Inventor format, which can be viewed using ivview.

whatif (vector)

This is the .vec format read in by Gerrit Vriend's WHATIF program (G. Vriend, "WHAT IF: A molecular modeling and drug design program", Journal of Molecular Graphics 8, pp. 52-56, 1990). There is one line for each edge. Each line contains seven floating-point numbers, the first six giving the coordinates of the two vertices, and the seventh giving the line color.

AVS geometry file (vector)

This is a triangle format read by the Advanced Visualization Systems geometry file input filter polyh.c, which is included in AVS's distribution. Line 1: the word "facet" or "smooth". Line 2: the number of vertices. Next, the vertices, one per line (x, y and z). After the vertices come the triangles. Each triangle has three vertex numbers (vertex numbering begins with 1). The vertices are counter-clockwise, as viewed from the probe.

AVS field file (density)

The MSRoll program writes density in AVS field format, which consists of an ASCII header, followed by two form-feed characters, and then the binary data.

My File Formats

binary piecewise quartic surface

The pre-3.5 format of the binary surface file written by MSRoll is given in the implementation manual. Beginning with version 3.5, the format has been modified to handle larger molecules. The shorts have been replaced by longs, and the floats by doubles. However, the new MSDraw program can still read old pqms files.

atomic area

This file gives the solvent-accessible areas of individual atoms. There is one line per atom. There are four floating point numbers per line. The first floating point number is the contact area, the second is the reentrant area, the third is their sum (molecular area), and the fourth is the accessible area. The accessible area describes the trace or trajectory of the center of the probe sphere, and has often been related to physical chemistry. Consult Fred Richards' publications for a discussion of molecular areas and volumes.

volume

This file gives the total contact, total reentrant, total molecular (contact+reentrant), and total accessible areas of the molecule, and the solvent-excluded volume of the molecule. This volume does not include the volumes of any internal cavities (packing defects large enough to accommodate the probe). These summary areas and volumes are followed by a table of centroids, volumes, and areas for each surface component. A surface component is a connected piece of surface. For small molecules there will be only one component. For large molecules, such as proteins, the first component is the outer surface, and the following components are surfaces bounding cavities. The volume for the outer surface includes the volumes of all the cavities. The cavity volumes are always negative, which is how they may be distinguished from a surface bounding a separate, small molecule located a few angstroms from the protein surface. Thus simply summing the volume column of this table will give the solvent-excluded volume given at the beginning of the file. That is, the cavity volume is not considered to be part of the solvent-excluded volume of the protein. The component areas are molecular areas (contact area plus reentrant area) followed by accessible areas.

vet

The first record has three integers ("%d %d %d"). The first integer is the number of vertices, the second integer is the number of edges, and the third integer is the number of triangles. The vertex coordinates then follow. Each line has the C format: "%12.6f %12.6f %12.6f %7.4f %7.4f %7.4f %10.6f %10.6f %10.6f %3d %5d %3d". The first three fields are the vertex coordinates and the next three fields are a unit normal vector for the vertex.The next three fields are the function values (default=0.0) for the vertex. They are there for assigning properties to vertices, for example shape or electrostatic potential (by some external program). The next three fields are integers: component number, atom number and color (hue). Next come the edge records. Each one has C format: "%6d %6d %3d %5d %3d". The first two numbers specify the vertex numbers, which start at one. The vertex numbers correspond to the order of the vertex records earlier in this file. The next three numbers are the component number, the atom number and the color (hue) number. For edges on the boundary between different atoms or different colors, one of the two possibilities will be chosen randomly. Finally come the triangles. Each line has three edge numbers (the edge numbers start at one and are implicitly given by the order of the edge records), followed by three vertex numbers, followed by a surface-component number, an atom number and a color number. The edge numbers are signed; that is, a negative number means traverse the edge in the reverse direction. The edges and vertices are in counter-clockwise order when viewed from outside the molecule. The C format of a triangle line is: "%7d %7d %7d %6d %6d %6d %3d %5d %3d". The atom and color numbers are determined by which atom the center of the triangle is closest to. The triangles are sorted by atom number.

surface point

The surface output file has one line per surface point. The surface points are in ascending atom number order, with the contact points of each atom preceding the reentrant points. The output format is similar to that of MS (QCPE program #429), except that: (a) the second and third atom numbers of reentrant surface points are not correct, (b) shape number is always 2, even when the probe touches three atoms, (c) contact and reentrant points are written to a single file, and (d) in atom number order, so there is no need for sorting or merging.

radius file (/srv/local/msp/v3.5/doc/atoms.radii)

The first real number is the van der Waals radius and the second is the covalent radius. The first field in the radius file and the third field in the pattern field are the atom type, which provides a bridge between the two files.

pattern file (/srv/local/msp/v3.5/doc/mspattern.h)

A question mark matches any one character. A string consisting of only an asterisk matches any string. There is no feature for, C*, for example, to match any string beginning with C. You would have to use as series of lines: C, C?, C??, C???, C????. The residue and atom names can be at most 5 characters. The fourth field, the atom kind, is currently not used. The last match found is used, so less-specific matches should be listed first.