README file for Kpax 5.0.6

Kpax is a fast protein structure aligner. Currently, it only works on Linux systems.
To install Kpax, you will need to download and extract the tar file using something 
like this:

   cd ~
   tar xvf kpax-5.0.6-x64.tgz

This will make and populate a folder called "kpax" that contains five sub-folders:

   bin  build   doc  test   kpax_database

The executable is "kpax/bin/kpax5.0.6.x64", but it is better to set some environment 
variables in your login file in order to run kpax more easily from the command line:

(for csh users, edit ~/.cshrc file)

   setenv KPAX_ROOT      /your-login-or-top-level-folder/kpax 

   setenv PATH           ${PATH}:${KPAX_ROOT}/bin

(for bash users, edit ~/.bashrc)

   export KPAX_ROOT=/home/dritchie/kpax       <-  substitute the proper pathname here.

   export PATH=${PATH}:${KPAX_ROOT}/bin

Here are two further environment variables you might wish to set

   KPAX_DATABASE=/the-directory-where-you-keep-your-databases/

   KPAX_RESULTS="./kpax_results/"

The program is launched from a script called "kpax" in the "kpax/bin" directory.
If your PATH is correct, you should be able to test it using something like:

   cd kpax/test
   
   kpax d1bhga1.ent d1cs6a3.ent

This will treat d1bhga1.ent as the "query" structure and d1cs6a3.ent as the
"database", and it will superpose the database structure onto the query.

Because Kpax can generate many output files, especially when searching a database,
it normally writes its output to a sub-directory called "./kpax_results/". In fact,
it makes a new sub-sub-folder for each query, so in this case you will get a
folder called "kpax/test/kpax_results/d1bhga1":

   ls -1 kpax/test/kpax_results/d1bhga1

   d1bhga1_query.pdb             <- the query PDB structure
   d1cs6a3_d1bhga1.pdb           <- the database structure superposed onto the query

   d1bhga1.khits                 <- files showing the scores in various formats
   d1bhga1.ktops
   d1bhga1.kcath
   d1bhga1.knames
   d1bhga1.krank
   d1bhga1.kroc

   d1cs6a3_d1bhga1.fasta         <- files showing the alignment in various formats
   d1cs6a3_d1bhga1.kpax
   d1cs6a3_d1bhga1.kalign
   d1cs6a3_d1bhga1.kprof
   d1cs6a3_d1bhga1.profit
   d1cs6a3_d1bhga1.wpairs

   d1cs6a3_d1bhga1.jmol          <- scripts to draw the superposition in jmol
   d1cs6a3_d1bhga1_matches.mac   <- for Hex
   d1cs6a3_d1bhga1_aligned.mac
   d1cs6a3_d1bhga1_segments.mac  
   d1cs6a3_d1bhga1_matches.tcl   <- for VMD
   d1cs6a3_d1bhga1_aligned.tcl
   d1cs6a3_d1bhga1_segments.tcl

By default, Kpax will produce many output files. To suppress all output files, use
the -nowrite option. You can then explicitly enable specific outputs by keyword.
For example, 

   kpax -nowrite -pdb -kalign -hex -fasta d1bhga1.ent d1cs6a3.ent

Except for the -nowrite option, which suppresses all output from the default settings
or from any previous keywords, you can put keywords and file names in any order.

If you put multiple PDB files on the command line, Kpax will treat the first one as
the query, and all the rest as the database structues. You will then get a bunch
of alignment files and the scores files will contain multiple entries...

If you want to calculate one multiple alignment of a list of PDB files, instead of
a series of pair-wise alignments, add the "-multi" option. If you want to calculate
a flexible alignment, and the "-flex" option. For a multiple flexible alignment with
an automatically selected rigid pivot structure, add both "-multi" and "-flex".

If you really do not want Kpax to make sub-directories, use:

   kpax -nosubdirs d1bhga1.ent d1cs6a3.ent

This will put all the results files directly in to "./kpax_results/". If you really 
do not want a results sub-folder, set the KPAX_RESULTS variable:

    KPAX_RESULTS=/tmp/junk

or

   KPAX_RESULTS="."

If you are searching a structure against a CATH or SCOP database, then you will 
almost certainly want to use a results folder :-) 

   kpax -db=cath d1bhga1.ent

Please see the example scripts "kpax/bin/build_cath" and "kpax/bin/build_scop" 
for examples of how to build a CATH or SCOP database. 

For more options, please use

   kpax -help


Happy kpax-ing!


Dave Ritchie 
INRIA Nancy Grand Est
Nancy, France

email:     Dave.Ritchie AT inria.fr (please make your own AT sign)
web:       http://www.loria.fr/~ritchied/
Kpax:      http://kpax.loria.fr/