[Debian-med-packaging] man page patch for concavity

[Laszlo Kajan]

(author is Bcc'd on this email)

Dear Tom!

I've created a man page for concavity (attached), based on the README file distributed with it. Please let me know if you would like any changes
to it.

Thank you for making concavity available to the community.

Best regards,

Laszlo Kajan
-------------- next part --------------
Author: Laszlo Kajan <lkajan at rostlab.org>
Description: man page for concavity
Forwarded: no
--- /dev/null
+++ b/concavity.1.pod
@@ -0,0 +1,190 @@
+=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: http://compbio.cs.princeton.edu/conservation/
+
+=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
+
+=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/>
+
+=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:]') > "$@"