Documentation for the HOLE: 2.0 Introduction & Setup

2.0 Introduction & Setup

2.1 Acquiring, Unpacking and setting up the package

The HOLE suite is now distributed using the web from the HOLE homepage on the web: http://hole.biop.ox.ac.uk/hole follow the instructions there for the download.

Download the compressed tar ball relevant for your system e.g., hole2.2_002_linux.tar.gz and place it in your home directory.

Unpacking this tar ball will create the directory hole2 containing files for your distribution. Use the commands:

cd
tar xzf hole2.2_002_linux.tar.gz

These commands will create the directories:
hole2/exe contains the main executables
hole2/rad contains a the radius set files needed by hole
hole2/examples contains a series of example input files for example runs with hole.
if you have a source code distribution (available by special request see the hole homepage) there will also be a source directory hole2/src.

To run the hole program and the other executables you can just type the full name of the program. To test that the executable works on your computer by typing at the unix prompt:

~/hole2/exe/hole
 *** Program HOLE ***
  
 If results of this run are reported or published, please
 cite the publications listed below.

 (edited for brevity)
  Control variables read:

The hole program should start and wait for input - hit ctrl-d (the control and d keys together) to get out of this or ctrl-c to interupt. If the program fails to load then please goto the hole homepage help section: http://hole.biop.ox.ac.uk/hole/help

It is normally most convenient to add the hole executable directory to the the unix path (this would allow hole to be started by typing "hole"). Suppose user "mary" has set up the package.

If you are a tcsh or csh user add the following line at the end of your ~/.cshrc file
setenv PATH "$PATH":~mary/hole2/exe
or otherwise if you are a bash user add the line that follows to the file that is used to set your ENV. This file is normally called following ~/.bash.profile or ~/.profile or ~/.kshrc
PATH=$PATH:~mary/hole2/exe
(if unsure which shell you are running type echo $SHELL)

Open a new shell (if unsure about this logout and then log back into your terminal). 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).

Unless you have installed hole in your own space you will need to modify the examples provided to point to the correct radius files. 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).

2.2 Brief scientific background to the hole method

The first version of HOLE was written at Birkbeck College from April 1992 to allow the visualization and analysis of the holes through atomic models of ion channels. At the time a number of people have suggested that it may prove to be useful to other scientists working on ion channel models and it was publicly distributed with that hope. This has proved to be true with many hundreds of downloads and literature citations to date. Its initial application was 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. In the original version the user had to supply an initial point in the channel cavity and a vector in the rough direction of the channel, now HOLE has the facility to make guesses for these. 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 molecular graphics plot file. The original version of HOLE directly produced a HYDRA/QUANTA binary 3D plot (.qpt) file. This contained a dot surface showing the locus of the surface of the moving sphere and a line showing the locus for the sphere centre. The file could be displayed together with the ion channel with the program QUANTA. Conversion programs were then developed to convert the qpt objects so they could be displayed with other molecular graphics programs, such as sybyl, rasmol, mage and InsightII. The direct output of molecular graphics object is now phased out of HOLE (see next paragraph).
The sphere centre information is output to a pdb format co-ordinate file (normally given the terminal identifier .sph). This contains an atom record for each centre with the occupancies set to the sphere radii. This file is now used to produce molecular graphics objects rather than directly producing them in HOLE. This has the advantage of allowing the separation of the process allowing the combination of the results of more than one HOLE run and/or This is useful for analysis of the route found using molecular graphics and combining the results of more that one run of HOLE.

The program was originally written on VAX under VMS and was then developed on an ibm rs6000 (under AIX). It has been used on a variety of Unix workstations (convex, SGI, HPI, OSF1) it now primarily supported on linux.

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

Follow (local) link to see article.

2.4 New features for release 2.0

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.