Documentation for the HOLE: 2.0 Introduction & Setup

Navigation:

Back to contents

On to next section 3.0 Control of HOLE

To subsection 2.3 New features for release beta 2.0

To subsection 2.4 Acquiring the package

To subsection 2.5 Setting up the package

2.0 Introduction & Setup

2.1 Brief scientific background to the hole method

this sub-section needs updating ***

HOLE was written at Birkbeck College from April 1992 to allow the visualization and analysis of the holes through atomic models of ion channels. A number of people have suggested that it may prove to be useful to other scientists working on ion channel models and it is being publicly distributed with that hope. Its initial application is to four experimentally determined structures of gramicidin A, as described in Smart, Goodfellow and Wallace (1993). Please refer to that work for a detailed description of the method and discussion as to the results. This manual will concentrate on operational matters.

The user must supply a file containing the co-ordinates for the ion channel structure to be analyzed - in pdb format. Atom records are read and the van der Waals radius of each atom is set up (see section 5.0). The user supplies an initial point in the channel cavity and a vector in the rough direction of the channel. HOLE then proceeds to move the point on the plane normal to the channel vector so as to find the largest sphere which can be accommodated without overlap with the van der Waals surface of any atom. The optimization is achieved by a Monte Carlo simulated annealing procedure. This method was initially chosen to avoid becoming trapped in local "minima" but has subsequently proved to be useful in follow alternative routes through channels with a complex internal cavity, such as annexin V (Smart, Wallace and Goodfellow, 1993). Once the largest sphere which can be accommodated on a particular plane is found a small displacement is taken in the direction of the channel vector and the process is repeated for the next plane. The net result of the routines is a series of sphere positions that can be thought of a flexible sphere "squeezing" through the ion channel.

Output from the procedure is in three forms:

Numerical information as to the radius found is given vs distance along the channel is written to the text output file. This can be input into a graph plotting program.
Graphical output is produced and output to a HYDRA/QUANTA binary 3D plot file. This contains a dot surface showing the locus of the surface of the moving sphere and a line showing the locus for the sphere centre. Also available is an option which draws a line from the two atoms closest to each sphere surface to that surface. This is intended to be useful in analyzing which atoms cause constrictions in the pore. The file can be displayed together with the ion channel with the program QUANTA. It can also converted into a format suitable for display using InsightII - see section 7.6.
The sphere centre information can be output to a pdb format co- ordinate file. This contains an atom record for each centre with the occupancies set to the sphere radii and B-factors giving the distance along the channel. This is useful for analysis of the route found using molecular graphics and combining the results of more that one run of HOLE, see section 7.5.

The program is written in reasonably standard FORTRAN 77. An exception to this is the use of machine specific random number generation routines. The original pre-release program improved the poor nature of the vendor supplied random numbers by using s/r RANO supplied in Numerical Recipes (1st ed., Press, Flannery, Teukolsky and Vetterling, CUP, 1986). This has been eliminated from the released version to avoid problems of property rights. I don't think this should matter as the method does not need very good random numbers - correlations should be of little consequence. The program was originally written on VAX under VMS and was then developed on an ibm rs6000 (under AIX). It is supplied in versions suitable for Silicon Graphics, Hewlett Packard and ibm rs6000 machines - it shouldn't be too difficult to adapt these for use on other machines.

2.2 Copy of J. Mol. Graphics article giving overview of HOLE

Follow (local) link to see article.

2.3 New features for release 2

HOLE2 has a large number of new features which should both ease the use of program and allow exploration of ion channel properties in further depth. Most notably:

(Release 2.002) 2D Maps of the internal surface of a pore: This feature is now documented and the use of the public domain program gnuplot is supported.
Speed: You should notice that the new version of HOLE runs about 30% faster as the calculation of unnecessary square root calculations have been eliminated.
Text output flushing.: By default HOLE reads from the standard input (keyboard) and writes to the standard output. For obvious reasons it is normal to redirect input and output to files (using the < and >) keys. One annoying consequence of this on Silicon Graphics and Hewlett Packard's machines is that the text output arrives in "bursts" (caused by buffering the output). This release of HOLE gets around this problem by flushing the output periodically. Unfortunately there is no machine independent way of doing this so some work may be needed to get this to work for non-supported machines.
Reduced text output option.: SHORTO
Analysis of anisotropy: CAPSULE
Prediction of K+ conductance
Better graphics
Colour coding surfaces
Better support for non-QUANTA users: With conversions programs added for O, mage, rasmol and VRML.
Easy analysis of multiple files e.g., from Molecular Dynamics trajectories.: Instead of HOLE being limited to the analysis of one input coordinate file it is now easy to apply HOLE to many input coordinate sets. This is achieved by specifying a wildcard (*) in the file name specified after the COORD card, e.g., coord ab*.pdb will apply hole to all files in the directory whose name starts with ab and ends with .pdb. The hole procedure will be applied to each file in turn with the same setup conditions (initial point, sampling distance etc.).
As well as being able to read from multiple pdb files HOLE can now read from CHARMm .DCD format binary trajectory files. Details of this option can be found by looking at the CHARMD and CHARMS cards.
Program qplot is now much easier to use and produces shorter postscipt files.: qplot allows the user to produce high quality colour or monochrome postscript files of HOLE objects. In the original release the program was difficult to use. The program is now much more user friendly and has sensible defaults. For instance you can produce pictures with views along the x or y axis very much more easily.

2.4 Acquiring the package

The normal method of distributing hole is via anonymous ftp. Please note that to unpack the files you must have a password - to get this fill in the request form (and it will be e-mailed to you). The normal process of distribution and setting up requires:

You have a unix machine working ftp.
The machine has the crypt program (this maybe not be available to certain counties).
You have a working FORTRAN complier - if not see this page.

If you do not meet 1 or 2 then let me know by email to o.smart@mail.cryst.bbk.ac.uk or sending a fax). However, please note that I have no current intention of porting HOLE onto low performance machines (pc's and mac's) - although this should not be that difficult to achieve. You can look at HOLE's results on a pc or mac by using mage or rasmol.

I strongly suggest that you keep the all the files associated with hole in a separate directory /hole2 from your login directory. Type the commands mkdir ~/hole2 and cd ~/hole2.
Establish ftp access to the Birmingham Biochemistry ftp server by typing ftp windy.bip.bham.ac.uk
Use the username anonymous and your email address as a password.
Once you have established access type the ftp command: bin to make sure that files are transfered as binary.
At the ftp prompt type: cd pub/hole2
Then type the ftp command: get hole.tar.Z.crypt
Leave ftp by entering the command bye
You should now have the file hole.tar.Z.crypt in the directory ~/hole2.
The file is encrypted. To return it to its former glory type the command crypt < hole.tar.Z.crypt > hole.tar.Z. You will be prompted Enter key: enter the key that has been sent to you by e-mail.
hole.tar.Z is a compressed tar file. First uncompress it by typing the command uncompress hole.tar.Z.
Unpack the .tar file by typing the command tar xvf hole.tar. You should see a list of the files created appear on the screen.
For the lazy then you should be apply to perform the above steps by copying the following steps with your mouse and pasting them to the unix command line.
```
mkdir ~/hole2
cd    ~/hole2
ftp windy.bip.bham.ac.uk
```
At the ftp prompt do another mouse paste of the following lines:
```
anonymous
hole2_user
bin
cd pub/hole2 
get hole.tar.Z.crypt 
bye
crypt < hole.tar.Z.crypt > hole.tar.Z
```
Now enter the encryption key which has been sent to you by e-mail.
```
uncompress hole.tar.Z
tar xvf hole.tar
setup
```
You should now have all the files needed to set up/run hole:
- Directory ~/hole2/doc contains the documentation
- Directory ~/hole2/rad contains van der Waals radii files (*.rad).
- Directory ~/hole2/f77 contains the FORTRAN source files (*.f) and script files needed to compile and link them (*.com).
- Directory ~/hole/example contains an example application of hole and ancillary programs.
- Directory ~/hole2/work is intended as a suitable placed to perform HOLE calculations from. It contains an input file which can be used to perform a HOLE calculation which should give the same result as that in the example directory.

2.5 Setting up the package

As the programs comprising hole and ancillary programs are written in FORTRAN you must have access to a fortran compiler/run time libraries - please talk to your system people if you do not. In this section it is assumed you are setting up the package on a reasonably standard unix machine, have followed the steps set out in section 2.2 and that your fortran compiler is run by the command "f77". If you do not have a fortran compiler then look at this page

Change default to the new directory - cd ~/hole2
Start the setup script by typing setup.
Then answer the scripts questions.
Ignore warnings on the ar command on Silicon Graphics.

The script file can automatically add the lines:

# next line added to ~/.cshrc by HOLE setup script
setenv PATH "$PATH":~/hole2/exe

to your ~/.cshrc file. This should enable you to run the HOLE exectables by typing the command name at your normal unix prompt. Test this by:

opening a new shell (or typing csh at your existing prompt.
then typing qpt_conv.
A program should then fire up. If this does not happen:
- try to sort it out yourself.
- ask your systems manager.
- or failing these, get in contact with me.

If your are in the minority of sensible korn shell users then add the following line to the file you have set your ENV to (normally ~/.kshrc):

# hole2 exe's
PATH=$PATH:~/hole2/exe

Using the package if someone has already set it up on your system.

If this is the case then please use these instructions to use the program from their space, rather than setting it up a fresh.
Suppose user "mary" has set up the package. Added the following line at the end of your ~/.cshrc file (assuming you are a csh or tcsh user):
```
setenv PATH "$PATH":~mary/hole2/exe
```
Open a new shell (type csh). You should be able to run the hole executables by typing the command name - try it out by typing hole if nothing happens then make sure that you have permission to use the executables by typing "ls -l ~mary/hole2/exe". If you cannot see this directory then go and speak to mary who should change the permissions for all the top hole2 directory (get her to type chmod a+rx ~/hole2).
In order to be able to use the "hole_help" facility you must get mary to edit the script ~mary/hole2/exe/hole_help and include the word "mary" after the ~.
In case of problems (a) go ask an experienced unix bod (b) e-mail me.
When specifying a file for vdw radii (using a RADIUS card) you can use files in mary's area e.g., specify the following line in the control file:
radius ~mary/hole2/rad/simple.rad
(HOLE now resolves ~'s for user names).