move tutorials to documentation/, update rescoring tutorial and README

Move misc/tutorials/ to documentation/ and add index readme.
Update rescoring.md: add quick-start examples, paper links for all
methods, add Pocketeer to supported methods list.
Fix stale links in README.md (tutorials path, local-env.sh typo).

README.md

@@ -147,15 +147,17 @@ parameters see [Params.groovy](https://github.com/rdk/p2rank/blob/develop/src/ma
 ### Rescoring (PRANK algorithm)
 
 In addition to predicting new ligand binding sites, 
-P2Rank is also able to rescore pockets predicted by other methods 
-(Fpocket, 
-ConCavity, 
-SiteHound, 
-MetaPocket2, 
-LISE, 
+P2Rank is also able to rescore pockets predicted by other methods
+(Fpocket,
+Pocketeer,
+ConCavity,
+SiteHound,
+MetaPocket2,
+LISE,
 DeepSite,
 and PUResNetV2.0
 are supported at the moment).
+See [rescoring documentation](documentation/rescoring.md) for details.
 
 Rescoring output:
 * `{protein_file}_rescored.csv`: list of pockets sorted by the new score
@@ -219,7 +221,7 @@ You can now run the program using:
 distro/prank       # standard mode that is run in production
 ./prank.sh         # development/training mode 
 ``` 
-To use `./prank.sh` (development/training mode) first you need to copy and edit `misc/locval-env.sh` into repo root directory (see [training tutorial](https://github.com/rdk/p2rank/blob/develop/misc/tutorials/training-tutorial.md#preparing-the-environment)).
+To use `./prank.sh` (development/training mode) first you need to copy and edit `misc/local-env.sh` into repo root directory (see [training tutorial](https://github.com/rdk/p2rank/blob/develop/documentation/training-tutorial.md#preparing-the-environment)).
 
 ## ⚖️ Comparison with Fpocket
 

documentation/readme.md

@@ -0,0 +1,25 @@
+# Documentation
+
+This directory contains documentation and tutorials for P2Rank.
+Note that the coverage is spotty and incomplete -- not all features and workflows are documented here.
+
+## Usage
+
+| File | Description |
+|------|-------------|
+| [rescoring.md](rescoring.md) | Rescoring predictions from other pocket prediction methods (Fpocket, Pocketeer, etc.) |
+| [export-points.md](export-points.md) | Exporting SAS points with feature vectors and predicted ligandability scores |
+| [aa-mapping.md](aa-mapping.md) | Non-canonical amino acid residue mapping to standard residues |
+| [hidden-commands.md](hidden-commands.md) | Miscellaneous hidden commands and analysis tools |
+| [random-examples.md](random-examples.md) | Assorted command-line examples for prediction and evaluation |
+
+## Training
+
+| File | Description |
+|------|-------------|
+| [training-tutorial.md](training-tutorial.md) | Training and evaluating custom models, crossvalidation, grid optimization |
+| [feature-setup.md](feature-setup.md) | Feature vector configuration and introduction to adding new features |
+| [new-feature-evaluation-tutorial.md](new-feature-evaluation-tutorial.md) | Implementing a new feature and evaluating its contribution to prediction |
+| [hyperparameter-optimization-tutorial.md](hyperparameter-optimization-tutorial.md) | Grid and Bayesian optimization of algorithm parameters |
+| [training-score-transformers.md](training-score-transformers.md) | Training probability and z-score transformers for pocket and residue scores |
+

documentation/rescoring.md

@@ -3,6 +3,16 @@
 P2Rank can rescore pocket predictions from other binding site prediction tools,
 re-ranking their pockets using its own ML model.
 
+## Quick Start
+
+```bash
+prank rescore test_data/fpocket.ds                            # rescore fpocket predictions
+prank rescore test_data/pocketeer.ds -o rescore_pocketeer     # rescore pocketeer, output to specific dir
+prank eval-rescore test_data/fpocket.ds                       # rescore and evaluate against known ligands
+prank fpocket-rescore test_data/basic.ds                      # run fpocket and rescore in one step
+prank rescore test_data/pocketeer.ds -c rescore_2024          # use new experimental rescoring model
+```
+
 ## Commands
 
 | Command | Description                                                                                                                    |
@@ -13,17 +23,17 @@ re-ranking their pockets using its own ML model.
 
 ## Supported Methods
 
-| Method | `PREDICTION_METHOD` | Prediction column points to | URL |
-|--------|--------------------|-----------------------------|-----|
-| Fpocket | `fpocket` | Fpocket output file (`.pdb`/`.cif`) | [GitHub](https://github.com/Discngine/fpocket) |
+| Method | `PREDICTION_METHOD` | Prediction column points to | Links |
+|--------|--------------------|-----------------------------|-------|
+| Fpocket | `fpocket` | Fpocket output file (`.pdb`/`.cif`) | [GitHub](https://github.com/Discngine/fpocket), [paper](https://doi.org/10.1186/1471-2105-10-168) |
 | Pocketeer | `pocketeer` | `pockets.json` file | [GitHub](https://github.com/cch1999/pocketeer) |
-| PUResNetV2.0 | `puresnet` | Directory with `*.pkt.pdb` files | [GitHub](https://github.com/jivankandel/PUResNetV2.0) |
-| ConCavity | `concavity` | `*_pocket.pdb` grid file | [project page](https://compbio.cs.princeton.edu/concavity/) |
+| PUResNetV2.0 | `puresnet` | Directory with `*.pkt.pdb` files | [GitHub](https://github.com/jivankandel/PUResNetV2.0), [paper](https://doi.org/10.1186/s13321-024-00865-6) |
+| ConCavity | `concavity` | `*_pocket.pdb` grid file | [project page](https://compbio.cs.princeton.edu/concavity/), [paper](https://doi.org/10.1371/journal.pcbi.1000585) |
 | SiteHound | `sitehound` | `*_summary.dat` file | [paper](https://pmc.ncbi.nlm.nih.gov/articles/PMC2703923/) |
-| DeepSite | `deepsite` | Results PDB file | [web app](https://playmolecule.org/deepsite/) |
+| DeepSite | `deepsite` | Results PDB file | [paper](https://doi.org/10.1093/bioinformatics/btx350) |
 | MetaPocket2 | `metapocket2` | PDB file with MPT residues | [paper](https://academic.oup.com/bioinformatics/article/27/15/2083/402380) |
 | LISE | `lise` | PDB file with HETATM records | [paper](https://academic.oup.com/nar/article/41/W1/W292/1094035) |
-| P2Rank | `p2rank` | `*_predictions.csv` file | [GitHub](https://github.com/rdk/p2rank) |
+| P2Rank | `p2rank` | `*_predictions.csv` file | [GitHub](https://github.com/rdk/p2rank), [paper](https://doi.org/10.1186/s13321-018-0285-8) |
 
 ## Dataset File Format