Merge pull request #181 from alchemistry/prep-release-060

prepare release 0.6.0
alchemistry · Dec 29, 2021 · a8ac1a1 · a8ac1a1
2 parents a1c0b09 + f1efb6c
commit a8ac1a1
Show file tree

Hide file tree

Showing 14 changed files with 100 additions and 47 deletions.
diff --git 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
@@ -13,13 +13,12 @@ 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
 
-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/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
-<http://pymbar.readthedocs.io/>`_ 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/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
@@ -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 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.
 
-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`_.
 

diff --git 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
+
+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
@@ -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/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/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

diff --git 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 <subsampling>` and :ref:`estimators <estimators>`.

diff --git 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
@@ -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
@@ -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

diff --git 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',

diff --git 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')