Merge pull request #264 from alchemistry/more-refs

added citations

docs/estimators/alchemlyb.estimators.BAR.rst

@@ -2,7 +2,7 @@
 
 BAR
 ===
-The :class:`~alchemlyb.estimators.BAR` estimator is a light wrapper around the implementation of the Bennett Acceptance Ratio (BAR) method from :mod:`pymbar` (:class:`pymbar.mbar.BAR`).
+The :class:`~alchemlyb.estimators.BAR` estimator is a light wrapper around the implementation of the Bennett Acceptance Ratio (BAR) method [Bennett1976]_ from :mod:`pymbar` (:class:`pymbar.mbar.BAR`).
 It uses information from neighboring sampled states to generate an estimate for the free energy difference between these state.
 
 .. SeeAlso::

docs/estimators/alchemlyb.estimators.MBAR.rst

@@ -2,7 +2,7 @@
 
 MBAR
 ====
-The :class:`~alchemlyb.estimators.MBAR` estimator is a light wrapper around the reference implementation of MBAR from :mod:`pymbar` (:class:`pymbar.mbar.MBAR`).
+The :class:`~alchemlyb.estimators.MBAR` estimator is a light wrapper around the reference implementation of MBAR [Shirts2008]_ from :mod:`pymbar` (:class:`pymbar.mbar.MBAR`).
 As a generalization of BAR, it uses information from all sampled states to generate an estimate for the free energy difference between each state.
 
 A more robust version of :class:`~alchemlyb.estimators.MBAR` is provided as

docs/references.rst

@@ -3,12 +3,25 @@
 References
 ==========
 
+.. [Bennett1976] C. H. Bennett. (1976). Efficient estimation of free energy
+   differences from Monte Carlo data. J Comp Phys 22, 245–268. doi:
+   `10.1016/0021-9991(76)90078-4
+   <https://doi.org/10.1016/0021-9991(76)90078-4>`_.
+
+.. [Shirts2008] M. R. Shirts and J. D. Chodera. (2008). Statistically optimal
+   analysis of samples from multiple equilibrium states. J Chem Phys
+   129, 124105. doi: `10.1063/1.2978177 <https://doi.org/10.1063/1.2978177>`_.
 
 .. [Klimovich2015] Klimovich, P.V., M. R. Shirts, and D. L. Mobley. (2015)
    Guidelines for the analysis of free energy calculations. Journal of
-   Computer-Aided Molecular Design 29, 397-411. doi:
-   `10.1007/s10822-015-9840-9 <https://doi.org/10.1007/s10822-015-9840-9>`_.
-		   
+   Computer-Aided Molecular Design 29, 397-411. doi: `10.1007/s10822-015-9840-9
+   <https://doi.org/10.1007/s10822-015-9840-9>`_.
+
+.. [Chodera2016] J. D. Chodera. (20016). A simple method for automated
+   equilibration detection in molecular simulations. Journal of Chemical Theory
+   and Computation 12, 1799-1805. doi: `10.1021/acs.jctc.5b00784
+   <https://doi.org/10.1021/acs.jctc.5b00784>`_.
+   
 .. [Fan2020] Fan, S., B. I. Iorga, and O. Beckstein. (2020). Prediction of
    octanol-water partition coefficients for the SAMPL6-log P molecules using
    molecular dynamics simulations with OPLS-AA, AMBER and CHARMM force fields.

src/alchemlyb/estimators/bar_.py

@@ -38,6 +38,19 @@ class BAR(BaseEstimator, _EstimatorMixOut):
     states_ : list
         Lambda states for which free energy differences were obtained.
 
+    Notes
+    -----
+    See [Bennett1976]_ for details of the derivation and cite the paper
+    (together with [Shirts2008]_ for the Python implementation in
+    :mod:`pymbar`) when using BAR in published work.
+
+    When possible, use MBAR instead of BAR as it makes better use of the
+    available data.
+
+    See Also
+    --------
+    MBAR
+
 
     .. versionchanged:: 1.0.0
        `delta_f_`, `d_delta_f_`, `states_` are view of the original object.

src/alchemlyb/estimators/mbar_.py

@@ -20,7 +20,7 @@ class MBAR(BaseEstimator, _EstimatorMixOut):
         Set to determine the relative tolerance convergence criteria.
 
     initial_f_k : np.ndarray, float, shape=(K), optional
-        Set to the initial dimensionless free energies to use as a 
+        Set to the initial dimensionless free energies to use as a
         guess (default None, which sets all f_k = 0).
 
     method : str, optional, default="hybr"
@@ -47,9 +47,15 @@ class MBAR(BaseEstimator, _EstimatorMixOut):
     states_ : list
         Lambda states for which free energy differences were obtained.
 
+    Notes
+    -----
+    See [Shirts2008]_ for details of the derivation and cite the
+    paper when using MBAR in published work.
+
     See Also
     --------
-    pymbar.MBAR
+    pymbar.mbar.MBAR
+    AutoMBAR
 
 
     .. versionchanged:: 1.0.0
@@ -75,7 +81,7 @@ def fit(self, u_nk):
 
         Parameters
         ----------
-        u_nk : DataFrame 
+        u_nk : DataFrame
             u_nk[n,k] is the reduced potential energy of uncorrelated
             configuration n evaluated at state k.
 
@@ -117,7 +123,7 @@ def _do_MBAR(self, u_nk, N_k, solver_protocol):
                      initial_f_k=self.initial_f_k,
                      solver_protocol=(solver_protocol,))
         self.logger.info("Solved MBAR equations with method %r and "
-                         "maximum_iterations=%d, relative_tolerance=%g", 
+                         "maximum_iterations=%d, relative_tolerance=%g",
                          solver_protocol['method'],
                          solver_protocol['options']['maximum_iterations'],
                          self.relative_tolerance)
@@ -145,16 +151,16 @@ def overlap_matrix(self):
 class AutoMBAR(MBAR):
     """A more robust version of Multi-state Bennett acceptance ratio (MBAR).
 
-    Given that there isn't a single *method* that would allow :class:`MBAR` 
-    to converge for every single use case, the :class:`AutoMBAR` estimator 
-    iteratively tries all the available methods to obtain the converged estimate. 
-    
+    Given that there isn't a single *method* that would allow :class:`MBAR`
+    to converge for every single use case, the :class:`AutoMBAR` estimator
+    iteratively tries all the available methods to obtain the converged estimate.
+
     The fastest method *hybr* will be tried first, followed by the most stable method
-    *adaptive*. If *adaptive* does not converge, *BFGS* will be used as last resort. 
-    Although *BFGS* is not as stable as *adaptive*, it has been shown to succeed in  
+    *adaptive*. If *adaptive* does not converge, *BFGS* will be used as last resort.
+    Although *BFGS* is not as stable as *adaptive*, it has been shown to succeed in
     some cases where *adaptive* cannot.
 
-    :class:`AutoMBAR` may be useful in high-throughput calculations where it can avoid 
+    :class:`AutoMBAR` may be useful in high-throughput calculations where it can avoid
     failures due non-converged MBAR estimates.
 
     Parameters
@@ -166,17 +172,17 @@ class AutoMBAR(MBAR):
         as MBAR.
 
         .. versionadded:: 1.0.0
-        
+
 
     Note
     ----
-    All arguments are described under :class:`MBAR` except that the solver method 
+    All arguments are described under :class:`MBAR` except that the solver method
     is determined by :class:`AutoMBAR` as described above.
 
     See Also
     --------
     MBAR
-    
+
 
     .. versionadded:: 0.6.0
     .. versionchanged:: 1.0.0

src/alchemlyb/preprocessing/subsampling.py

@@ -493,6 +493,9 @@ def equilibrium_detection(df, series=None, lower=None, upper=None, step=None,
                           drop_duplicates=False, sort=False):
     """Subsample a DataFrame using automated equilibrium detection on a timeseries.
 
+    This function uses the :mod:`pymbar` implementation of the *simple
+    automated equilibrium detection* algorithm in [Chodera2016]_.
+
     If `series` is ``None``, then this function will behave the same as
     :func:`slicing`.
 
@@ -519,6 +522,10 @@ def equilibrium_detection(df, series=None, lower=None, upper=None, step=None,
     DataFrame
         `df` subsampled according to subsampled `series`.
 
+    Notes
+    -----
+    Please cite [Chodera2016]_ when you use this function in published work.
+
     See Also
     --------
     pymbar.timeseries.detectEquilibration : detailed background