Author: Laszlo Kajan <lkajan@rostlab.org>
Description: man page for concavity
Forwarded: http://lists.alioth.debian.org/pipermail/debian-med-packaging/2012-October/017343.html
--- /dev/null
+++ b/concavity.1.pod
@@ -0,0 +1,195 @@
+=pod
+
+=head1 NAME
+
+concavity - predictor of protein ligand binding sites from structure and conservation
+
+=head1 SYNOPSIS
+
+concavity [options] PDBFILE OUTPUT_NAME
+
+=head1 DESCRIPTION
+
+ConCavity predicts protein ligand binding sites by combining evolutionary
+sequence conservation and 3D structure.
+
+ConCavity takes as input a PDB format protein structure B<PDBFILE> and optionally
+files that characterize the evolutionary sequence conservation of the chains
+in the structure file.
+
+The following result files are produced by default:
+
+=over
+
+=item * Residue ligand binding predictions for each chain (*.scores).
+
+=item * Residue ligand binding predictions in a PDB format file (residue scores placed in the temp. factor field, *_residue.pdb).
+
+=item * Pocket prediction locations in a DX format file (*.dx).
+
+=item * PyMOL script to visualize the predictions (*.pml).
+
+=back
+
+To visualize the predictions in PyMol (it if is installed on your
+system), load the script by typing "pymol 1G6C_test1.pml" at the
+prompt or by loading it through the pymol interface.
+
+The PDB and DX files can be input into other molecular viewers if
+preferred.  Several additional output formats are available; see
+below. Note that the residue numbering in the .scores files may not
+match that of the PDB file.
+
+The ConCavity approach proceeds in three conceptual steps: grid
+creation, pocket extraction, and residue mapping (see Methods in
+paper). First, the structural and evolutionary properties of the
+protein are used to create a regular 3D grid surrounding the protein
+in which the score associated with each grid point represents an
+estimated likelihood that it overlaps a bound ligand atom. Second,
+groups of contiguous, high-scoring grid points are clustered to
+extract pockets that adhere to given shape and size
+constraints. Finally, every protein residue is scored with an estimate
+of how likely it is to bind to a ligand based on its proximity to
+extracted pockets.
+
+Each of the algorithms described for these steps is implemented in
+concavity.  See the examples.
+
+=head1 REFERENCES
+
+=over
+
+=item Capra JA, Laskowski RA, Thornton JM, Singh M, and Funkhouser TA(2009) Predicting Protein Ligand Binding Sites by Combining Evolutionary Sequence Conservation and 3D Structure. PLoS Comput Biol, 5(12).
+
+=back
+
+=head1 OPTIONS
+
+B<PDBFILE> is a protein structure file in PDB format.  B<OUTPUT_NAME> becomes part of the output file names and may not contain "/".  Output is written to the current directory.
+
+=head2 Input
+
+=over
+
+=item B<-conservation> I<PATH>
+
+If the "-conservation" option is not given, then conservation
+information is not considered.  Note that there are separate
+conservation files for each protein chain in the structure, and the
+input to the -conservation option is the prefix of these files.
+Pre-computed conservation files available for almost the entire PQS on
+the ConCavity web site.  If you'd like to compute sequence
+conservation values for your own alignments, we recommend the JSD
+algorithm: L<http://compbio.cs.princeton.edu/conservation/>,
+available as score_conservation(1) from the conservation-code package.
+
+=back
+
+=head2 Grid Creation
+
+=over
+
+=item B<-grid_method> I<ligsite|surfnet|pocketfinder|custom>
+
+=item B<-resolution> I<int> I<int> I<int>
+
+Set the grid resolution.
+
+=item B<-spacing> I<float>
+
+Set the grid spacing.
+
+=back
+
+=head2 Pocket Extraction
+
+=over
+
+=item B<-extraction_method> I<search|topn|custom>
+
+=back
+
+=head2 Residue Mapping
+
+=over
+
+=item B<-res_map_method> I<blur|dist|dist-thresh|custom>
+
+=back
+
+Each of these algorithms is described in the text, and each has a
+number of additional parameters that change their behavior.  The
+"custom" option allows you to set the values of all parameters for
+each step yourself.  The presets (e.g. ligsite, search, blur) may
+override values you set on the command line, so use "custom" to have
+complete control.
+
+=head2 Output
+
+There are also several output format options. Pocket
+prediction grid values can be output in the following formats:
+
+=over
+
+=item B<-print_grid_dx> I<0|1>
+
+DX format.  This is I<1> by default.
+
+=item B<-print_grid_pdb> I<0|1>
+
+PDB format. The residue predictions are output as a PDB file with the residue
+scores mapped to the temp. factor field and pocket numbers to the
+residue sequence field.
+
+=item B<-print_grid_txt> I<0|1>
+
+Raw text.
+
+=item B<-v>
+
+Verbose mode.
+
+=back
+
+=head1 EXAMPLES
+
+Note: you may have to copy and uncompress the example data files before running the following examples.
+
+=over
+
+=item 1
+
+This will run concavity with default values (equivalent to ConCavity^L
+in the paper) on the structure 1G6C.pdb and consider the conservation
+values found in conservation_data/.  This set of predictions will be
+called "test1".  This produces the following default result files in the current directory:
+
+ concavity -conservation __docdir__/examples/conservation_data/1G6C __docdir__/examples/1G6C.pdb test1
+
+=item 2
+
+For example to score the structure 1G6C.pdb with
+ConCavity_Pocketfinder, Search, and Blur, you'd type:
+
+ concavity -conservation __docdir__/examples/conservation_data/1G6C -grid_method pocketfinder -extraction_method search -res_map_method blur __docdir__/examples/1G6C.pdb cc-pocketfinder_search_blur
+
+=back
+
+=head1 NOTES
+
+The authors primarily use PyMol and Chimera for visualization, but the range of
+output formats means you should be able to import the data into most
+structural analysis program.  Let us know if there are other output
+formats you'd like to see.
+
+=head1 SEE ALSO
+
+=over
+
+=item Concavity Homepage L<http://compbio.cs.princeton.edu/concavity/>
+
+=item score_conservation(1)
+
+=back
+
+=cut
--- a/Makefile
+++ b/Makefile
@@ -1,9 +1,15 @@
 #
 # Makefile for GAPS
 #
+PACKAGE:=concavity
+VERSION?=0.1
+prefix?=/usr
+
+datarootdir:=${prefix}/share
+docdir:=${datarootdir}/doc/${PACKAGE}
 
 .PHONY: all opt
-all: opt
+all: opt man
 
 opt:
 	$(MAKE) target "TARGET=$@"
@@ -13,6 +19,7 @@
 
 clean:
 	$(MAKE) target "TARGET=$@"
+	rm -f concavity.1
 
 release:
 	mkdir -p release
@@ -26,8 +33,12 @@
 	cd pkgs && $(MAKE) $(TARGET)
 	cd apps && $(MAKE) $(TARGET)
 
+.PHONY: man
+man: concavity.1
 
-
+%.1:	%.1.pod
+	sed -e 's|__docdir__|$(docdir)|g;s|__pkgdatadir__|$(pkgdatadir)|g;s|__sysconfdir__|$(sysconfdir)|g;s|__bindir__|$(bindir)|g;s|__VERSION__|$(VERSION)|g;s|__PACKAGE_VERSION__|$(PACKAGE_VERSION)|g;' "$<" | \
+	pod2man -c 'User Commands' -r "$(VERSION)" -name $(shell echo "$(basename $@)" | tr '[:lower:]' '[:upper:]') > "$@"