From 3ae6668ec323420ca8d14b206534c94fffc5ae91 Mon Sep 17 00:00:00 2001 From: Oliver Beckstein Date: Wed, 2 Jun 2021 15:58:06 -0700 Subject: [PATCH] regenerated generated reST doc files --- docs/estimators/alchemlyb.estimators.BAR.rst | 34 ++++++++----- docs/estimators/alchemlyb.estimators.MBAR.rst | 44 +++++++++++----- docs/estimators/alchemlyb.estimators.TI.rst | 33 ++++++++---- docs/parsing/alchemlyb.parsing.amber.rst | 42 +++++++++++---- docs/parsing/alchemlyb.parsing.gmx.rst | 51 ++++++++----------- docs/parsing/alchemlyb.parsing.gomc.rst | 35 +++++++++---- docs/parsing/alchemlyb.parsing.namd.rst | 44 ++++++++-------- .../alchemlyb.preprocessing.subsampling.rst | 37 ++++++++++---- ...chemlyb.visualisation.plot_convergence.rst | 19 ++----- .../alchemlyb.visualisation.plot_dF_state.rst | 35 ++----------- ...visualisation.plot_mbar_overlap_matrix.rst | 20 ++------ .../alchemlyb.visualisation.plot_ti_dhdl.rst | 24 ++------- 12 files changed, 216 insertions(+), 202 deletions(-) diff --git a/docs/estimators/alchemlyb.estimators.BAR.rst b/docs/estimators/alchemlyb.estimators.BAR.rst index aa6919ff..64b52a06 100644 --- a/docs/estimators/alchemlyb.estimators.BAR.rst +++ b/docs/estimators/alchemlyb.estimators.BAR.rst @@ -1,15 +1,25 @@ -.. _estimators_BAR: +alchemlyb.estimators.BAR +======================== -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`). -It uses information from neighboring sampled states to generate an estimate for the free energy difference between these state. +.. currentmodule:: alchemlyb.estimators -.. SeeAlso:: - :class:`alchemlyb.estimators.MBAR` +.. autoclass:: BAR -API Reference -------------- -.. autoclass:: alchemlyb.estimators.BAR - :members: - :inherited-members: + + .. automethod:: __init__ + + + .. rubric:: Methods + + .. autosummary:: + + ~BAR.__init__ + ~BAR.fit + ~BAR.get_params + ~BAR.set_params + + + + + + \ No newline at end of file diff --git a/docs/estimators/alchemlyb.estimators.MBAR.rst b/docs/estimators/alchemlyb.estimators.MBAR.rst index 05719aaa..4ab9fdfe 100644 --- a/docs/estimators/alchemlyb.estimators.MBAR.rst +++ b/docs/estimators/alchemlyb.estimators.MBAR.rst @@ -1,12 +1,32 @@ -.. _estimators_MBAR: - -MBAR -==== -The :class:`~alchemlyb.estimators.MBAR` estimator is a light wrapper around the reference implementation of MBAR 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. - -API Reference -------------- -.. autoclass:: alchemlyb.estimators.MBAR - :members: - :inherited-members: +alchemlyb.estimators.MBAR +========================= + +.. currentmodule:: alchemlyb.estimators + +.. autoclass:: MBAR + + + .. automethod:: __init__ + + + .. rubric:: Methods + + .. autosummary:: + + ~MBAR.__init__ + ~MBAR.fit + ~MBAR.get_params + ~MBAR.predict + ~MBAR.set_params + + + + + + .. rubric:: Attributes + + .. autosummary:: + + ~MBAR.overlap_matrix + + \ No newline at end of file diff --git a/docs/estimators/alchemlyb.estimators.TI.rst b/docs/estimators/alchemlyb.estimators.TI.rst index 108b65c2..20b0da9a 100644 --- a/docs/estimators/alchemlyb.estimators.TI.rst +++ b/docs/estimators/alchemlyb.estimators.TI.rst @@ -1,11 +1,26 @@ -.. _estimatators_TI: +alchemlyb.estimators.TI +======================= -TI -== -The :class:`~alchemlyb.estimators.TI` estimator is a simple implementation of `thermodynamic integration `_ that uses the trapezoid rule for integrating the space between :math:`\left<\frac{dH}{d\lambda}\right>` values for each :math:`\lambda` sampled. +.. currentmodule:: alchemlyb.estimators -API Reference -------------- -.. autoclass:: alchemlyb.estimators.TI - :members: - :inherited-members: +.. autoclass:: TI + + + .. automethod:: __init__ + + + .. rubric:: Methods + + .. autosummary:: + + ~TI.__init__ + ~TI.fit + ~TI.get_params + ~TI.separate_dhdl + ~TI.set_params + + + + + + \ No newline at end of file diff --git a/docs/parsing/alchemlyb.parsing.amber.rst b/docs/parsing/alchemlyb.parsing.amber.rst index c297b888..581f3e2f 100644 --- a/docs/parsing/alchemlyb.parsing.amber.rst +++ b/docs/parsing/alchemlyb.parsing.amber.rst @@ -1,20 +1,40 @@ -Amber parsing -============= +alchemlyb.parsing.amber +======================= + .. automodule:: alchemlyb.parsing.amber -The parsers featured in this module are constructed to properly parse `Amber MD`_ output files containing derivatives of the Hamiltonian and FEP (BAR/MBAR) data. + + + + + + + .. rubric:: Functions + + .. autosummary:: + + any_none + convert_to_pandas + extract_dHdl + extract_u_nk + file_validation + + -.. _Amber MD: http://ambermd.org/ + + + .. rubric:: Classes -.. TODO + .. autosummary:: + + FEData + SectionParser + - Notes on what options need to be set in Amber to produce the required output. See the Gromacs parser page for an example of the information that we would like to have here. + + + -API Reference -------------- -This submodule includes these parsing functions: -.. autofunction:: alchemlyb.parsing.amber.extract_dHdl -.. autofunction:: alchemlyb.parsing.amber.extract_u_nk diff --git a/docs/parsing/alchemlyb.parsing.gmx.rst b/docs/parsing/alchemlyb.parsing.gmx.rst index 0c875f56..d8502c8f 100644 --- a/docs/parsing/alchemlyb.parsing.gmx.rst +++ b/docs/parsing/alchemlyb.parsing.gmx.rst @@ -1,39 +1,30 @@ -Gromacs parsing -=============== -.. automodule:: alchemlyb.parsing.gmx - -The parsers featured in this module are constructed to properly parse XVG files containing Hamiltonian differences (for obtaining reduced potentials, :math:`u_{nk}`) and/or Hamiltonian derivatives (for obtaining gradients, :math:`\frac{dH}{d\lambda}`). -To produce such a file from an existing EDR energy file, use ``gmx energy -f <.edr> -odh dhdl.xvg`` with your installation of `Gromacs`_. - -If you wish to use FEP-based estimators such as :class:`~alchemlyb.estimators.MBAR` that require reduced potentials for all lambda states in the alchemical leg, you will need to use these MDP options: - -.. code-block:: none +alchemlyb.parsing.gmx +===================== - calc-lambda-neighbors = -1 ; calculate Delta H values for all other lambda windows - dhdl-print-energy = potential ; total potential energy of system included - -In addition, the full set of lambda states for the alchemical leg should be explicitly specified in the ``fep-lambdas`` option (or ``coul-lambdas``, ``vdw-lambdas``, etc.), since this is what Gromacs uses to determine what lambda values to calculate :math:`\Delta H` values for. - -To use TI-based estimators that require gradients, you will need to include these options: - -.. code-block:: none +.. automodule:: alchemlyb.parsing.gmx - dhdl-derivatives = yes ; write derivatives of Hamiltonian with respect to lambda + + + -Additionally, the parsers can properly parse XVG files (containing Hamiltonian differences and/or Hamiltonian derivatives) produced during expanded ensemble simulations. To produce such a file during the simulation, use ``gmx mdrun -deffnm -dhdl dhdl.xvg`` with your installation of `Gromacs`_. -To run an expanded ensemble simulation you will need to use the following MDP option: + + + .. rubric:: Functions -.. code-block:: none + .. autosummary:: + + extract_dHdl + extract_u_nk + + - free_energy = expanded ; turns on expanded ensemble simulation, lambda state becomes a dynamic variable + + + -.. _`Gromacs`: http://www.gromacs.org/ -.. _`MDP options`: + + + -API Reference -------------- -This submodule includes these parsing functions: -.. autofunction:: alchemlyb.parsing.gmx.extract_dHdl -.. autofunction:: alchemlyb.parsing.gmx.extract_u_nk diff --git a/docs/parsing/alchemlyb.parsing.gomc.rst b/docs/parsing/alchemlyb.parsing.gomc.rst index 200d4a29..b7418330 100644 --- a/docs/parsing/alchemlyb.parsing.gomc.rst +++ b/docs/parsing/alchemlyb.parsing.gomc.rst @@ -1,15 +1,30 @@ -GOMC parsing -============== +alchemlyb.parsing.gomc +====================== + .. automodule:: alchemlyb.parsing.gomc -The parsers featured in this module are constructed to properly parse `GOMC `_ free energy output files, -containing the Hamiltonian derivatives (:math:`\frac{dH}{d\lambda}`) for TI-based estimators and Hamiltonian differences (:math:`\Delta H` -for all lambda states in the alchemical leg) for FEP-based estimators (BAR/MBAR). + + + + + + + .. rubric:: Functions + + .. autosummary:: + + extract_dHdl + extract_u_nk + + + + + + + + + + -API Reference -------------- -This submodule includes these parsing functions: -.. autofunction:: alchemlyb.parsing.gomc.extract_dHdl -.. autofunction:: alchemlyb.parsing.gomc.extract_u_nk diff --git a/docs/parsing/alchemlyb.parsing.namd.rst b/docs/parsing/alchemlyb.parsing.namd.rst index 9e71e519..8dfd6cfa 100644 --- a/docs/parsing/alchemlyb.parsing.namd.rst +++ b/docs/parsing/alchemlyb.parsing.namd.rst @@ -1,33 +1,29 @@ -NAMD parsing -============= -.. automodule:: alchemlyb.parsing.namd - -The parsers featured in this module are constructed to properly parse `NAMD`_ ``.fepout`` output files containing derivatives of the Hamiltonian and FEP (BAR) data. -See the NAMD documentation for the `theoretical backdrop `_ and `implementation details `_. +alchemlyb.parsing.namd +====================== -If you wish to use BAR on FEP data, be sure to provide the ``.fepout`` file from both the forward and reverse transformations. +.. automodule:: alchemlyb.parsing.namd -After calling :meth:`~alchemlyb.parsing.namd.extract_u_nk` on the forward and reverse work values, these dataframes can be combined into one: + + + -.. code-block:: python + + + .. rubric:: Functions - # replace zeroes in initial dataframe with nan - u_nk_fwd.replace(0, np.nan, inplace=True) - # replace the nan values with the reverse dataframe -- - # this should not overwrite any of the fwd work values - u_nk_fwd[u_nk_fwd.isnull()] = u_nk_rev - # replace remaining nan values back to zero - u_nk_fwd.replace(np.nan, 0, inplace=True) - # sort final dataframe by `fep-lambda` (as opposed to `timestep`) - u_nk = u_nk_fwd.sort_index(level=u_nk_fwd.index.names[1:]) + .. autosummary:: + + extract_u_nk + + -The ``fep-lambda`` index states at which lambda this particular frame was sampled, whereas the columns are the evaluations of the Hamiltonian (or the potential energy U) at other lambdas (sometimes called "foreign lambdas"). + + + -.. _`NAMD`: http://www.ks.uiuc.edu/Research/namd/ + + + -API Reference -------------- -This submodule includes these parsing functions: -.. autofunction:: alchemlyb.parsing.namd.extract_u_nk diff --git a/docs/preprocessing/alchemlyb.preprocessing.subsampling.rst b/docs/preprocessing/alchemlyb.preprocessing.subsampling.rst index bbc41dd1..62a308f2 100644 --- a/docs/preprocessing/alchemlyb.preprocessing.subsampling.rst +++ b/docs/preprocessing/alchemlyb.preprocessing.subsampling.rst @@ -1,14 +1,31 @@ -.. _subsampling: - -Subsampling -=========== +alchemlyb.preprocessing.subsampling +=================================== .. automodule:: alchemlyb.preprocessing.subsampling -The functions featured in this module can be used to easily subsample either :ref:`dHdl ` or :ref:`u_nk ` datasets to give less correlated timeseries. + + + + + + + .. rubric:: Functions + + .. autosummary:: + + equilibrium_detection + slicing + statistical_inefficiency + + + + + + + + + + + + -API Reference -------------- -.. autofunction:: alchemlyb.preprocessing.subsampling.slicing -.. autofunction:: alchemlyb.preprocessing.subsampling.statistical_inefficiency -.. autofunction:: alchemlyb.preprocessing.subsampling.equilibrium_detection diff --git a/docs/visualisation/alchemlyb.visualisation.plot_convergence.rst b/docs/visualisation/alchemlyb.visualisation.plot_convergence.rst index ea532ea2..16b9580a 100644 --- a/docs/visualisation/alchemlyb.visualisation.plot_convergence.rst +++ b/docs/visualisation/alchemlyb.visualisation.plot_convergence.rst @@ -1,19 +1,6 @@ -.. _visualisation_plot_convergence: - -Plot the Forward and Backward Convergence +alchemlyb.visualisation.plot\_convergence ========================================= -The function :func:`~alchemlyb.visualisation.plot_convergence` allows -the user to visualise the convergence by plotting the free energy change -computed using the equilibrated snapshots between the proper target time frames -in both forward (data points are stored in `forward` and `forward_error`) and -reverse (data points are stored in `backward` and `backward_error`) directions. -The unit in the y axis could be labelled to other units by setting *units*, -which by default is :math:`kT`. The user can pass :class:`matplotlib.axes.Axes` into -the function to have the convergence drawn on a specific axes. - -Please check :ref:`How to plot convergence ` for usage. +.. currentmodule:: alchemlyb.visualisation -API Reference -------------- -.. autofunction:: alchemlyb.visualisation.plot_convergence \ No newline at end of file +.. autofunction:: plot_convergence \ No newline at end of file diff --git a/docs/visualisation/alchemlyb.visualisation.plot_dF_state.rst b/docs/visualisation/alchemlyb.visualisation.plot_dF_state.rst index a96607be..a209339f 100644 --- a/docs/visualisation/alchemlyb.visualisation.plot_dF_state.rst +++ b/docs/visualisation/alchemlyb.visualisation.plot_dF_state.rst @@ -1,35 +1,6 @@ -.. _visualisation_plot_dF_state: - -Plot dF states from multiple estimators +alchemlyb.visualisation.plot\_dF\_state ======================================= -The function :func:`~alchemlyb.visualisation.plot_dF_state` allows the user to -plot and compare the free energy difference between states ("dF") from various -kinds of :class:`~alchemlyb.estimators`. - -To compare the dF states of a single alchemical transformation among various -:class:`~alchemlyb.estimators`, the user can pass a list of `estimators`. (e.g. -`estimators` = [:class:`~alchemlyb.estimators.TI`, -:class:`~alchemlyb.estimators.BAR`, :class:`~alchemlyb.estimators.MBAR`]) - -To compare the dF states of a multiple alchemical transformations, results from -the same :class:`~alchemlyb.estimators` can be concatenated into a list, which -is then bundled to to another list of different :class:`~alchemlyb.estimators`. -(e.g. `estimators` = [(:class:`~alchemlyb.estimators.TI`, -:class:`~alchemlyb.estimators.TI`), (:class:`~alchemlyb.estimators.BAR`, -:class:`~alchemlyb.estimators.BAR`), (:class:`~alchemlyb.estimators.MBAR`, -:class:`~alchemlyb.estimators.MBAR`)]) - -The figure could be plotted in *portrait* or *landscape* mode by setting the -`orientation`. `nb` is used to control the number of dF states in one row. -The user could pass a list of strings to `labels` to name the -:class:`~alchemlyb.estimators` or a list of strings to `colors` to color -the estimators differently. The unit in the y axis could be labelled to other -units by setting `units`, which by default is :math:`kT`. - -Please check :ref:`How to plot dF states ` for a complete -example. +.. currentmodule:: alchemlyb.visualisation -API Reference -------------- -.. autofunction:: alchemlyb.visualisation.plot_dF_state +.. autofunction:: plot_dF_state \ No newline at end of file diff --git a/docs/visualisation/alchemlyb.visualisation.plot_mbar_overlap_matrix.rst b/docs/visualisation/alchemlyb.visualisation.plot_mbar_overlap_matrix.rst index a4de37da..bad154d5 100644 --- a/docs/visualisation/alchemlyb.visualisation.plot_mbar_overlap_matrix.rst +++ b/docs/visualisation/alchemlyb.visualisation.plot_mbar_overlap_matrix.rst @@ -1,18 +1,6 @@ -.. _visualisation_plot_mbar_overlap_matrix: +alchemlyb.visualisation.plot\_mbar\_overlap\_matrix +=================================================== -Plot Overlap Matrix from MBAR -============================= +.. currentmodule:: alchemlyb.visualisation -The function :func:`~alchemlyb.visualisation.plot_mbar_overlap_matrix` allows -the user to plot the overlap matrix from -:attr:`~alchemlyb.estimators.MBAR.overlap_matrix`. The user can pass -:class:`matplotlib.axes.Axes` into the function to have the overlap maxtrix -drawn on a specific axes. The user could also specify a list of lambda states -to be skipped when labelling the states. - -Please check :ref:`How to plot MBAR overlap matrix ` for -usage. - -API Reference -------------- -.. autofunction:: alchemlyb.visualisation.plot_mbar_overlap_matrix \ No newline at end of file +.. autofunction:: plot_mbar_overlap_matrix \ No newline at end of file diff --git a/docs/visualisation/alchemlyb.visualisation.plot_ti_dhdl.rst b/docs/visualisation/alchemlyb.visualisation.plot_ti_dhdl.rst index 6f9844d7..a15347bc 100644 --- a/docs/visualisation/alchemlyb.visualisation.plot_ti_dhdl.rst +++ b/docs/visualisation/alchemlyb.visualisation.plot_ti_dhdl.rst @@ -1,22 +1,6 @@ -.. _visualisation_plot_mbar_plot_ti_dhdl: +alchemlyb.visualisation.plot\_ti\_dhdl +====================================== -Plot dhdl from TI -================= +.. currentmodule:: alchemlyb.visualisation -The function :func:`~alchemlyb.visualisation.plot_ti_dhdl` allows -the user to plot the dhdl from :class:`~alchemlyb.estimators.TI` estimator. -Several :class:`~alchemlyb.estimators.TI` estimators could be passed to the -function to give a concerted picture of the whole alchemical transformation. -When custom labels are desirable, the user could pass a list of strings to the -*labels* for labelling each alchemical transformation differently. The color of -each alchemical transformation could also be set by passing a list of color -string to the *colors*. The unit in the y axis could be labelled to other units -by setting *units*, which by default is :math:`kT`. The user can pass -:class:`matplotlib.axes.Axes` into the function to have the dhdl drawn on a -specific axes. - -Please check :ref:`How to plot TI dhdl ` for usage. - -API Reference -------------- -.. autofunction:: alchemlyb.visualisation.plot_ti_dhdl \ No newline at end of file +.. autofunction:: plot_ti_dhdl \ No newline at end of file