From 58f32e311a669e7e941146a8585078a31a812d02 Mon Sep 17 00:00:00 2001 From: Oliver Beckstein Date: Tue, 1 Nov 2022 10:55:33 -0700 Subject: [PATCH] added citations - MBAR citation - BAR citation - equilibrium_detection citation --- docs/estimators/alchemlyb.estimators.BAR.rst | 2 +- docs/estimators/alchemlyb.estimators.MBAR.rst | 2 +- docs/references.rst | 19 +++++++++-- src/alchemlyb/estimators/bar_.py | 13 +++++++ src/alchemlyb/estimators/mbar_.py | 34 +++++++++++-------- src/alchemlyb/preprocessing/subsampling.py | 7 ++++ 6 files changed, 58 insertions(+), 19 deletions(-) diff --git a/docs/estimators/alchemlyb.estimators.BAR.rst b/docs/estimators/alchemlyb.estimators.BAR.rst index aa6919ff..59a4f6b5 100644 --- a/docs/estimators/alchemlyb.estimators.BAR.rst +++ b/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:: diff --git a/docs/estimators/alchemlyb.estimators.MBAR.rst b/docs/estimators/alchemlyb.estimators.MBAR.rst index 90aa5270..f8e3b0b3 100644 --- a/docs/estimators/alchemlyb.estimators.MBAR.rst +++ b/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 diff --git a/docs/references.rst b/docs/references.rst index a8fea0aa..bd76538a 100644 --- a/docs/references.rst +++ b/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 + `_. + +.. [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 `_. .. [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 `_. - + Computer-Aided Molecular Design 29, 397-411. doi: `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 + `_. + .. [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. diff --git a/src/alchemlyb/estimators/bar_.py b/src/alchemlyb/estimators/bar_.py index c608abc3..3a7150b2 100644 --- a/src/alchemlyb/estimators/bar_.py +++ b/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. diff --git a/src/alchemlyb/estimators/mbar_.py b/src/alchemlyb/estimators/mbar_.py index da0a186b..d34434e9 100644 --- a/src/alchemlyb/estimators/mbar_.py +++ b/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 diff --git a/src/alchemlyb/preprocessing/subsampling.py b/src/alchemlyb/preprocessing/subsampling.py index d2ac278a..2b34274e 100644 --- a/src/alchemlyb/preprocessing/subsampling.py +++ b/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