Merge pull request #26 from MobleyLab/release0.1

Clean up/complete documentation for first release

README.md

@@ -21,20 +21,21 @@ All three host-guest components of this challenge are now final and launched, th
   - Submission file formats
 - GSK logD challenge information as soon as available
 
+## Disclaimers:
+- As usual, we make no warranty as to correctness of protonation states, tautomers, conformations and poses provided in these directories. In some cases the most relevant such states may not be known, or multiple states perhaps should be considered. Please exercise caution and due diligence.
+- We make an effort to indicate which files are original source files, and which are derived files, so that participants can refer to the original source files to help resolve any uncertainties. We encourage participants to do so.
+- While we make every effort to ensure correctness of the files we provide, it is not uncommon for there to be some errors. *Please* sign up for our e-mail list, since if any critical bugs are found, we will e-mail out appropriate announcements. 
+
 ## Changes and Data Set Versions
 
 ### Release versions
+- **Release 0.1** (July 22, 2019): Finalizes all three host-guest systems and provides sdf, mol2 and PDB files for all guests. Fixes several critical bugs, including **fixing several incorrect cyclodextrin-derivative host structure files**, **fixing errors in a draft TrimerTrip structure file**, **fixing the SMILES string for TrimerTrip guest `g15`**, and **finalizing TrimerTrip guest list**.
 
 ### Changes not in a release
-There are no formal releases yet, so here we only note particularly important changes. 
-- **Critical bug**: Isaacs/TrimerTrip guest `g15` had an incorrect SMILES string as originally provided. This was corrected in the provided input files on July 18, 2019.
-- **Finalized systems**: Finalized details of TrimerTrip hosts from Lyle Isaacs, July 22, 2019. Materials added this date included several modifications to which guests are being considered relative to what had been provided earlier. GDCC and cyclodextrin challenges were finalized at an earlier date.
-- **Critical bug**: Isaacs/TrimerTrip host draft 3D structure files (mol2, sdf, PDB) had incorrect host due to a bond perception error in generating the files initially.
-- **Critical bug**: Cyclodextrin hosts 9, 24 and 36 had incorrect starting PDB files (and thus host mol2/sdf files as well) due to errors in their construction in the Gilson lab. 2D structures of these compounds were correct, however. This has now been fixed.
 
 ## Challenge overview
 
-The SAMPL7 phase of challenges currently includes host-guest binding on three systems: A pair of Gibb Deeep Cavity Cavitands (GDCCs), a new "TrimerTrip" molecule from Lyle Isaacs and his group, and a series of cyclodextrin derivatives from Mike Gilson's group. Each host binds one or more guests, and each system involves a total of 9-20 binding free energy calculations.
+The SAMPL7 phase of challenges currently includes host-guest binding on three systems: A pair of Gibb Deep Cavity Cavitands (GDCCs), a new "TrimerTrip" molecule from Lyle Isaacs and his group, and a series of cyclodextrin derivatives from Mike Gilson's group. Each host binds one or more guests, and each system involves a total of 9-20 binding free energy calculations.
 Additional details are provided below.
 
 A later phase of SAMPL7 is expected to include logD prediction (hopefully with pKa values provided) for a series of small moleculs in several solvents; data is currently being collected in partnership with GSK.
@@ -45,7 +46,7 @@ One host-guest series is based on the Gibb Deep Cavity Cavitands (GDCCs), famili
 
 ### Modified acyclic cucurbituril (TrimerTrip) binding of guests
 
-The Isaacs lab is contributing data on binding of a series of guests to an acyclic cucubituril host, codenamed "TrimerTrip", as detailed in `host_guest/Isaacs_clip` tentatively. Guest selection is still being finalized to ensure good dynamic range, but it will likely include compounds which overlap with the GDCC and cyclodextrin-derivative challenges, with a total of roughly ten complexes being examined.
+The Isaacs lab is contributing data on binding of a series of guests to an acyclic cucubituril host, codenamed "TrimerTrip", as detailed in `host_guest/Isaacs_clip`. Guests include compounds which overlap with the GDCC and cyclodextrin-derivative challenges, with a total of roughly 15 complexes being examined.
 
 ### The cyclodextrin derivatives challenge
 

host_guest/GDCC_and_guests/README.md

@@ -34,8 +34,15 @@ Buffer conditions are expected to be 10 mM sodium phosphate, but this will be co
 
 For positively charged guests, chloride salts are expected to be used.
 
+### Disclaimers
+
+The protonation state of the host may in some cases be not completely certain, and participants are also encouraged to carefully select guest protonation states. Protonation states and conformations may or may not match those of the files provided here. 
+
 # What's here
 
 - Hosts: `host_files`: Folder containing PDB, MOL2 and SDF files for the Octa Acid (OA) host and the exo-OA host. Contains the the jupyter notebook used to generate the MOL2 and SDF files of the guests.
 - Guests: `guest_files`: Folder containing files for the eight guests, SMILES strings, and the jupyter notebook used to generate PDB, MOL2 and SDF files of the guests.
 - Images: `images`: Folder containing images of the guest and host structures for this challenge in PDF format.
+
+**Source files**:
+For this portion of the challenge, the original source files were two (provided) host PDB files from Paolo Suating (in the `host_files` directory) and a `SAMPL7_guests.cdx` file from Bruce Gibb (in the `guest_files` directory). All other files here were derived from those files.

host_guest/Isaacs_clip/README.md

@@ -11,8 +11,17 @@ Following this, the challenge is expected to launch around June 1, 2019, with ex
 
 ![](images/SAMPL7.jpg)
 
+## Disclaimer
+
+Note that we have typically selected reasonable protonation states and conformers of the host and guests, but these may be controversial, uncertain, or change upon binding, so participants are encouraged to exercise care in selecting which states are modeled. In this case in particular, the host structure was [simulated for a period of time](host_files/README.md) in the absence of any guests prior to deposition, which may or may not mean that additional equilibration is needed in the presence of guests before conducting binding free energy calculations.
+
 # What's here
 
 - Hosts: `host_files`: Folder containing PDB, MOL2, SDF and Chemdraw files for the TrimerTrip host. Contains a detailed description of input file generation for the TrimerTrip host.
 - Guests: `guest_files`: Folder containing files for the 15 guests, SMILES strings, and the jupyter notebook used to generate PDB, MOL2 and SDF files of the guests.
 - Images: `images`: Folder containing an image of the guest and host structures for this challenge in JPG file format.
+
+**Source files**
+In this case the original source files provided were:
+- `guest_files/SAMPL7.cdx`, from Lyle Isaacs, providing a 2D structure of the host and all of the guests
+- A (not deposited) `.cif` crystallographic file of the host, from which we prepared the host structure and checked it against the 2D structure.

host_guest/README.md

@@ -4,3 +4,5 @@
 - `Isaacs_clip`: Files for the TrimerTrip challenge, on a clip shaped host from Lyle Isaacs which binds a series of guests
 - `cyclodextrin_derivative`: Files for the Gilson lab's cyclodextrin derivative challenge, on a series of *hosts* binding two different guests.
 - `scripts`: Scripts used in preparing some of the files present here and doing other processing.
+
+Note that we have typically selected reasonable protonation states and conformers of the hosts and guests, but these may be controversial, uncertain, or change upon binding, so participants are encouraged to exercise care in selecting which states are modeled. 

host_guest/cyclodextrin_derivatives/README.md

@@ -33,8 +33,20 @@ Binding in all systems was assayed in 25 mM pH 6.8 sodium phosphate buffer at 27
 Compounds exhibiting strange binding patterns have already been removed prior to construction of this set.
 [Full experimental details are available.](../host_guest_description.md)
 
+### Disclaimers
+
+Note that we have typically selected reasonable protonation states and conformers of the hosts and guests, but these may be controversial, uncertain, or change upon binding, so participants are encouraged to exercise care in selecting which states are modeled.
+
 # What's here
 
 - Hosts: `host_files`: Folder containing beta cyclodextrin plus the eight other cyclodextrin derivative hosts, provided by Katy Kellett and Michael Gilson, initially only in PDB format with all protons present. The Chemdraw files are also provided. MOL2 and SDF files of the hosts were added on 7/18/19.
 - Guests: `guest_files`: Contains MOL2, PDB and SDF files and files containing the isomeric SMILES strings and codenames of the guests.
 - Images: `images`: Folder containing images of the guest and host structures for this challenge in JPG and PDF format.
+
+**Source files**:
+- PDB files of all hosts from the Gilson lab, which served to generate host sdf and mol2 files
+- SMILES strings for the guests, which were used to generate PDB and SDF files for the guests, as well as names
+
+**Auxiliary files**:
+- ChemDraw files of all hosts from the Gilson lab
+- mol2 files for the guests from the Gilson lab