From 09b4b458181f418f90f71e1ada427f20dacf3403 Mon Sep 17 00:00:00 2001 From: Oliver Beckstein Date: Tue, 28 Dec 2021 17:27:00 -0700 Subject: [PATCH 1/5] updated CHANGES and docs for release 0.6.0 --- CHANGES | 2 +- docs/api_principles.rst | 28 ++++++++-------------------- 2 files changed, 9 insertions(+), 21 deletions(-) diff --git a/CHANGES b/CHANGES index 60d483c8..3765e25f 100644 --- a/CHANGES +++ b/CHANGES @@ -13,7 +13,7 @@ The rules for this file: * release numbers follow "Semantic Versioning" https://semver.org ------------------------------------------------------------------------------ -??/??/2021 schlaicha, xiki-tempula, jhenin, ttjoseph, orbeckst +12/28/2021 schlaicha, xiki-tempula, jhenin, ttjoseph, orbeckst * 0.6.0 diff --git a/docs/api_principles.rst b/docs/api_principles.rst index 8d912d08..dbcb8c02 100644 --- a/docs/api_principles.rst +++ b/docs/api_principles.rst @@ -64,30 +64,18 @@ The library is structured as follows, following a similar style to │   ├── mbar_matrix.py │   ├── ti_dhdl.py │   └── ... - └── workflows + └── workflows ### WORK IN PROGRESS └── ... -The :mod:`~alchemlyb.parsing` submodule contains parsers for individual MD engines, since the output files needed to perform alchemical free energy calculations vary widely and are not standardized. -Each module at the very least provides an `extract_u_nk` function for extracting reduced potentials (needed for MBAR), as well as an `extract_dHdl` function for extracting derivatives required for thermodynamic integration. -Other helper functions may be exposed for additional processing, such as generating an XVG file from an EDR file in the case of GROMACS. -All `extract\_*` functions take similar arguments (a file path, -parameters such as temperature), and produce standard outputs -(:class:`pandas.DataFrame` for reduced potentials, :class:`pandas.Series` for derivatives). +* The :mod:`~alchemlyb.parsing` submodule contains parsers for individual MD engines, since the output files needed to perform alchemical free energy calculations vary widely and are not standardized. Each module at the very least provides an `extract_u_nk` function for extracting reduced potentials (needed for MBAR), as well as an `extract_dHdl` function for extracting derivatives required for thermodynamic integration. Other helper functions may be exposed for additional processing, such as generating an XVG file from an EDR file in the case of GROMACS. All `extract\_*` functions take similar arguments (a file path, parameters such as temperature), and produce standard outputs (:class:`pandas.DataFrame` for reduced potentials, :class:`pandas.Series` for derivatives). +* The :mod:`~alchemlyb.preprocessing` submodule features functions for subsampling timeseries, as may be desired before feeding them to an estimator. So far, these are limited to `slicing`, `statistical_inefficiency`, and `equilibrium_detection` functions, many of which make use of subsampling schemes available from :mod:`pymbar`. These functions are written in such a way that they can be easily composed as parts of complex processing pipelines. +* The :mod:`~alchemlyb.estimators` module features classes *a la* **scikit-learn** that can be initialized with parameters that determine their behavior and then "trained" on a `fit` method. MBAR, BAR, and thermodynamic integration (TI) as the major methods are all implemented. Correct error estimates require the use of time series with independent samples. +* The :mod:`~alchemlyb.convergence` submodule will feature convenience functions/classes for doing convergence analysis using a given dataset and a chosen estimator. +* The :mod:`~alchemlyb.postprocessing` submodule contains functions to calculate new quantities or express data in different units. +* The :mod:`~alchemlyb.visualization` submodule contains convenience plotting functions as known from, for example, `alchemical-analysis.py`_. +* The :mod:`~alchemlyb.workflows` submodule will contain complete analysis workflows that will serve as larger building blocks for complex analysis pipelines or a command line interface. -The :mod:`~alchemlyb.preprocessing` submodule features functions for subsampling timeseries, as may be desired before feeding them to an estimator. -So far, these are limited to `slicing`, `statistical_inefficiency`, and `equilibrium_detection` functions, many of which make use of subsampling schemes available from :mod:`pymbar`. -These functions are written in such a way that they can be easily composed as parts of complex processing pipelines. - -The :mod:`~alchemlyb.estimators` module features classes *a la* **scikit-learn** that can be initialized with parameters that determine their behavior and then "trained" on a `fit` method. -MBAR, BAR, and thermodynamic integration (TI) as the major methods are all implemented. -Correct error estimates require the use of time series with independent samples. - -The :mod:`~alchemlyb.convergence` submodule will feature convenience functions/classes for doing convergence analysis using a given dataset and a chosen estimator. - -The :mod:`~alchemlyb.postprocessing` submodule contains functions to calculate new quantities or express data in different units. - -The :mod:`~alchemlyb.visualization` submodule contains convenience plotting functions as known from, for example, `alchemical-analysis.py`_. All of these components lend themselves well to writing clear and flexible pipelines for processing data needed for alchemical free energy calculations, and furthermore allow for scaling up via libraries like `dask`_ or `joblib`_. From 671bcf31aaf42fc1f38efcd8fcf1f63f1fb41df4 Mon Sep 17 00:00:00 2001 From: Oliver Beckstein Date: Tue, 28 Dec 2021 17:30:43 -0700 Subject: [PATCH 2/5] support Python 3.10 (Keep Python 3.7 even though we could drop it as of two days ago.) --- .github/workflows/ci.yaml | 2 +- CHANGES | 3 +-- setup.py | 1 + 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index d80f06dd..5a5f10e1 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -22,7 +22,7 @@ jobs: fail-fast: true matrix: os: ["ubuntu-latest", "macOS-latest", "windows-latest"] - python-version: ["3.7", "3.8", "3.9"] + python-version: ["3.7", "3.8", "3.9", "3.10"] steps: - uses: actions/checkout@v2 diff --git a/CHANGES b/CHANGES index 3765e25f..3c6c588d 100644 --- a/CHANGES +++ b/CHANGES @@ -17,9 +17,8 @@ The rules for this file: * 0.6.0 -Changes - Enhancements + - support Python 3.10 - support for Interleaved Double-Wide Sampling (IDWS) in NAMD (PR #135). Windows may be split across NAMD .fepout files, allowing for interrupted and restarted simulations, but each window must be complete (issue #145). diff --git a/setup.py b/setup.py index d9930f6d..81f19a13 100755 --- a/setup.py +++ b/setup.py @@ -31,6 +31,7 @@ 'Programming Language :: Python :: 3.7', 'Programming Language :: Python :: 3.8', 'Programming Language :: Python :: 3.9', + 'Programming Language :: Python :: 3.10', 'Topic :: Scientific/Engineering', 'Topic :: Scientific/Engineering :: Bio-Informatics', 'Topic :: Scientific/Engineering :: Chemistry', From e95ac8dbc59139dca0219af7226235176f6f050c Mon Sep 17 00:00:00 2001 From: Oliver Beckstein Date: Tue, 28 Dec 2021 18:03:17 -0700 Subject: [PATCH 3/5] document convergence.convergence with summary table --- docs/convergence.rst | 16 +++++++++++++++- .../alchemlyb.convergence.convergence.rst | 12 ++++++++++++ src/alchemlyb/convergence/convergence.py | 13 +++++++------ 3 files changed, 34 insertions(+), 7 deletions(-) create mode 100644 docs/convergence/alchemlyb.convergence.convergence.rst diff --git a/docs/convergence.rst b/docs/convergence.rst index 14a1b480..55a4e270 100644 --- a/docs/convergence.rst +++ b/docs/convergence.rst @@ -1,3 +1,5 @@ +.. module:: alchemlyb.convergence + Using functions to estimate Convergence ======================================= @@ -31,4 +33,16 @@ Will give a plot looks like this A convergence plot of showing that the forward and backward has converged fully. -.. autofunction:: alchemlyb.convergence.forward_backward_convergence \ No newline at end of file + +Convergence functions +--------------------- + +The currently available connvergence functions: + +.. currentmodule:: alchemlyb.convergence + +.. autosummary:: + :toctree: convergence + + convergence + diff --git a/docs/convergence/alchemlyb.convergence.convergence.rst b/docs/convergence/alchemlyb.convergence.convergence.rst new file mode 100644 index 00000000..981c9b27 --- /dev/null +++ b/docs/convergence/alchemlyb.convergence.convergence.rst @@ -0,0 +1,12 @@ +Convergence analysis +==================== +.. automodule:: alchemlyb.convergence.convergence + +This module contains building blocks that perform a specific convergence analysis. They typically operate on lists of raw data and run estimators on these data sets. + + +API Reference +------------- +This submodule includes these convergence functions: + +.. autofunction:: alchemlyb.convergence.forward_backward_convergence diff --git a/src/alchemlyb/convergence/convergence.py b/src/alchemlyb/convergence/convergence.py index 4ece921c..e626f2dc 100644 --- a/src/alchemlyb/convergence/convergence.py +++ b/src/alchemlyb/convergence/convergence.py @@ -7,13 +7,13 @@ def forward_backward_convergence(df_list, estimator='mbar', num=10): - ''' The forward and backward convergence of the free energy estimate. + '''Forward and backward convergence of the free energy estimate. - Generate the free energy estimate as a function of time in both - directions, with the specified number of points in the time. For example, - setting `num` to 10 would give the forward convergence which is the free - energy estimate from the first 10%, 20%, 30% .. of the data. The - Backward would give the estimate from the last 10%, 20%, 30% .. of the + Generate the free energy estimate as a function of time in both directions, + with the specified number of equally spaced points in the time. For + example, setting `num` to 10 would give the forward convergence which is + the free energy estimate from the first 10%, 20%, 30%, ... of the data. The + Backward would give the estimate from the last 10%, 20%, 30%, ... of the data. Parameters @@ -44,6 +44,7 @@ def forward_backward_convergence(df_list, estimator='mbar', num=10): .. versionadded:: 0.6.0 + ''' logger = logging.getLogger('alchemlyb.convergence.' 'forward_backward_convergence') From aa1a87250537772313083ee0c6ddddbb25c4e572 Mon Sep 17 00:00:00 2001 From: Oliver Beckstein Date: Tue, 28 Dec 2021 18:08:40 -0700 Subject: [PATCH 4/5] add module links to docs --- docs/api_principles.rst | 8 ++++---- docs/estimators.rst | 2 ++ docs/parsing.rst | 3 +++ docs/postprocessing.rst | 2 ++ docs/preprocessing.rst | 3 +++ docs/visualisation.rst | 2 ++ 6 files changed, 16 insertions(+), 4 deletions(-) diff --git a/docs/api_principles.rst b/docs/api_principles.rst index dbcb8c02..7abbe7f7 100644 --- a/docs/api_principles.rst +++ b/docs/api_principles.rst @@ -52,7 +52,7 @@ The library is structured as follows, following a similar style to │   ├── mbar_.py │   ├── ti_.py │   └── ... - ├── convergence ### NOT IMPLEMENTED + ├── convergence │   ├── convergence.py │   └── ... ├── postprocessors @@ -71,9 +71,9 @@ The library is structured as follows, following a similar style to * The :mod:`~alchemlyb.parsing` submodule contains parsers for individual MD engines, since the output files needed to perform alchemical free energy calculations vary widely and are not standardized. Each module at the very least provides an `extract_u_nk` function for extracting reduced potentials (needed for MBAR), as well as an `extract_dHdl` function for extracting derivatives required for thermodynamic integration. Other helper functions may be exposed for additional processing, such as generating an XVG file from an EDR file in the case of GROMACS. All `extract\_*` functions take similar arguments (a file path, parameters such as temperature), and produce standard outputs (:class:`pandas.DataFrame` for reduced potentials, :class:`pandas.Series` for derivatives). * The :mod:`~alchemlyb.preprocessing` submodule features functions for subsampling timeseries, as may be desired before feeding them to an estimator. So far, these are limited to `slicing`, `statistical_inefficiency`, and `equilibrium_detection` functions, many of which make use of subsampling schemes available from :mod:`pymbar`. These functions are written in such a way that they can be easily composed as parts of complex processing pipelines. * The :mod:`~alchemlyb.estimators` module features classes *a la* **scikit-learn** that can be initialized with parameters that determine their behavior and then "trained" on a `fit` method. MBAR, BAR, and thermodynamic integration (TI) as the major methods are all implemented. Correct error estimates require the use of time series with independent samples. -* The :mod:`~alchemlyb.convergence` submodule will feature convenience functions/classes for doing convergence analysis using a given dataset and a chosen estimator. -* The :mod:`~alchemlyb.postprocessing` submodule contains functions to calculate new quantities or express data in different units. -* The :mod:`~alchemlyb.visualization` submodule contains convenience plotting functions as known from, for example, `alchemical-analysis.py`_. +* The :mod:`~alchemlyb.convergence` submodule features convenience functions/classes for doing convergence analysis using a given dataset and a chosen estimator. +* The :mod:`~alchemlyb.postprocessors` submodule contains functions to calculate new quantities or express data in different units. +* The :mod:`~alchemlyb.visualisation` submodule contains convenience plotting functions as known from, for example, `alchemical-analysis.py`_. * The :mod:`~alchemlyb.workflows` submodule will contain complete analysis workflows that will serve as larger building blocks for complex analysis pipelines or a command line interface. diff --git a/docs/estimators.rst b/docs/estimators.rst index d1eceebb..af3476f1 100644 --- a/docs/estimators.rst +++ b/docs/estimators.rst @@ -1,3 +1,5 @@ +.. module:: alchemlyb.estimators + .. _estimators: Using estimators to obtain free energies diff --git a/docs/parsing.rst b/docs/parsing.rst index 4af2d65b..c3a4181c 100644 --- a/docs/parsing.rst +++ b/docs/parsing.rst @@ -1,3 +1,6 @@ +.. module:: alchemlyb.parsing + + Parsing data files ================== **alchemlyb** features parsing submodules for getting raw data from different software packages into common data structures that can be used directly by its :ref:`subsamplers ` and :ref:`estimators `. diff --git a/docs/postprocessing.rst b/docs/postprocessing.rst index d7451108..e6e4dc80 100644 --- a/docs/postprocessing.rst +++ b/docs/postprocessing.rst @@ -1,3 +1,5 @@ +.. module:: alchemlyb.postprocessors + .. _postprocessing: Tools for postprocessing diff --git a/docs/preprocessing.rst b/docs/preprocessing.rst index 44ba8baa..dcd2ad19 100644 --- a/docs/preprocessing.rst +++ b/docs/preprocessing.rst @@ -1,3 +1,6 @@ +.. module:: alchemlyb.preprocessing + + Preprocessing datasets ====================== It is often the case that some initial pre-processing of raw datasets are desirable before feeding these to an estimator. diff --git a/docs/visualisation.rst b/docs/visualisation.rst index 2390cc63..e25e1266 100644 --- a/docs/visualisation.rst +++ b/docs/visualisation.rst @@ -1,3 +1,5 @@ +.. module:: alchemlyb.visualisation + Visualisation of the results ============================ It is quite often that the user want to visualise the results to gain From f1efb6cd5edda7685c034f3a0875ab18d465599d Mon Sep 17 00:00:00 2001 From: Oliver Beckstein Date: Tue, 28 Dec 2021 18:18:39 -0700 Subject: [PATCH 5/5] add link to GitHub Discussions forum - in docs - in README (update with the Getting Involved section from docs) --- README.rst | 43 +++++++++++++++++++++++++++++++------------ docs/index.rst | 13 ++++++++++--- 2 files changed, 41 insertions(+), 15 deletions(-) diff --git a/README.rst b/README.rst index 51fca4b4..3ade4108 100644 --- a/README.rst +++ b/README.rst @@ -11,15 +11,41 @@ includes: molecular dynamics engines such as `GROMACS`_, `AMBER`_, `NAMD`_ and `other simulation codes`_. -2. Subsamplers for obtaining uncorrelated samples from timeseries data. +2. Subsamplers for obtaining uncorrelated samples from timeseries data + (including extracting independent, equilibrated samples + [Chodera2016]_ as implemented in the pymbar_ package). 3. Estimators for obtaining free energies directly from this data, using best-practices approaches for multistate Bennett acceptance ratio (MBAR) - [Shirts2008]_ and thermodynamic integration (TI). + [Shirts2008]_ and BAR (from pymbar_) and thermodynamic integration (TI). -In particular, it uses internally the excellent `pymbar -`_ library for performing MBAR and extracting -independent, equilibrated samples [Chodera2016]_. +.. _GROMACS: http://www.gromacs.org/ +.. _AMBER: http://ambermd.org/ +.. _NAMD: http://www.ks.uiuc.edu/Research/namd/ +.. _`other simulation codes`: https://alchemlyb.readthedocs.io/en/latest/parsing.html +.. _`pymbar`: http://pymbar.readthedocs.io/ + + +Getting involved +---------------- + +Contributions of all kinds are very welcome. + +If you have questions or want to discuss alchemlyb please post in the `alchemlyb Discussions`_. + +If you have bug reports or feature requests then please get in touch with us through the `Issue Tracker`_. + +We also welcome code contributions: have a look at our `Developer Guide`_. Open an issue with the proposed fix or change in the `Issue Tracker`_ and submit a pull request against the `alchemistry/alchemlyb`_ GitHub repository. + +.. _`alchemlyb Discussions`: https://github.com/alchemistry/alchemlyb/discussions +.. _`Developer Guide`: https://github.com/alchemistry/alchemlyb/wiki/Developer-Guide +.. _`Issue Tracker`: https://github.com/alchemistry/alchemlyb/issues +.. _`alchemistry/alchemlyb`: https://github.com/alchemistry/alchemlyb + + + +References +---------- .. [Shirts2008] Shirts, M.R., and Chodera, J.D. (2008). Statistically optimal analysis of samples from multiple equilibrium states. The Journal of Chemical @@ -29,14 +55,7 @@ independent, equilibrated samples [Chodera2016]_. Equilibration Detection in Molecular Simulations. Journal of Chemical Theory and Computation 12, 1799–1805. -.. _GROMACS: http://www.gromacs.org/ -.. _AMBER: http://ambermd.org/ - -.. _NAMD: http://www.ks.uiuc.edu/Research/namd/ - -.. _`other simulation codes`: https://alchemlyb.readthedocs.io/en/latest/parsing.html - .. |doi| image:: https://zenodo.org/badge/68669096.svg :alt: Zenodo DOI :scale: 100% diff --git a/docs/index.rst b/docs/index.rst index f9b36240..6d42c6a3 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -54,10 +54,17 @@ The pandas_ package (one of our other primary dependencies) also follows `NEP 29 .. _contact: -Contributing ------------- -Contributions are very welcome. If you have bug reports or feature requests or questions then please get in touch with us through the `Issue Tracker`_. We also welcome code contributions: have a look at our `Developer Guide`_ and submit a pull request against the `alchemistry/alchemlyb`_ GitHub repository. +Getting involved +---------------- +Contributions of all kinds are very welcome. +If you have questions or want to discuss alchemlyb please post in the `alchemlyb Discussions`_. + +If you have bug reports or feature requests then please get in touch with us through the `Issue Tracker`_. + +We also welcome code contributions: have a look at our `Developer Guide`_. Open an issue with the proposed fix or change in the `Issue Tracker`_ and submit a pull request against the `alchemistry/alchemlyb`_ GitHub repository. + +.. _`alchemlyb Discussions`: https://github.com/alchemistry/alchemlyb/discussions .. _`Developer Guide`: https://github.com/alchemistry/alchemlyb/wiki/Developer-Guide .. _`Issue Tracker`: https://github.com/alchemistry/alchemlyb/issues .. _`alchemistry/alchemlyb`: https://github.com/alchemistry/alchemlyb