Merge pull request #242 from choderalab/update-readme

pymbar 3.0.0 release; clean up README and docs

README.md

@@ -6,81 +6,63 @@
 pymbar
 ======
 
-Python implementation of the multistate Bennett acceptance ratio (MBAR) method for estimating expectations and free energy differences.  See our [Docs](http://pymbar.readthedocs.org/en/latest/).
+Python implementation of the [multistate Bennett acceptance ratio (MBAR)](http://www.alchemistry.org/wiki/Multistate_Bennett_Acceptance_Ratio) method for estimating expectations and free energy differences from equilibrium samples from multiple probability densities.
+See our [docs](http://pymbar.readthedocs.org/en/latest/).
 
 
 Installation
 ------------
 
-The easiest way to install `pymbar` is via [conda](http://conda.pydata.org), a binary package installer that comes with the [Anaconda Scientific Python distribution](https://store.continuum.io/cshop/anaconda/):
-```tcsh
-conda install -c https://conda.binstar.org/omnia pymbar
+The easiest way to install the `pymbar` release is via [conda](http://conda.pydata.org):
+```bash
+conda install -c omnia pymbar
+```
+You can also install `pymbar` from the [Python package index](https://pypi.python.org/pypi/pymbar) using `pip`:
+```bash
+pip install pymbar
+```
+The development version can be installed directly from github via `pip`:
+```bash
+pip install git+https://github.com/choderalab/pymbar.git
 ```
-
-Besides conda, you can also install `pymbar` using `pip` (`pip install pymbar`) or directly from the source directory (`python setup.py install`).
-
 
 Usage
 -----
 
-Basic usage involves importing pymbar, loading data, and constructing an MBAR object from the reduced potential of simulation or experimental data:
+Basic usage involves importing `pymbar` and constructing an `MBAR` object from the [reduced potential](http://www.alchemistry.org/wiki/Multistate_Bennett_Acceptance_Ratio#Reduced_potential) of simulation or experimental data.
 
+Suppose we sample a 1D harmonic oscillator from a few thermodynamic states:
 ```python
->>> from pymbar import MBAR, testsystems
->>> x_k, u_kn, N_k, s_n = testsystems.HarmonicOscillatorsTestCase().sample()
->>> mbar = MBAR(u_kn, N_k)
+>>> from pymbar import testsystems
+>>> [x_n, u_kn, N_k, s_n] = testsystems.HarmonicOscillatorsTestCase().sample()
 ```
+We have the `nsamples` sampled oscillator positions `x_n` (with samples from all states concatenated), [reduced potentials](http://www.alchemistry.org/wiki/Multistate_Bennett_Acceptance_Ratio#Reduced_potential) in the `(nstates,nsamples)` matrix `u_kn`, number of samples per state in the `nsamples` array `N_k`, and indices `s_n` denoting which thermodynamic state each sample was drawn from.
 
-Next, we extract the dimensionless free energy differences and uncertainties:
-
+To analyze this data, we first initialize the `MBAR` object:
 ```python
->>> (Deltaf_ij_estimated, dDeltaf_ij_estimated, Theta_ij) = mbar.getFreeEnergyDifferences()
+>>> mbar = MBAR(u_kn, N_k)
 ```
-
-or compute expectations of given observables A(x) for all states:
-
+Estimating dimensionless free energy differences between the sampled thermodynamic states and their associated uncertainties (standard errors) simply requires a call to `getFreeEnergyDifferences()`:
 ```python
->>> (A_k_estimated, dA_k_estimated) = mbar.computeExpectations(x_k)
+>>> (Deltaf_ij, dDeltaf_ij, Theta_ij) = mbar.getFreeEnergyDifferences()
 ```
-See the help for these individual methods for more information on exact usage; in Python or IPython, you can view the docstrings with `help()`.  
-Additional examples can be found in [pymbar-examples](http://github.com/choderalab/pymbar-examples/).  Note that the example for free energy calculations found in pymbar-examples/alchemical-free-energy has moved to https://github.com/MobleyLab/alchemical-analysis
-
-
-Prerequisites
--------------
+Here, `Deltaf_ij[i,j]` is the dimensionless free energy difference `f_j - f_i`, `dDeltaf_ij[i,j]` is the standard error in this estimate, and `Theta_ij` a covariance matrix that can be used to propagate error into quantities derived from the free energies.
 
-To install and run pymbar requires the following:
-
-* Python 2.7 or later: http://www.python.org/
-* NumPy: http://numpy.scipy.org/
-* SciPy: http://www.scipy.org/
-* NumExpr: https://github.com/pydata/numexpr
-* six
-* nose
-* Some optional graphing functionality in the tests requires the matplotlib library: http://matplotlib.sourceforge.net/
+Expectations and associated uncertainties can easily be estimated for observables `A(x)` for all states:
+```python
+>>> A_kn = x_kn # use position of harmonic oscillator as observable
+>>> (EA_k, dEA_k) = mbar.computeExpectations(A_kn)
+```
+where `EA_k[k]` is the estimated expectation of the mean oscillator position in thermodynamic state `k`.
 
+See the docstring help for these individual methods for more information on exact usage; in Python or IPython, you can view the docstrings with `help()`.  
 
 Authors
 -------
-* John D. Chodera <choderaj@mskcc.org>
+* Kyle A. Beauchamp <kyle.beauchamp@choderalab.org>
+* John D. Chodera <john.chodera@choderalab.org>
+* Levi N. Naden <levi.naden@choderalab.org>
 * Michael R. Shirts <michael.shirts@virginia.edu>
-* Kyle A. Beauchamp <beauchak@mskcc.org>
-
-
-Manifest
---------
-
-This archive contains the following files:
-
-* `README.md` - this file
-* `LICENSE` - a copy of the GNU General Public License version 2 covering this code
-* `pymbar/` - Python MBAR package
-* `examples/` - examples of applications of MBAR to various types of calculations
-  See the README.md in that folder for more information
-* `docs/` - sphinx documetation
-* `devtools/` - travis CI and conda configuration files
-
-
 
 References
 ----------
@@ -93,16 +75,18 @@ References
 
   Chodera JD, Swope WC, Pitera JW, Seok C, and Dill KA. Use of the weighted histogram analysis method for the analysis of simulated and parallel tempering simulations. J. Chem. Theor. Comput. 3(1):26-41 (2007).  [DOI](http://dx.doi.org/10.1021/ct0502864)
 
+* The automatic equilibration detection method provided in `pymbar.timeseries.detectEquilibration()` is described here:
+
+  Chodera JD. A simple method for automated equilibration detection in molecular simulations. J. Chem. Theor. Comput. 12:1799, 2016.  [DOI](http://dx.doi.org/10.1021/acs.jctc.5b00784)
 
 License
 -------
 
-Pymbar is free software and is licensed under the GPLv2 license.
+`pymbar` is free software and is licensed under the LGPLv2 license.
 
 
 Thanks
 ------
-
 We would especially like to thank a large number of people for helping us identify issues
 and ways to improve `pymbar`, including Tommy Knotts, David Mobley, Himanshu Paliwal,
 Zhiqiang Tan, Patrick Varilly, Todd Gingrich, Aaron Keys, Anna Schneider, Adrian Roitberg,

docs/conf.py

@@ -46,7 +46,8 @@
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx',
               'sphinx.ext.todo', 'sphinx.ext.pngmath', 'sphinx.ext.ifconfig',
               'numpydoc', 'sphinx.ext.inheritance_diagram',
-              'sphinx.ext.autosummary', 'sphinx.ext.extlinks', ]
+              'sphinx.ext.autosummary', 'sphinx.ext.extlinks',
+              'sphinxcontrib.bibtex']
 
 autosummary_generate = True
 autodoc_default_flags = ['members', 'inherited-members']
@@ -312,4 +313,3 @@
 
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #texinfo_no_detailmenu = False
-

docs/getting_started.rst

@@ -3,101 +3,42 @@
 Getting started
 ###############
 
-Dependencies
-============
-
-``pymbar`` requires ``numpy`` and ``scipy``. You'll also need a working C
-compiler and build environment, to compile various C-level extensions.
-
-Easy Way (Recommended)
-----------------------
-
-The easiest way to get all of the dependencies is to install one of the 
-pre-packaged scientific python distributes like `Enthought's Canopy 
-<https://www.enthought.com/products/canopy/>`_ or `Continuum's Anaconda 
-<https://store.continuum.io/>`_. These distributions already contain all of 
-the dependences, and are distributed via 1-click installers.
-
-Medium Way
-----------
-
-Linux
-++++++
-If you're on ubuntu and have root, you can install everything through your package manager. ::
-
-  $ sudo apt-get install python-dev python-numpy python-nose python-setuptools python-scipy
-
-Mac
-+++
-If you're on mac and want a package manager, you should be using `homebrew <http://mxcl.github.io/homebrew/>`_ and ``brews``'s python (see `this page <https://github.com/mxcl/homebrew/wiki/Homebrew-and-Python>`_ for details). The best way to install numpy and scipy with ``brew`` is to use
-samueljohn's tap. ::
-
-  $ brew tap samueljohn/python
-  $ brew install python
-  $ brew install numpy
-  $ brew install scipy
-
-Harder Way : Compiling from source (no root needed)
----------------------------------------------------
-
-If you don't already have a python installation you want to use, you can compile a new one. ::
-
-  $ wget http://www.python.org/ftp/python/2.7.5/Python-2.7.5.tgz
-  $ tar -xzvf Python-2.7.5.tgz
-  $ cd Python-2.7.5
-  $ ./configure --prefix=$HOME/local/python
-  $ make
-  $ make install
-
-  $ export PATH=$HOME/local/python/bin:$PATH
-
-If you don't have ``easy_install`` or ``pip`` yet, you can get them with ::
-
-  $ wget http://pypi.python.org/packages/source/s/setuptools/setuptools-0.6c11.tar.gz
-  $ tar -xzvf setuptools-0.6c11.tar.gz
-  $ cd setuptools-0.6c11.tar.gz
-  $ python setup.py install
-  $ easy_install pip
-
-Now you're home free ::
-
-  $ pip install numpy
-  $ pip install scipy
-
 Installing ``pymbar``
 =====================
 
-``pymbar`` currently runs best on Python 2.7.x; earlier versions of Python are not
-supported.  ``pymbar`` is developed and
-tested on mac and linux platforms. 
+conda (recommended)
+-------------------
 
-Easy Way (Recommended)
-----------------------
+The easiest way to install the ``pymbar`` release is via `conda <http://conda.pydata.org>`_:
 
-Just run ::
+  $ conda install -c omnia pymbar
 
-  $ pip install pymbar
+pip
+---
 
-Medium Way (Advanced Users Only)
-------------------------------------
-To get the latest unstable version, clone the source code repository from github::
+You can also install ``pymbar`` from the `Python package index <https://pypi.python.org/pypi/pymbar>`_ using ``pip``:
 
-  $ git clone git://github.com/choderalab/pymbar.git
+  $ pip install pymbar
 
-Then, in the directory containing the source code, you can install it with. ::
+Development version
+-------------------
 
-  $ python setup.py install
+The development version can be installed directly from github via ``pip``:
 
+  $ pip install git+https://github.com/choderalab/pymbar.git
 
 Running the tests
 =================
 Running the tests is a great way to verify that everything is working. The test
 suite uses `nose <https://nose.readthedocs.org/en/latest/>`_, which you can pick
-up via ``pip`` if you don't already have it. ::
+up via ``conda`` or ``pip`` if you don't already have it. ::
+
+  $ conda install --yes nose
+
+or
 
   $ pip install nose
-  
-Then enter the ``pymbar`` the source directory and run ::
 
-  $ nosetests
+You can then run the tests with:
 
+  $ nosetests -vv pymbar

docs/index.rst

@@ -6,8 +6,7 @@
 pymbar
 ======
 
-Python implementation of the multistate Bennett acceptance ratio (MBAR) method for estimating expectations and free energy differences
-
+Python implementation of the `multistate Bennett acceptance ratio (MBAR) <http://www.alchemistry.org/wiki/Multistate_Bennett_Acceptance_Ratio>`_ method for estimating expectations and free energy differences
 
 Documentation
 -------------
@@ -20,13 +19,11 @@ Documentation
    mbar
    timeseries
    testsystems
-
-
+   references
 
 Indices and tables
 ==================
 
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
-

docs/mbar.rst

@@ -1,8 +1,8 @@
 .. currentmodule:: pymbar.mbar
 
-The mbar module : :class:`pymbar.mbar`
+The :module:`mbar` module : :class:`MBAR`
 ======================================
 
-The mbar module contains the MBAR class, the key object in pymbar.
+The :module:`mbar` module contains the :class:`MBAR` class, which implements the `multistate Bennett acceptance ratio (MBAR) <http://www.alchemistry.org/wiki/Multistate_Bennett_Acceptance_Ratio>`_ method :cite:`shirts-chodera:jcp:2008:mbar`.
 
 .. automodule:: pymbar.mbar

docs/references.bib

@@ -0,0 +1,19 @@
+@article{shirts-chodera:jcp:2008:mbar,
+   author = {Michael R. Shirts and John D. Chodera},
+   title = {Statistically optimal analysis of samples from multiple equilibrium states},
+   journal = {Journal of Chemical Physics},
+   volume = {129},
+   pages = {124105},
+   year = {2008},
+   type = {Journal Article}
+}
+
+@article{chodera:jctc:2016:automatic-equilibration-detection,
+   author = {John D. Chodera},
+   title = {A simple method for automated equilibration detection in molecular simulations},
+   journal = {Journal of Chemical Theory and Computation},
+   volume = {12},
+   pages = {1799},
+   year = {2016},
+   type = {Journal Article}
+}

docs/rtd_requirements.txt

@@ -2,3 +2,4 @@ numpy
 nose
 numpydoc
 scipy
+sphinxcontrib-bibtex

docs/testsystems.rst

@@ -3,6 +3,13 @@
 The testsystems Module : :class:`pymbar.testsystems`
 ====================================================
 
-testsystems contains a number of test systems that you can use with pymbar.
+The ``pymbar.testsystems`` module contains a number of test systems with analytically or numerically computable expectations or free energies we use to validate its implementation.
+These test systems are also convenient to use if you want to easily generate synthetic data to experiment with the capabilities of ``pymbar``.
 
 .. automodule:: pymbar.testsystems
+
+.. automodule:: pymbar.testsystems.harmonic_oscillators
+.. automodule:: pymbar.testsystems.timeseries
+.. automodule:: pymbar.testsystems.exponential_distributions
+.. automodule:: pymbar.testsystems.gaussian_work
+.. automodule:: pymbar.testsystems.pymbar_datasets