R a s M o l v 2 . 5 ===================== A Molecular Visualisation Program Roger Sayle Biomolecular Structure Department Glaxo Research and Development Greenford, Middlesex, UK. Copyright (C) 1992,1993,1994 by Roger Sayle (rasmol@ggr.co.uk) The information supplied in this document is believed to be true but no liability is assumed for its use or for the infringements of the rights of the others resulting from its use. Information in this document is subject to change without notice and does not represent a commitment on the part of the supplier. This package is sold/distributed subject to the condition that it shall not, by way of trade or otherwise, be lent, re-sold, hired out or otherwise circulated without the supplier's prior consent, in any form of packaging or cover other than that in which it was produced. No part of this manual or accompanying software may be reproduced, stored in a retrieval system on optical or magnetic disk, tape or any other medium, or transmitted in any form or by any means, electronic, mechanical, photocopying, recording or otherwise for any purpose other than the purchaser's personal use. This product is not to be used in the planning, construction, maintenance, operation or use of any nuclear facility nor the flight, navigation or communication of aircraft or ground support equipment. The author shall not be liable, in whole or in part, for any claims or damages arising from such use, including death, bancruptcy or outbreak of war. INTRODUCTION ============ RasMol2 is a molecular graphics program intended for the visualisation of proteins, nucleic acids and small molecules. The program is aimed at display, teaching and generation of publication quality images. RasMol runs on Microsoft Windows, Apple Macintosh, UNIX and VMS systems. The UNIX and VMS systems require an 8, 24 or 32 bit colour X Windows display (X11R4 or later). The program reads in a molecule co-ordinate file and interactively displays the molecule on the screen in a variety of colour schemes and molecule representations. Currently available representations include depth-cued wireframes, 'Dreiding' sticks, spacefilling (CPK) spheres, ball and stick, solid and strand biomolecular ribbons, atom labels and dot surfaces. COMMANDS ======== RasMol allows the execution of interactive commands typed at the "RasMol>" prompt in the terminal window. Each command must be given on a separate line. Keywords are case insensitive and may be entered in either upper or lower case letters. All whitespace characters are ignored except to separate keywords and their arguments. The commands/keywords currently recognised by RasMol are given below. backbone background centre clipboard colour connect cpk dots define echo exit hbonds help label load print quit renumber reset restrict ribbons rotate save script select set show slab source spacefill ssbonds strands structure trace translate wireframe write zap zoom Backbone -------- Syntax: backbone {} backbone The RasMol `backbone' command permits the representation of a polypeptide backbone as a series of bonds connecting the adjacent alpha carbons of each amino acid in a chain. The display of these backbone `bonds' is turned on and off by the command paramater the same as the `wireframe' command. The command `backbone off' turns off the selected `bonds', and `backbone on' or with a number turns them on. The number can be used to specify the cylinder radius of the representation in either angstrom or rasmol units. A parameter value of 500 (2.0 angstroms) or above results in a "Parameter value too large" error. Backbone objects may be coloured using the RasMol `colour backbone' command. The reserved work `backbone' is also used as a predefined set and as a parameter to the `set hbond' and `set ssbond' commands. The RasMol command `trace' is synonymous with the command `backbone.' Background ---------- Syntax: background The RasMol `background' command is used to set the colour of the "canvas" background. The colour may be given as either a colour name or a comma separated triple of Red, Green and Blue (RGB) components enclosed in square brackets. Typing the command `help colours' will give a list of the predefined colour names recognised by RasMol. When running under X Windows, RasMol also recognises colours in the X server's colour name database. The `background' command is synonymous with the RasMol `set background' command. Centre ------ Syntax: center {} centre {} The RasMol `centre' command defines the point about which the `rotate' command and the scroll bars rotate the current molecule. Without a parameter the centre command resets the centre of rotation to be the centre of gravity of the molecule. If an atom expression is specified, RasMol rotates the molecule about the centre of gravity of the set of atoms specified by the expression. Hence, if a single atom is specified by the expression, that atom will remain `stationary' during rotations. Type `help expression' for more information on RasMol atom expressions. Clipboard --------- Syntax: clipboard The RasMol `clipboard' command places a copy of the currently displayed image on the local graphics `clipboard'. Note: this command is not yet supported on UNIX or VMS machines. It is intended to make transfering images between applications easier under Microsoft Windows or on an Apple Macintosh. When using RasMol on a UNIX or VMS system this functionality may be achieved by generating a raster image in a format that can be read by the receiving program using the RasMol `write' command. Colour ------ Syntax: colour {} color {} Colour the atoms (or other objects) of the selected region. The colour may be given as either a colour name or a comma separated triple of Red, Green and Blue (RGB) components enclosed in square brackets. Typing the command `help colours' will give a list of all the predefined colour names recognised by RasMol. Allowed objects are `atoms,' `bonds,' `backbone,' `ribbons' `labels' `dots,' `hbonds,' and `ssbonds.' If no object is specified, the default keyword `atom' is assumed. Some colour schemes are defined for certain object types. The colour scheme `none' can be applied all objects accept atoms and dots, stating that the selected objects have no colour of their own, but use the colour of their associated atoms (i.e. the atoms they connect). `Atom' objects can also be coloured by `cpk,' `amino,' `chain,' `group,' `shapely,' `structure,' `temperature' `charge' and `user. Hydrogen bonds can also be coloured by' `type' and dot surfaces can also be coloured by `electrostatic potential.' For more information type `help colour .' Connect ------- Syntax: connect {} The RasMol `connect' command is used to force RasMol to (re)calculate the connectivity of the current molecule. If the original input file contained connectivity information, this is discarded. The command `connect false' uses an extremely fast heuristic algorithmm that is suitable for determing bonding in large bio-molecules such as proteins and nucleic acids. The command `connect true' uses a slower more accurate algorithm based upon covalent radii that is more suitable for small molecules containing inorganic elements or strained rings. If no parameters are given, RasMol determines which algorithm to use based on the number of atoms in the file. Greater than 255 atoms causes RasMol to use the faster implementation. This is the method used to determine bonding, if necessary, when a molecule is first read in using the `load' command. Define ------ Syntax: define The RasMol `define' command allows the user to associate an arbitrary set of atoms with a unique identifier. This allows the definition of user-defined sets. These sets are declared statically, i.e. once defined the contents of the set do not change, even if the expression defining them depends on the current transformation and representation of the molecule. Dots ---- Syntax: dots {} dots The RasMol `dots' command is used to generate a Van der Waal's dot surface around the currently selected atoms. Dot surfaces display regularly spaced points on a sphere of Van der Waals' radius about each selected atom. Dots that would are `buried' within the Van der Waal's radius of any other atom (selected or not) are not displayed. The command `dots on' deletes any existing dot surface and generates a dots surface around the currently selected atom set with a default dot density of 100. The command `dots off' deletes any existing dot surface. The dot density may be specified by providing a numeric parameter between 1 and 1000. This value approximately corresponds to the number of dots on the surface of a medium sized atom. By default, the colour of each point on a dot surface is the colour of it's closest atom at the time the surface is generated. The colour of the whole dot surface may be changed using the `colour dots' command. Echo ---- Syntax: echo {} The RasMol `echo' command is used to display a message in the RasMol command/terminal window. The string parameter may optionally be delimited in double quote characters. If no parameter is specified, the `echo' command displays a blank line. This command is particularly useful for displaying text from within a RasMol `script' file. HBonds ------ Syntax: hbonds {} hbonds The RasMol `hbond' command is used to represent the hydrogen bonding of the protein molecule's backbone. This information is useful in assessing the protein's secondary structure. Hydrogen bonds are represented as either dotted lines or cylinders between the donor and acceptor residues. The first time the `hbond' command is used, the program searches the structure of the molecule to find hydrogen bonded residues and reports the number of bonds to the user. The command `hbonds on' displays the selected `bonds' as dotted lines, and the `hbonds off' turns off their display. The colour of hbond objects may be changed by the `colour hbond' command. Initially, each hydrogen bond has the colours of its connected atoms. By default the dotted lines are drawn between the accepting oxygen and the donating nitrogen. By using the `set hbonds' command the alpha carbon positions of the appropriate residues may be used instead. This is especially useful when examining proteins in backbone representation. Help ---- Syntax: help { {}} ? { {} The RasMol `help' command provides on-line help on the given topic. Label ----- Syntax: label {} label The RasMol `label' command allows an arbitrary formatted text string to be associated with each currently selected atom. This string may contain embedded `expansion specifiers' which display properties of the atom being labelled. An expansion specifier consists of a `%' character followed by a single alphabetic character specifying the property to be displayed (similar to C's printf syntax). An actual '%' character may be displayed by using the expansion specifier `%%'. Atom labelling for the currently selected atoms may be turned off with the command `label off.' By default, if no string is given as a parameter RasMol uses labels appropriate for the current molecule. RasMol uses the label "%n%r:%c.%a" if the molecule contains more than one chain, "%e%i" if the molecule has only a single residue (a small molecule) and "%n%r.%a" otherwise. The colour of each label may be changed using the `colour label' command. By default, each label is drawn in the same colour as the atom to which it is attached. The size of the displayed text may be changed using the `set fontsize' command. The following table lists the current expansion specifiers: %a Atom Name %b %t B-factor/Temperature %c %s Chain Identifier %e Element Atomic Symbol %i Atom Serial Number %n Residue Name %r Residue Number Load ---- Syntax: load {} Load a molecule co-ordinate file into RasMol2. Valid molecule file formats are `pdb' (Brookhaven Protein Databank), `mdl' (Molecular Design Limited's MOL file format), `alchemy' (Tripos' Alchemy file format), `mol2' (Tripos' Sybyl Mol2 file format), `charmm' (CHARMm file format) or `xyz' (MSC's XMol XYZ file format). If no file format is specified, `pdb' is assumed by default. Only a single molecule may be loaded at a time. To delete a molecule prior to loading another use the RasMol `zap' command. The `load' command selects all the atoms in the molecule, centres it on the screen and renders it as a CPK coloured wireframe model. If the molecule contains no bonds (i.e. contains only alpha carbons), it is drawn as an alpha carbon backbone. If the file specifies less bonds than atoms, RasMol determines connectivity using the `connect' command. Print ----- Syntax: print The RasMol `print' command sends the currently displayed image to the local default printer using the operating system's native printer driver. Note: this command is not yet supported under UNIX or VMS. It is intended to take advantage of Microsoft Windows and Apple Macintosh printer drivers. For example, allowing images to be printed directly on a dot matrix printer. When using RasMol on a UNIX or VMS system this functionality may be achieved by either generating a PostScript file using the RasMol `write ps' or `write vectps' commands and printing that or generating a raster image file and using a utility to dump that to the local printer. Quit ---- Syntax: quit exit Exit from the RasMol program. The RasMol commands `exit' and `quit' are synonymous. Renumber -------- Syntax: renumber {{-} } The RasMol `renumber' command sequentially numbers the residues in a macromolecular chain. The optional parameter specifies the value of the first residue in the sequence. By default, this value is one. For proteins, each amino acid is numbered consecutively from the N terminus to the C terminus. For nucleic acids, each base is numbered from the 5' terminus to 3' terminus. All chains in the current database are renumbered and gaps in the original sequence are ignored. The starting value for numbering may be negative. Reset ----- Syntax: reset The RasMol `reset' command restores the original viewing transformation and centre of rotation. The scale is set to it default value, `zoom 100,' the centre of rotation is set to the geometric centre of the currently loaded molecule, `centre all,' this centre is translated to the middle of the screen and the viewpoint set to the default orientation. This command should not be mistaken for the RasMol `zap' command which deletes the currently stored molecule, returning the program to its initial state. Restrict -------- Syntax: restrict {} The RasMol `restrict' command both defines the currently selected region of the molecule and disables the representation of (most of) those parts of the molecule no longer selected. All subsequent RasMol commands that modify a molecule's colour or representation effect only the currently selected region. The parameter of a `restrict' command is a RasMol atom expression that is evaluated for every atom of the current molecule. This command is very similar to the RasMol `select' command, except restrict disables the `wireframe,' `spacefill' and `backbone' representations in the non-selected region. Type "help expression" for more information on RasMol atom expressions. Ribbons ------- Syntax: ribbons {} ribbons The RasMol `ribbons' command displays the currently loaded protein or nucleic acid as a smooth solid "ribbon" surface passing along the backbone of the protein. The ribbon is drawn between each amino acid whose alpha carbon is currently selected. The colour of the ribbon is changed by the RasMol `colour ribbon' command. If the current ribbon colour is `none' (the default), the colour is taken from the alpha carbon at each position along its length. The width of the ribbon at each position is determined by the optional parameter in the usual RasMol units. By default the width of the ribbon is taken from the secondary structure of the protein or a constant value of 720 (2.88 Angstroms) for nucleic acids. The default width of protein alpha helices and beta sheets is 380 (1.52 Angstroms) and 100 (0.4 Angstroms) for turns and random coil. The secondary structure assignment is either from the PDB file or calculated using the DSSP algorithm as used by the `structure' command. This command is similar to the RasMol command `strands' which renders the biomolecular ribbon as parallel depth-cued curves. Rotate ------ Syntax: rotate {-} Rotate the molecule about the specified axis. Permited values for the axis parameter are "x", "y" and "z". The integer parameter states the angle in degrees for the structure to be rotated. For the X and Y axes, positive values move the closest point up and right, and negative values move it down and left respectively. For the Z axis, a positive rotation acts clockwise and a negative angle anti-clockwise. Save ---- Syntax: save {pdb} save alchemy Save the currently selected set of atoms in either a Brookhaven Protein Database (PDB) or Alchemy(tm) format file. The distinction between this command and the RasMol `write' command has been dropped. The only difference is that without a format specifier the `save' command generates a `PDB' file and the `write' command generates a `GIF' image. Script ------ Syntax: script The RasMol `script' command reads a set of RasMol commands sequentially from a text file and executes them. This allows sequences of commonly used commands to be stored and performed by single command. A RasMol script file may contain a further script command up to a maximum "depth" of 10, allowing compilicated sequences of actions to be executed. RasMol ignores all characters after the first '#' character on each line allowing the scripts to be annotated. Script files are often also annotated using the RasMol `echo' command. The most common way to generate a RasMol script file is to use the `write script' or `write rasmol' commands to output the sequence of commands that are needed to regenerate the current view, representation and colouring of the currently displayed molecule. The RasMol command `source' is synonymous with the `script' command. Select ------ Syntax: select {} Define the currently selected region of the molecule. All subsequent RasMol commands that manipulate a molecule or modify its colour or representation, only effects the currently selected region. The parameter of a `select' command is a RasMol expression that is evaluated for every atom of the current molecule. The currently selected (active) region of the molecule are those atoms that cause the expression to evaluate true. To select the whole molecule use the RasMol command `select all.' The behaviour of the `select' command without any parameters is determined by the RasMol `hetero' and `hydrogen' parameters. Type "help expression" for more information on RasMol atom expressions. Set --- Syntax: set {