AstexViewer Documentation

Mike Hartshorn (m.hartshorn@astex-technology.com)

Astex Technology Ltd.
250 Cambridge Science Park, Milton Road
Cambridge, CB4 0WE, UK
http://www.astex-technology.com/

Introduction

AstexViewer is a program for displaying molecular structures and electron density maps. It has been developed specifically for displaying protein/ligand complexes and is not intended for high quality molecular graphics.

The contents of this documentation are:

Conditions of Use
Usage
Mouse Controls
Keyboard Controls
Menu Items
Colours
Web Page Applets
Scripting Language
Applet Methods

Conditions of Use

AstexViewer has been provided as it may prove useful to the structural biology community. No warranties of any kind are provided or implied.You may use the program for any purpose subject to the conditions of supply and use in the CCP4 Software Licence and the following additional terms and Conditions of Use:

1. AstexViewer is provided as is and Astex makes no warranty as to its use, performance or results which the user may obtain using the software.
2. Astex makes no warranty, express or implied, as to the merchantability, non-infringement of third party rights, or fitness for any particular purpose.
3. In no event will Astex be liable to the user for any consequential, incidental or special damages, including any lost profits or savings, or for any claim by any third party.
4. The user is permitted to use, copy and distribute the AstexViewer software provided that this is performed under the terms of these Conditions of Use and the CCP4 Software Licence. A notice to Astex Technology must appear in all copies. If you use the AstexViewer on a publicly accessible internet site the user shall include the Astex company logo on the site as well as an acknowledgement of the origin of the program.
5. The user is not permitted to repackage the software for inclusion in other packages without the prior approval of Astex.
6. The user is not permitted to copy, modify, sublicence, distribute or transfer the AstexViewer software except as expressly provided under these Conditions of Use and the CCP4 Software Licence. Any attempt otherwise will automatically terminate any user rights to use the AstexViewer software.
7. Astex is under no obligation to maintain the AstexViewer software nor to respond to requests for information from the user.
8. Any publication arising from the use of AstexViewer should be accompanied by a reference to Astex Technology as the originator and author of the AstexViewer software.
9. All other terms and conditions of the supply of AstexViewer by CCLRC shall apply as specified in the CCP4 Software Licence.

Usage

AstexViewer is written in Java 1.1 and will run unchanged on a variety of computer platforms. The program has been used on PC's running Windows 95/98/NT, SGI workstations, Linux systems and as an applet in Netscape and Microsoft Internet Explorer.

Windows

Under Windows the program can be launched from a desktop icon or by typing the program name (AstexViewer) in a Dos window. The program name may be followed by one or more molecule names. These molecules will be read in turn and displayed by AstexViewer when it starts up.

By default the viewer will center on the first molecule named on the command line. If a protein and ligand are stored in separate files it is extremely simple to center on the ligand. Just name the ligand file first on the command line.

Unix

The same method can be used for starting the viewer on Unix machines. The program is usually called astex_viewer on these machines.

Mouse Controls

Keyboard Controls

Menu Items

• File

  Open Structure...

  Provides a file open box. All files are listed in a particular directory (not just structure files), due to a deficiency in Java.

  Multiple structures can be opened. PDB files and mol files are supported.

  Open Map...

  Provides a file open box, and allows CCP4 format maps to be opened.

  Close

  Provides a menu of loaded structures. Choosing a structure will remove that structure from the viewer.

  Write Gif

  Pops up a file chooser. A gif file name can be specified and the current image from the viewer will be written to that file (This functionality works only when AstexViewer is running as an application, not an Applet in a web browser). Images can be us

  Exit

  When running as an application this will close the viewer.

• Select

  This menu provides some partial functionality for selecting certain atoms in the structures that are displayed. Selected atoms are highlighted with a yellow dot.

  The viewer was originally intended for displaying protein/ligand complexes and so currently only has functionality for selecting ligand groups. The ligands are identified automatically.

  Clear

  This will unselect all atoms

  Exclude

  This makes all selections remove the matching atoms from the current selection.

  Ligands

  This will select all atoms in ligand groups. If there are no ligands this menu item should be greyed out.

  Ligand

  Pops up a menu of all the ligand groups that are present in the viewer. Choosing one will select all the atoms in that group.

• Display

  This menu allows the control of whether certain objects are displayed.

  Maps

  Turns on or off all electron density maps.

  Symmetry

  Turns on or off the display of symmetry atoms. As the center of the scene is moved, AstexViewer automatically calculates symmetry equivalents for all structures that have symmetry defined. If there is a map loaded the symmetry is taken from that, if not it is taken from the CRYST1 records of a pdb file.

  Bumps

  If bumps are turned on, any atoms that are selected are annotated with distances to nearby atoms that are within the sum of VDW radii.

  Solvent

  Controls the display of solvent atoms.

• Colour

  By Atom

  Will colour all atoms according to a standard atom based colour scheme.

  By Chain

  Colours atoms according to their chain id.

  By B-factor

  Colours atoms according to a predefined b-factor range. Blue indicates low b-factors, white intermediate, and red high b-factors.

  By B-factor Range

  Colours atoms by mapping their b-factors into a range from red to blue.

  Change to

  Will change all selected atoms to the specified colour. If no atoms are selected all atoms are changed.

  Background

  Will change the background colour to the specified colour.

• View

Reset

Reset the view. The molecules are recentered and the orientation is reset.

Center on Selection

The view is centered on the selected atoms. The atoms may have been selected by choosing a select menu item or by picking them with the mouse.

Clip Maps to Selection

This will clip electron density to selected atoms. This is principally useful for making pictures.

Wide Bonds for Selection

Selected atoms will be drawn with wide bonds. Useful for highlighting a particular part of a structure, such as a ligand.

Contour Levels...

Pops up a set of sliders that can be used to change the contour levels for the displayed maps. The check buttons control whether the contour level is displayed. The colours are hard wired to red, blue and orange at the moment. All map contour levels can be turned off at once by choosing the Display Maps menu item.

• Measure

Nothing

Doesn't measure anything just labels atoms

Distances

Pairs of atoms that are picked get a distance indicator between them.

Angles

Sets of three atoms have the angle in degress indicated.

Clear distances

Removes all distance markers.

Clear angles

Removes all angle markers.

Colours

	black
	white
	red
	green
	blue
	yellow
	cyan
	magenta
	purple
	aquamarine
	orange
	lightgreen
	lightblue
	brown
	grey

Web Page Applets

Alternatively, AstexViewer can be embedded in a web page as a Java Applet. The following lines of HTML should be added to a web page to include AstexViewer as an Applet.

<applet archive="AstexViewer.jar"
        code="MoleculeViewerApplet"
        width="400" height="300">
<param name="molecule" value="1xyz.pdb">
<param name="map" value="fofc.map">
</applet>

This example will read a structure called 1xyz.pdb, and a map called fofc.map from the directory containing the web page. The example also assumes that AstexViewer.jar is in the same directory (it is possible to centralise the location of the jar file by adding a codebase="wherever" tag).

The applet can display more than one structure and map at the same time. Multiple structures or maps are loaded by using molecule tags with sequential ids.

<applet archive="AstexViewer.jar"
        code="MoleculeViewerApplet"
        width="400" height="300">
<param name="molecule1" value="mol1.pdb">
<param name="molecule2" value="mol2.pdb">
<param name="molecule3" value="mol3.pdb">
<param name="map1" value="fofc1.map">
<param name="map2" value="fofc2.map">
<param name="map3" value="fofc3.map">
</applet>

The Applet also supports two other tags, which allow the specification of which atoms to center on, and which to draw in wide bond style. Examples are shown below.

<param name="wide" value="X:1">
<param name="center" value="X:1">

The values of both these tags are simple atom selection expressions. The expressions are of the form [CHAIN:]first_residue[-last_residue]. Some examples are given below.

The following example shows a typical arrangement for displaying a protein ligand complex. The protein is in protein.pdb and the ligand is in ligand.pdb (in residue 1 in chain X). A difference map is in fofc.map.

<applet archive="AstexViewer.jar"
        code="MoleculeViewerApplet"
        width="400" height="300">
<param name="molecule1" value="protein.pdb">
<param name="molecule2" value="ligand.pdb">
<param name="map" value="fofc.map">
<param name="center" value="X:1">
<param name="wide" value="X:1">
</applet>

The applet displays the protein and ligand with the electron density map contoured at 3sigma. The wide and center tags instruct the applet to center on the ligand and display its bonds in wide bond style.

The latest version of AstexViewer supports a script tag that allows arbitrary sets of commands to be included at startup. This is the preferred way of loading molecules and maps in later versions. The scripting language is described in detail in the next section.

When creating Applets pay particular attention to the file locations and permissions. In particular any file that you will download through a webserver will usually need to be world readable. The Java Console will usually give you some clues as to the cause of the problem.

<applet archive="AstexViewer.jar"
        code="MoleculeViewerApplet"
        width="400" height="300">

<param name="script" value="
molecule load molecule1 protein.pdb;
molecule load molecule2 ligand.pdb;
map load map1 fofc.map;
center chain X and residue 1;
display wide chain X and residue 1;
">
</applet>

More Complex Example

Scripting Language

Commands

molecule load name 'file_or_url'

Load the molecule specified by the file or url and give it the specified internal name.

molecule lazy name 'file_or_url'

Load the specified molecule if nothing of that name already exists.

molecule remove name

Remove the specified molecule from AstexViewer.

map load name 'file_or_url'

Load the electron density map and give it the specified internal name.

map name contour contour_number value

Set the contour level for the contour to the specified value.

map name contour contour_number on/off/toggle

Change the display state of the specified contour for the named map.

colour colour_name selection

Change the colour of the atoms specified by selection.

label format selection

Label the specified atoms using the format statement. In this version the format statement is ignored and atoms are labelled with their atom name, residue name and residue number e.g. CA ALA:24.

centre selection

Sets the origin of the viewer to the center of the selected atoms. The width of the view is adjusted to that of the sphere that encloses the selected atoms.

centre x y z

Sets the origin of the viewer to the specified coordinate. The width of the view is not altered.

radius r

Sets the width of the view. This is intended to be used with the center command above.

matrix x00 x01 x02 x03 x10 x11 x12 x13 x20 x21 x22 x23 x30 x31 x32 x33

Sets the transformation matrix to that specified. Note that the center and scale should be set with the center and radius commands above.

select selection

Select the set of atoms specified by selection.

append selection

Select the specified atoms if they are not already selected.

exclude selection

Unselect the specified atoms.

Atom selections

Expression ::=
	    Statement
	| ( Expression )
	| Expression and Expression
	| Expression or Expression
	| not Expression
	| sphere radius around Expression
	| sphere radius around x y z
	| byresidue Expression

id id1 [id2 id3 ...]

Select the atoms that have the specified ids. Atoms from pdb files have the ids that are specified on the atom records. Atoms from .mol files take a sequential id starting from 1 for the first atom.

atom string

Select the atoms whose atom name matches the string.

residue id1 [id2 id3 ...]

The atoms that are in the residues with the specified ids.

name string

The atoms that are in residues with the specified name.

chain string

The atoms that are in the specified aminoacid chain.

molecule string

The atoms that are in the specified molecule.

x/y/z/b/o =/>=/<= number

The atoms that satisfy the condition on their property. x, y and z are the respective atomic coordinates. b is the atomic b-factor for atoms that come from a pdb file (0.0 for atoms from mol files) and o is the occupancy for atoms from pdb files (1.0 for atoms from molfiles).

all

All atoms in all molecules.

none

No atoms at all (useful for resetting selections and such like).

aminoacid

Atoms that are in residues that have one of the 20 standard amino-acid names.

solvent

Atoms that are in residues that have standard solvent names (HOH, WAT, TIP).

dna

Atoms in residues that have one of the standard DNA base names.

ions

Atoms that are ions (Zn, Ca, Mg, Fe etc.).

current

Atoms that are currently selected. They appear with yellow dots in the dsiplay.

labelled

Atoms that currently have a label.

displayed

Atoms that are currently visible.

Examples of atom selections

atom CA				select all C-alpha atoms (and Calciums)
atom CA and aminoacid		select all C-alpha atoms
(atom C or atom CA or atom N) and aminoacid
				select backbone atoms
name GLY			select atoms in all Glycine residues
molecule mol1			select atoms in mol1
molecule m*			select atoms in all molecules whose name
					begins with m
chain A				select atoms in chain A
sphere 5 around residue 100	a 5A sphere of atoms around (and including) residue 100

Once groups of atoms have been selected, they can be operated on in various ways. For instance, they can have their colour changed or their display style modified. The atom selection expressions also form the basis of the surface generation commands described in the next section.

Applet Methods

execute(command_string)

Passes a string of scripting language commands to an AstexViewer applet. The commands are interpreted (no error code is returned). This is the main method for interacting with AstexViewer from a web page by use of JavaScript. This is supported in all recent versions of Internet Explorer and Netscape. The calls to an Applet are usually done via a JavaScript function. The actual function calls are usually made from the OnClick() (and equivalent) actions of a JavaScript control e.g.

function execute(s){
  document.form.execute(s);
}

execute('colour green atom C*;');
execute('molecule display mol1 off;');

fetch(url_string)

This method causes AstexViewer to open the URL specified in the argument. All output is read from the URL and it is returned to JavaScript as a string value. This allows JavaScript to make calls back to a server to obtain information about what to display and other things. AstexViewer may only open URL's on the server that it was downloaded from. This is a restriction imposed by the default Applet security model, and is not a limitation of AstexViewer.

getSelection()

This method returns a list of selected atoms in AstexViewer. The method returns a string that lists all of the atoms selected for each molecule. The ids are appropriate for passing back in a select statement. The return format is illustrated below

mol0,1,2,3,4,5|mol2,3,45|ligand23,34,56

The selections for each molecule are separated by '|' characters. The molecule name is the first part of each subexpression (mol0, mol2 and ligand 23 in the example above) and the remaining ',' separated tokens are the atom ids for each molecule.