This file contains detailed instructions for compiling and running
FEATURE metal scans.

To compile:

./configure
make

This will create executables in the feature directory. You may leave them
there or move them to any other location.

Preparing to run FEATURE
-------------------------
FEATURE depends on several environment variables. The FEATURE_DIR
variable tells FEATURE where to look for the files
feature/residue_templates.dat and feature/amberM2_params.dat. To set
this environment variable in bash, use this syntax:

export FEATURE_DIR=/directory/feature

where "directory" should be replaced with the full path to the
directory in which the files will be stored (by default, the "feature"
subdirectory of the installation directory).

FEATURE will always find PDB files located in the directory from which
it was run. However, if you have a local database of PDB files, you
can also set the PDB_DIR environment variable. This will allow you to
specify PDB files using only the PDB identifier. FEATURE understands a
variety of file naming conventions.

For each PDB file, you will also need a DSSP file. If it is located
in the directory from which FEATURE is run, it will be found
automatically. Otherwise, you may set up the DSSP_DIR environment
variable in the same manner as the PDB_DIR variable.

To make these variables persist across sessions, put them in your
~/.bash_profile file.


Detecting metal binding sites using FEATURE
------------------------------------------
1) First, run feature/getPotentialBindingSites to identify potential
binding sites based on the presence of at least a partial first
coordination shell:

./feature/getPotentialBindingSites -p <pdb file name> -c feature/coordinating-atoms.zinc.txt -o output.pts

In this case, the PDB file name must be a complete path to a PDB
file. Your PDB_DIR environment variable will be ignored by this
code. The file feature/coordinating-atoms.zinc.txt specifies expected
coordination environments for zinc. If you wish, it can be
modified. Points to be scanned by FEATURE will be written to
output.pts. All three arguments are required.

2) Convert the points used in step 1 to FEATURE vectors:

First, you must create a DSSP file for your PDB file. DSSP may be
downloaded from http://swift.cmbi.ru.nl/gv/dssp/.

dssp filename.ent > filename.dssp

Then, run featurize:

./feature/featurize -P output.pts > output.pts.ff

3) Score the FEATURE vectors:

./feature/scoreit -a models/zinc.model output.pts.ff >
output.zinc.hits

The output file will have one line for each FEATURE vector. The tab
delimited fields are as follows:

- Unique identifier
- Score
- x coordinate
- y coordinate
- z coordinate
- comment (may be safely ignored)

4) Optionally, run the zinc vs. calcium model.

The zinc model may give high scores to other metals. To improve
discrimination between zinc and the alkaline earth metals, you may
also want to score your FEATURE vectors using the zinc vs. calcium
model (which was built using calcium binding sites as negative
training examples). Note that this may decrease your sensitivity with
respect to zinc somewhat.

./feature/scoreit -a models/zinc_vs_calcium.model output.pts.ff >
output.zinc_vs_calcium.hits

5) Analyze your results.

We provide several score cutoffs derived from a specificity analysis
of an independent data set of zinc binding proteins. The score cutoffs
for several specificity thresholds are given in
SCORE_CUTOFFS.txt. Since a protein may contain tens of thousands of
negative points, we recommend the most stringent score cutoff (99.8%
specificity).

If you have chosen to run the zinc vs. calcium model, we recommend
a score cutoff of 20.7 (corresponding to a z score of 2.0). For all
points in output.zinc.hits, accept the hit only if it surpasses both
your chosen cutoff for the zinc model and scored at least 20.7 against
the zinc vs. calcium model. Points are listed in the same order in
both output.zinc.hits and output.zinc_vs_calcium.hits, and can also be
uniquely identified by the identifier in the first column of each
file.

6) View your hits.

You may view your hits in Pymol using the feature/viewhits.py script:

./feature/viewhits.py -i output.zinc.hits -s 16.83 

This will produce a script named "view.py" that can be run from within
Pymol to produce red spheres at the location of each hit that
surpasses the score cutoff given by the "-s" option (set to the 99.8%
specificity score threshold in the example above). Type
"./feature/viewhits.py -h" to see additional options.

Note that this script will not automatically consider the scores for
the zinc vs. calcium model. You may wish to produced a new hits file
containing only those points in which you are interested before
running viewhits.py