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