                    BIOMOLECULAR MODELLING LABORATORY
                      IMPERICAL CANCER RESEARCH FUND
                      ______________________________
                 Head of Laboratory: Dr M.J.E. Sternberg

 
                      MOLECULAR GRAPHICS PROGRAMS
                      ___________________________
                      ___________________________
                       Suhail A Islam - Dec 1996

THE PROGRAMS ARE THE PROPERTY OF IMPERIAL CANCER RESEARCH FUND (ICRF).
THEY CONTAIN COPYRIGHT WORKS. UNAUTHORISED USE, COPYING OR DISCLOSURE
IS UNLAWFUL.    IF YOU HAVE OBTAINED ACCESS TO THESE PROGRAMS WITHOUT
AUTHORISATION  IN WRITING  BY  IMPERIAL  CANCER  RESEARCH  TECHNOLOGY,
(ICRT) THE  LICENSING AGENT OF ICRF, ICRF RESERVES  THE RIGHT TO BRING
PROCEEDINGS AGAINST YOU BASED ON COPYRIGHT INFRINGMENT OR OTHER CAUSES
OF ACTION.

                         CONTENTS OF THIS FILE
                         _____________________
               [I]  BRIEF DESCRIPTION OF DIRECTORY CONTENTS
 	      [II]  STEPS FOR OBTAINING THE PREPI SUITE
             [III]  WHERE TO FIND THE PREPI SUITE
	      [IV]  DOWNLOADING THE CORRECT VERSION FOR YOUR MACHINE
	       [V]  HOW TO DOWNLOAD PROGRAMS
	      [VI]  ENTERING YOUR LICENSE CODE
             [VII]  ENVIRONMENT VARIABLE DEFINTION PRIOR TO RUNNING PROGRAM
	    [VIII]  HOW TO RUN PROGRAMS - A QUICK START
			(a) PREPI PERFORMANCE VS QUALITY ON SG MACHINES
			(b) EXAMPLES OF USING PREPI
			(c) EXAMPLES OF USING PREPIPS
	      [IX]  SLIDE MAKING/PRINTING FROM PREPI
	       [X]  PREPI WEB PAGE DETAILS
              [XI]  CONTACT ADDRESS FOR FURTHER INFORMATION AND WWW SITE


             [I] BRIEF DESCRIPTION OF DIRECTORY CONTENTS
              ___________________________________________

(1) PREPIVx.x_y.TAR.Z
	Compressed Tar file of Molecular graphics program PREPI &
	associated files (PREPI is an acronym for Protein REPresentations
	Interactively). This program runs on a SILICON GRAPHICS
	workstation. Taking atomic coordinates as input PREPI can EASILY
	produce many different types of molecular representations as well
	as provide quantative information. Some of the important structural
	display features of the program are: 

	a)	Liquorice and Ball & Stick display of bonds
	b)	Ribbons: Standard (Richardson) & Cylinderical
	c)	Cylinders & Arrows  (to represent Helices and Sheets)
	d)	Spheres (to represent atoms)
	e)	Hydrogen Bonds & Disulphide bonds representations
	f)	Inertial (and Thermal) Ellipsoids
	g)	Planes: Least Squares & 2D sections through molecule
        h)      Planes: Disk Representations of ring structures
                (e.g. Heme, Tyrosine, Guanine)
        i)      DNA representations (ladders)
        j)      Molecular Surfaces
        k)      Geometrical calculations (distances & angles including
                between secondary structural elements in proteins, helix
                pitch)
        l)      Plots eg Phi-Psi
        m)      Various NMR representations
        n)      PostScript files of cartoons eg ribbons, arrows & cylinders
                (by use of the standalone program PREPIPS)
        o)      Least squares surface fitting (Lines, Planes, Conics,
                Quadrics and Cubics)
Additional features include:
	a)	Interactive change of colours & material properties
	b)	Use of up to 6 Lights of varying colours
	c)	Control of background colours
	d)	Captions (Text, Arrows & Lines)
	e)	Interactive image capture
	f)	Non-graphical functions such as torsion angle calculations,
		hydrogen atom generation and data filtering.
Some features under development
	a)	Ray-Tracing
	b)	Crystal Packing


(2) SGIUTILITES_y.TAR.Z
    	Compressed Tar file containing standard Silicon Graphics
	programs which are useful e.g. image file format conversions
	such as topict (convert SGI format to Macintosh PICT),
	togiff (convert SGI format to GIFF) & tops (convert SGI format
	to Encapsulated PostScript). THESE ARE STANDARD SG PROGRAM
	WHICH SHOULD ALREADY BE ON YOUR SYSTEM, but are provided here
	for convenience if they have not been loaded onto your system.



		[ II] STEPS FOR OBTAINING THE PREPI SUITE
		_________________________________________

1) You should sign and return COMPUTER PROGRAM RELEASE FORM (Copyright
   agrement form). Obtain this via our WWW site (see SECTION X below)
2) You should obtain the programs via anonymous ftp as instructed below.
3) A password (to access the programs will be issued), which you should
   type in as instructed below.
4) You will be regularily informed of updates, changes etc. Please make
   sure that if there is a change in your email address that you inform
   us.


		[III] WHERE TO FIND THE PREPI SUITE
		___________________________________
	
Site address:   ftp.icnet.uk  [ip address 143.65.1.15]
Login name:     ftp
Password:       your email
Directory:      pub/bmm/graphics



	[ IV] DOWNLOADING THE CORRECT VERSION FOR YOUR MACHINE
        ______________________________________________________
                
You must first note the correct version of the software for your
machine & operating system. PREPI, AT PRESENT, WILL ONLY WORK ON
A SILICON GRAPHICS WORKSTATION (SG) under Irix 4 or 5 (note that
this software is being ported to OpenGL for future portibility to
other platforms). PREPIPS is available for both the SUN & SG (a
verison for the Macintosh is under development). The file names
in this directory comprise of the program name, version number & 
indicates the platform. e.g. PREPIV1.0_IRIX5.2.TAR.Z indicates
PREPI version 1.0 running under Irix 5.2. YOU SHOULD GENERALLY
OBTAIN THE LATEST VERSION.



                 [  V] HOW TO DOWNLOAD PROGRAMS
                 ______________________________

This procedure will result in the creation of a directory eg PREPIV1.0
containing the programs. The space requirements for the PREPI SUITE are
modest (approx 5-10MB) depending on the programs/images that you obtain.
We will assume that you have created a directory /usr/people/icrf. Ftp
over the appropriate version USING BINARY MODE e.g

	% pwd
	/usr/people/icrf
	% ftp ftp.icnet.uk
	  Name: ftp
          Password: your email address
          ...
          ...
	ftp > bin
	ftp > cd pub/bmm/graphics
	ftp > ls -l
			
	ftp > get PREPIV0.9_IRIX5.2.TAR.Z	(if you have Irix 5.2 or above)
		or
	ftp > get PREPIV0.9_IRIX6.2.TAR.Z	(if you have Irix 6.2)

	ftp > get SGIUTILITIES.TAR.Z		(optional)
	ftp > get PrepiTrace-1.tar.Z		(optional)
	ftp > get PrepiTrace-2.tar.Z		(optional)
	ftp > quit

Then on your own system

	% uncompress PREPIV0.9_IRIX5.2.TAR.Z
	% tar xvf PREPIV0.9_IRIX5.2.TAR

This will create a directory, e.g., PREPIV0.9. You should type "pwd"
to find the exact path of the extracted PREPI directory. The main programs
in the PREPIV0.9 directory are called PREPI and PREPIPS. 

The Irix 5.2 binaries should run under Irix 6.x. However we have recently
recompiled the programs on Irix 6.2 and these can be obtain from
PREPI_BIN_IRIX6.2.TAR.Z.



	         [ VI] ENTERING YOUR LICENSE CODE
	         ________________________________

Once you have returned the COMPUTER PROGRAM RELEASE FORM you will be sent
a LICENSE CODE. You must insert this code into the file PREPIAUTH.DAT.
You can do this using any editor (eg vi , jot). Enter the code exactly
as given. The code must start at the first space of the first line in
the file PREPIAUTH.DAT.



	[ VII] ENVIRONMENT VARIABLE DEFINTION PRIOR TO RUNNING PROGRAM
	______________________________________________________________

Lets assume that the full path of the PREPI directory is :

	/usr/people/icrf/PREPIV0.9

You should define the environment variable PREPIDIR eg

	% setenv PREPIDIR /usr/people/icrf/PREPIV0.9

Although PREPI can work without this definition it is important to
define it as latter versions of PREPI will make extensive use of
Data Libraries and also access the License Agreement File.
It is also useful to define aliases (or add the PREPI directory to
your path) eg

	alias prepi  '$PREPIDIR/PREPI'
	alias prepis '$PREPIDIR/PREPI -small -line'

The prepis alias starts the program in line  mode on a small
screen area which is more convenient for low-end SG machines
(do "prepi help" for a full list of startup functions).



           [VIII]  HOW TO RUN PROGRAMS - A QUICK START
           ___________________________________________

You will find full instructions in file *.DOC in each directory. All
programs are very easy to use and only require an input file (PREPIPS
also requires an output file to be specified on the command line).
Please read ALL COPYRIGHT NOTICES before proceeding further.


(a) PREPI PERFORMANCE VS QUALITY ON SG MACHINES
_______________________________________________

The speed and smoothness of manipulations (eg rotations, scaling) will
obviously  depend on the  number of  vectors/polygons  being displayed.
PREPI can display objects such as bonds as Lighted Solid Polygons. 
For LARGE structures, display manipulation can be a little slow on LOW
END SGI systems such as the INDY. Therefore PREPI also allows the
option of displaying bonds as vectors (i.e. simple LINES).  To improve
performance of manipulation on  LOW END SG's  you can do the following
within the program:
	 (i) Turn off menu (item "MENU OFF" in main menu)
             Press RIGHT MOUSE BUTTON to turn MENU back on
	(ii) Turn off complex lighted objects such as SPHERES,
	     & COIL, manipulate and turn objects back on
       (iii) For general manipulations display bonds as LINES by:
	     a) Press F1 (no depth-cue) or F2 (lines with depth-cue)
	     b) Alternatively you can select the "LINES" option
	        under individual menu items eg "C-ALPHA" (under
	        TOP-BAR menu item "OBJECTS"
These items can be EASILY TOGGLED ON & OFF within the program. Therefore
you can produce complex and smooth objects for a Photograph but turn
these items off when adjusting for a better view or adjusting position
of TEXT & CAPTIONS.

(b) EXAMPLES OF USING PREPI
___________________________

Some example coordinate files have been included. you should run
through these examples.    NOTE THAT MOST COMMAND LINE FUNCTIONS
(E.G.  DATA SELECTION,  CHANGE IN DISPLAYABLE AREA)  GIVEN BELOW
ARE FOR CONVENIENCE ONLY AND THESE FUNCTIONS CAN ALSO BE EXECUTED
WITHIN THE PROGRAM, ONCE STARTED. 

a) Try the help command first:

	% prepi help

There are many useful nographical functions as well as a list of
short cut function keys in the program. Some PREPI menu items
may be marked "DEBUG". This means that the functionality is
incomplete at present, but the options still serve a useful purpose.

There is a subdirectory "data-prepi" which contains a few coordinate
and log files. It also contains a README.


YOU SHOULD RUN SOME OF THE EXAMPLES IN THIS DIECTORY data-prepi
TO SEE THE RANGE OF PREPI CAPABILITIES. LOOK AT THE README FILE
IN DIRECTORY "data-prepi".


b) Minimal startup example:

	% prepi -p example.pdb     [-p = a PDB format file]
	% prepi -fre phage.fre     [-fre = prepi free format object language]

c) Using previously saved log files:

	% prepi -d 3cro.log
	% prepi -d example.log
	% prepi -d polygon.log
	% prepi -d 1tfi.log

d) Examples making use of commands lines

   (i)	TYPICAL START

	% prepi -p pdb4hhb.ent -small -line
		Initial dislay should be SMALL & in LINE MODE.
		Drawing in LINE MODE makes manipulations faster.
	% prepi -csd example.csd -small -line
		Read a Cambridge Databank format file.
	% prepi -fre p52-st.fre
		Read Prepi's free format. This will allow users
		to virtually display anything as this polyhedra
		demonstrates. In menu select SIDE-CHAINS and PLANES

   (ii)	EXAMPLES OF DATA SELECTION

	% prepi -p pdb4hhb.ent -chainAB -small -line
		Only read data for chains A & B.
	% prepi -p pdb2crd.ent -chain# 1 to 3 7 -small -line
		Only read data for chains number 1,2,3 & 7. Cannot
		use chain Id's for selection as it is a NMR
		structure & and all chain Id's are same.
	% prepi -nographics -p pdb4hhb.ent -chainA -calpha -o 4hhbA.pdb
		Read pdb file & write out chain A only into file 4hhbA.pdb.
		The program exist after processing data i.e. no graphics
	% prepi -nographics -p pdb1tfi.ent -nohyd -o 1tfinohyd.pdb
		Read pdb file & write out NON-HYDROGEN data to file 1tfinohyd.pdb

 (iii)	EXAMPLES OF GENERATING DATA

	% prepi -tor -p pdb1ppt.pdb -o output-file
	  Generate torsion angles. If no output file is provided then
	  program defaults to screen
	% prepi -genhyd -p pdb1ppt.pdb -o output.pdb
	  Generate hydrogen atoms and write results to output.pdb
	% prepi -cell2pdb 100.0 150.0 100.0 90 95.5 90 -o output-file
	  Generates PDB format CRYST1, SCALE & ORIGX records
	  given cell onstants i.e. a,b,c,alpha,beta & gamma.
	% prepi -genside -p example.pdb -o output.pdb
	  Read main chain atom coordinates from a PDB file &
	  generate side chain atoms in extended conformation.


(c) EXAMPLES OF USING PREPIPS
_____________________________

	% PREPIPS  input_ascii_file  output_postscript_file

The directory contains example input files (*.inp), eg

	% PREPIPS  5pti.inp  5pti.ps

View the output file using xpsview (on SG) eg

	% xpsview  5pti.ps



          [IX] SLIDE MAKING/PRINTING FROM PREPI
          _____________________________________

There are 3 methods to produce an image (we normally use Method (1) for
producing images for slides & publications). Please also see the 
documentation in files
	(a) doc-01-basics.doc  - 2.6 IMAGE FILES - MAKING SLIDES & PRINTING
	(b) doc-x-display-quality.doc 
	(c) doc-x-MakingSlidesImages.doc
 

(1) DIRECT SCREEN CAPTURE INTO AN IMAGE FILE
    The program can capture the display screen into an RGB file.
    Either full screen or user defined area.
    * To save the entire PREPI window as an image file (without the main
      menu), PRESS the F12 KEY. This option will ask for an output file name
      (e.g. protein.rgb - to view this saved image use ipaste or xv)
    * For more options and user selected areas select the menu item
         DATA (top left in main PREPI window) -> SAVE SCREEN
    We use this to make slides (via convertion to Mac PICT). If you
    wish to convert RGB files to PICT format (Macintosh), please
    remember
    (a) if transfering to your Mac via ftp use the BINARY mode
    (b) PICT files created on the SG do not have a PICT
        header, therefore this must be added using eg ChangeMaker,
        FileTyper once the files are on the Mac.
(2) CREATES AN INPUT FILE FOR THE POSTSCRIPT PROGRAM PREPIPS
    This is still being developed and DOES NOT have all functions
    of PREPI eg surfaces. It is however, good enough (i.e. publication quality)
    for standard protein cartoons. PREPI tries to create an input file
    for PREPIPS on an WYSIWYG (What you See is What you Get) principle.
    Therefore you should only display objects that you wish to view
    (you can of course edit the input file once it has been created).
    The steps involved are:
    (a) DATA (top left in main PREPI window) -> CREATE POSTSCRIPT INPUT FILE
            You will be given a number of options (e.g. black & white,
            depth-cue) and asked to give an output file name (e.g. protein.inp)
    (b) Run the postscript program PREPIPS e.g.
	    % PREPIPS  protein.inp  protein.ps
    (c) View & print (always view file before printing) e.g.
	    % xpsview protein.ps 
(3) CREATES AN INPUT FILE FOR THE RAYTRACER PROGRAM PREPIRAY
    This is NOT AVAILABLE AS yet. This really will create photorealistic
    quality output, with shadows, reflections, refractions. You will also
    be able to use cool textures such as wood, marble.



          [X] PREPI WEB PAGE DETAILS
          ___________________________________________


The PREPI software details are at

	http://www.icnet.uk/bmm/people/suhail/prepi.html

The COPYRIGHT AGREEMENT form can be obtained from

	http://www.icnet.uk/bmm/people/suhail/copyright-form.txt

You should also browse through our general software page at

	http://www.icnet.uk/bmm/software.html



         [XI] CONTACT ADDRESS FOR FURTHER INFORMATION
          ___________________________________________

Please send comments & enquiries to

	Dr. Suhail A Islam
	Biomolecular Modelling Laboratory
	Imperial Cancer Research Fund
	44 Lincoln's Inn Fields , London WC2A 3PX, U.K.
	Tel:   +44 (0)171 269 3380
	Fax:   +44 (0)171 269 3479
	email: islam@icrf.icnet.uk
	www:   http://www.icnet.uk/bmm/
