integrate extended ensemble data into docs (#18)

* display extended ensemble data in docs
  - include extended ensemble test cases from #4 in gmx.rst
  - added sub-headings to distinguish Simple TI/FEP and Extended ensemble
    test data (note: do not use ==== underline because that is used in
    descr.rst, use --- over+underline)
* small reST fixes in extended ensemble descriptions
* Fixes so that the docs build without issues. For instance, make the citation markers unique.

docs/gmx.rst

@@ -14,10 +14,46 @@ can be accessed using the following accessor functions:
 .. autosummary::
 
    load_benzene
+   load_expanded_ensemble_case_1
+   load_expanded_ensemble_case_2
+   load_expanded_ensemble_case_3
 
 
-.. _gmx_benzene:
+-----------------
+Simple TI and FEP
+-----------------
+
+The data sets contain derivatives of the Hamiltonian (TI) and free
+energy perturbation (FEP) data suitable for processing with FEP
+estimators as well as BAR/MBAR. Individual :math:`\lambda` windows
+were run independently.
 
+
+.. _gmx_benzene:
 .. include:: ../src/alchemtest/gmx/benzene/descr.rst
 
 .. autofunction:: alchemtest.gmx.load_benzene
+
+
+-----------------		  
+Extended ensemble
+-----------------
+
+Data for *extended ensemble* simulations; case 1 and case 2 are
+extended ensembles in the alchemical parameters, case 3 includes
+replica exchange (REX).
+
+.. include:: ../src/alchemtest/gmx/expanded_ensemble/case_1/descr.rst
+
+.. autofunction:: alchemtest.gmx.load_expanded_ensemble_case_1
+
+
+.. include:: ../src/alchemtest/gmx/expanded_ensemble/case_2/descr.rst
+
+.. autofunction:: alchemtest.gmx.load_expanded_ensemble_case_2
+
+
+.. include:: ../src/alchemtest/gmx/expanded_ensemble/case_3/descr.rst
+
+.. autofunction:: alchemtest.gmx.load_expanded_ensemble_case_3
+

src/alchemtest/gmx/access.py

@@ -39,6 +39,7 @@ def load_expanded_ensemble_case_1():
     -------
     data : Bunch
         Dictionary-like object, the interesting attributes are:
+
         - 'data' : the data files by alchemical leg
         - 'DESCR': the full description of the dataset
 
@@ -62,6 +63,7 @@ def load_expanded_ensemble_case_2():
     -------
     data : Bunch
         Dictionary-like object, the interesting attributes are:
+
         - 'data' : the data files by alchemical leg
         - 'DESCR': the full description of the dataset
 
@@ -85,6 +87,7 @@ def load_expanded_ensemble_case_3():
     -------
     data : Bunch
         Dictionary-like object, the interesting attributes are:
+
         - 'data' : the data files by alchemical leg
         - 'DESCR': the full description of the dataset
 

src/alchemtest/gmx/expanded_ensemble/case_1/descr.rst

@@ -1,7 +1,7 @@
 Gromacs: Host CB7 and Guest C3 in water
 =======================================
 
-Host CB7 and Guest C3 in water, Guest C3 alchemically turned into Guest C3 in vacuum separated from water and Host CB7. This unpublished data uses Host CB7 and Guest C3 from [Muddana2014]_. Similar published data can be found in [Monroe2014]_.
+Host CB7 and Guest C3 in water, Guest C3 alchemically turned into Guest C3 in vacuum separated from water and Host CB7. This unpublished data uses Host CB7 and Guest C3 from [Muddana2014a]_. Similar published data can be found in [Monroe2014a]_.
 
 Notes
 -----
@@ -22,6 +22,6 @@ Data Set Characteristics:
 
 This dataset was generated using the expanded ensemble algorithm in the `Gromacs <http://www.gromacs.org/>`_ molecular dynamics engine.
 
-.. [Muddana2014] H. Muddana, A. Fenley, D. Mobley, and M. Gilson. The SAMPL4 host–guest blind prediction challenge: an overview. Journal of Computer-Aided Molecular Design, 28(4):305–317, 2014. PMID: 24599514. DOI: `10.1007/s10822-014-9735-1 <https://doi.org/10.1007/s10822-014-9735-1>`_.
+.. [Muddana2014a] H. Muddana, A. Fenley, D. Mobley, and M. Gilson. The SAMPL4 host–guest blind prediction challenge: an overview. Journal of Computer-Aided Molecular Design, 28(4):305–317, 2014. PMID: 24599514. DOI: `10.1007/s10822-014-9735-1 <https://doi.org/10.1007/s10822-014-9735-1>`_.
 
-.. [Monroe2014] J. Monroe and M. Shirts. Converging free energies of binding in cucurbit[7]uril and octa-acid host-guest systems from SAMPL4 using expanded ensemble simulations. Journal of Computer-Aided Molecular Design, 28(4):401–415, 2014. PMID: 24610238 DOI: `10.1007/s10822-014-9716-4 <https://doi.org/10.1007/s10822-014-9716-4>`_.
+.. [Monroe2014a] J. Monroe and M. Shirts. Converging free energies of binding in cucurbit[7]uril and octa-acid host-guest systems from SAMPL4 using expanded ensemble simulations. Journal of Computer-Aided Molecular Design, 28(4):401–415, 2014. PMID: 24610238 DOI: `10.1007/s10822-014-9716-4 <https://doi.org/10.1007/s10822-014-9716-4>`_.

src/alchemtest/gmx/expanded_ensemble/case_2/descr.rst

@@ -1,7 +1,7 @@
 Gromacs: Host CB7 and Guest C3 in water
 =======================================
 
-Host CB7 and Guest C3 in water, Guest C3 alchemically turned into Guest C3 in vacuum separated from water and Host CB7. This unpublished data uses Host CB7 and Guest C3 from [Muddana2014]_. Similar published data can be found in [Monroe2014]_.
+Host CB7 and Guest C3 in water, Guest C3 alchemically turned into Guest C3 in vacuum separated from water and Host CB7. This unpublished data uses Host CB7 and Guest C3 from [Muddana2014b]_. Similar published data can be found in [Monroe2014b]_.
 
 Notes
 -----
@@ -22,6 +22,6 @@ Data Set Characteristics:
 
 This dataset was generated using the expanded ensemble algorithm in the `Gromacs <http://www.gromacs.org/>`_ molecular dynamics engine.
 
-.. [Muddana2014] H. Muddana, A. Fenley, D. Mobley, and M. Gilson. The SAMPL4 host–guest blind prediction challenge: an overview. Journal of Computer-Aided Molecular Design, 28(4):305–317, 2014. PMID: 24599514. DOI: `10.1007/s10822-014-9735-1 <https://doi.org/10.1007/s10822-014-9735-1>`_.
+.. [Muddana2014b] H. Muddana, A. Fenley, D. Mobley, and M. Gilson. The SAMPL4 host–guest blind prediction challenge: an overview. Journal of Computer-Aided Molecular Design, 28(4):305–317, 2014. PMID: 24599514. DOI: `10.1007/s10822-014-9735-1 <https://doi.org/10.1007/s10822-014-9735-1>`_.
 
-.. [Monroe2014] J. Monroe and M. Shirts. Converging free energies of binding in cucurbit[7]uril and octa-acid host-guest systems from SAMPL4 using expanded ensemble simulations. Journal of Computer-Aided Molecular Design, 28(4):401–415, 2014. PMID: 24610238 DOI: `10.1007/s10822-014-9716-4 <https://doi.org/10.1007/s10822-014-9716-4>`_.
+.. [Monroe2014b] J. Monroe and M. Shirts. Converging free energies of binding in cucurbit[7]uril and octa-acid host-guest systems from SAMPL4 using expanded ensemble simulations. Journal of Computer-Aided Molecular Design, 28(4):401–415, 2014. PMID: 24610238 DOI: `10.1007/s10822-014-9716-4 <https://doi.org/10.1007/s10822-014-9716-4>`_.

src/alchemtest/gmx/expanded_ensemble/case_3/descr.rst

@@ -1,7 +1,7 @@
 Gromacs: Host CB7 and Guest C3 in water
 =======================================
 
-Host CB7 and Guest C3 in water, Guest C3 alchemically turned into Guest C3 in vacuum separated from water and Host CB7. This unpublished data uses Host CB7 and Guest C3 from [Muddana2014]_.
+Host CB7 and Guest C3 in water, Guest C3 alchemically turned into Guest C3 in vacuum separated from water and Host CB7. This unpublished data uses Host CB7 and Guest C3 from [Muddana2014c]_.
 
 Notes
 -----
@@ -22,4 +22,4 @@ Data Set Characteristics:
 
 This dataset was generated using the REX algorithm in the `Gromacs <http://www.gromacs.org/>`_ molecular dynamics engine.
 
-.. [Muddana2014] H. Muddana, A. Fenley, D. Mobley, and M. Gilson. The SAMPL4 host–guest blind prediction challenge: an overview. Journal of Computer-Aided Molecular Design, 28(4):305–317, 2014. PMID: 24599514. DOI: `10.1007/s10822-014-9735-1 <https://doi.org/10.1007/s10822-014-9735-1>`_.
+.. [Muddana2014c] H. Muddana, A. Fenley, D. Mobley, and M. Gilson. The SAMPL4 host–guest blind prediction challenge: an overview. Journal of Computer-Aided Molecular Design, 28(4):305–317, 2014. PMID: 24599514. DOI: `10.1007/s10822-014-9735-1 <https://doi.org/10.1007/s10822-014-9735-1>`_.