
                       README file for Kpax 4.0.0

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

   cd ~
   sh kpax-4.0.0-mint17-x64.bin

This script will make a subfolder called "kpax" and it will add any necessary 
environment variables to your start-up shell script. Normally, you will then 
be able to run the program from the command line by typing the command "kpax" 
(without the quotes).

If you prefer to install the program manually, you should create a kpax directory, 
and then uncompress the distribution files into it. For example, assuming you are 
installing for 64-bit Mint17, use something like:

   sh kpax-4.0.0-mint17-x64.bin --noexec

   mv kpax-dist-4.0.0/kpax-4.0.0-x64.tgz /your-kpax-directory

   cd /your-kpax-directory

   zcat kpax-4.0.0-x64.tgz  | tar xvpf -

You will then need to set some environment variables in your login file. Here are the 
main variables that you will probably need to set:

(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 "kapx/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 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/

