Merge branch 'nk'

.travis.yml

@@ -1,28 +1,24 @@
 language: c
 
+#branches:
+#  only:
+#    - master  # Need to build the nk branch for current pymbar.
+
 install:
-  - source tools/ci/install.sh
+  - source devtools/ci/install.sh
   - export PYTHONUNBUFFERED=true
 
 script:
-  - export CC="gcc -std=c89"
-  - source deactivate
-  - conda install --yes conda-build
-  - conda build tools/conda-recipe
-  - source activate $python
-  - conda install $HOME/miniconda/conda-bld/linux-64/pymbar-dev-*
-  - conda list -e
-  - nosetests -vv
+  # this builds the binary, unpacks it, and runs the tests
+  - conda build devtools/conda-recipe
 
 env:
   matrix:
-    - python=2.7  CONDA_PY=27
-#    - python=3.3  CONDA_PY=33
+    - CONDA_PY=2.7
 
   global:
     # encrypted BINSTAR_TOKEN for push of dev package to binstar
     - secure: "lu3EsyPF+woAABbZyctdFUPfTkAUOyC7k7LsDmWBMrV6ctpvYkomDFS65NAElXDOnmPzxMpn4+f0V2+tNqD4sM/9erDfM2MkJH+tRznNkAAZFoxbxeZCmzV4zSzNvAKlopasHSXt2mbhzbDnhrIToAssQZMHp13pNlBMEq86hKc="
 
 after_success:
-  - echo "after_success"
-  - source tools/ci/after_sucess.sh
+  - source devtools/ci/after_sucess.sh

README.md

@@ -6,14 +6,40 @@
 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) method for estimating expectations and free energy differences.  See our [Docs](http://pymbar.readthedocs.org/en/latest/).
 
 Authors
 -------
 * John D. Chodera <choderaj@mskcc.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
+* `tests/` - unit tests for the functionality
+* `docs/` - sphinx documetation
+* `devtools/` - travis CI and conda configuration files
+
+Prerequisites
+-------------
+
+The pymbar module requires the following:
+
+* Python 2.4 or later: http://www.python.org/
+* The `Python.h` header file (either installed via the Python installer, but a separate `python-dev` package on distributions like Ubunti)
+* the NumPy package: http://numpy.scipy.org/
+* the SciPy package: http://www.scipy.org/
+* Some optional graphing functionality in the tests requires the matplotlib library: http://matplotlib.sourceforge.net/
+
 Quickstart
 ----------
 
@@ -61,8 +87,9 @@ and add the directory containing this file to your PYTHONPATH environment variab
 # For tcsh
 setenv PYTHONPATH "/path/to/pymbar:$PYTHONPATH"
 # For bash
-export PYTHONPATH="/path/to/pymbar:$PYTHONPTH"
+export PYTHONPATH="/path/to/pymbar:$PYTHONPATH"
 ```
+
 Usage
 -----
 
@@ -92,27 +119,6 @@ Examples
 
 Several examples of applications of `pymbar` to various types of simulation data can be found in [pymbar-examples](http://github.com/choderalab/pymbar-examples/).
 
-Manifest
---------
-
-This archive contains the following files:
-
-* `README.md` - this file
-* `GPL` - a copy of the GNU General Public License version 2
-* `pymbar/` - Python MBAR package
-* `examples/` - examples of applications of MBAR to various types of experiments
-
-Prerequisites
--------------
-
-The pymbar module requires the following:
-
-* Python 2.6 or later: http://www.python.org/
-* the NumPy package: http://numpy.scipy.org/
-* the SciPy package: http://www.scipy.org/
-* Some optional graphing functionality in the tests requires the matplotlib library: http://matplotlib.sourceforge.net/
-
-Many of these packages are now standard in scientific Python installations or bundles, such as [Enthought Canopy](https://www.enthought.com/products/canopy/) or [continuum.io Anaconda](http://continuum.io/).
 
 Optimizations and improvements
 ------------------------------

devtools/ci/install.sh

@@ -0,0 +1,17 @@
+MINICONDA=Miniconda-latest-Linux-x86_64.sh
+MINICONDA_MD5=$(curl -s http://repo.continuum.io/miniconda/ | grep -A3 $MINICONDA | sed -n '4p' | sed -n 's/ *<td>\(.*\)<\/td> */\1/p')
+wget http://repo.continuum.io/miniconda/$MINICONDA
+if [[ $MINICONDA_MD5 != $(md5sum $MINICONDA | cut -d ' ' -f 1) ]]; then
+    echo "Miniconda MD5 mismatch"
+    exit 1
+fi
+bash $MINICONDA -b
+PIP_ARGS="-U"
+
+sudo ln -s /usr/bin/g++ /usr/bin/g++44
+export PATH=$HOME/miniconda/bin:$PATH
+
+conda update --yes conda
+conda config --add channels http://conda.binstar.org/omnia
+conda install --yes conda-build
+

tools/ci/requirements-conda.txt → devtools/ci/requirements-conda.txt

@@ -3,3 +3,4 @@ numpy
 scipy
 pip
 nose
+numexpr

tools/conda-recipe/meta.yaml → devtools/conda-recipe/meta.yaml

@@ -10,11 +10,22 @@ requirements:
     - numpy
     - scipy
     - setuptools
+    - numexpr    
   run:
     - python
     - cython
     - numpy
     - scipy
+    - numexpr
+
+test:
+  requires:
+    - nose
+    - setuptools    
+  imports:
+    - pymbar
+  commands:
+    - nosetests pymbar --with-doctest --doctest-tests -v
 
 about:
   home: https://github.com/choderalab/pymbar

examples/README.md

@@ -0,0 +1,72 @@
+pymbar/examples
+======
+
+This folder contains two examples illustrating application of MBAR to
+a set of harmonic oscillators, for which free energy differences and
+expectations can be computed analytically. More examples can be found
+in [pymbar-examples](http://github.com/choderalab/pymbar-examples/).
+
+* `README.md` - this file
+* `harmonic-oscilllators.py` - a file  
+* `harmonic-oscilllators-distributions.py`
+
+It also contains sample output from these scripts.
+
+Usage
+------
+
+* `harmonic-oscillators.py` - runs though all of the external functions for MBAR 
+  using data generated from harmonic oscillators
+
+** `harmonic-oscillators.py_output.txt` - sample output from `harmonic-oscillators.py`
+
+* `oscillators.pdf` - figure illustrating the overlap of the harmonic oscillators in this test.
+
+* `oscillators.m` - Matlab script to generate oscillators.pdf
+
+This script gives examples of how to call all externally accessible
+functionality in MBAR.  Since all samples are drawn from harmoinc
+oscillators, 
+
+ * `harmonic-oscillators-distributions.py` - test driver showing the
+  consistency of free energies and observable error estimates from the
+  normal distribution
+
+** `harmonic-oscillators-distributions.py_output.txt` - sample output from `harmonic-oscillators.py`
+
+** `QQdf.pdf` - QQ plots for the free energy differences
+
+** `QQMBARobserve.pdf` - QQ plots for the ensemble averages computing using MBAR
+
+** `QQstandardobserve.pdf` - QQ plots for the ensemble averages computing using standard averaging (which can't be done for the lone unsampled state
+
+** cumulative_probability_comparison_curves.pdf - another visualization comparing the standard normal distribution with the errors in the data normalized by the estimated uncertatity. 
+
+QQ plots give a straight line if the distributions agree.  In this
+case, we compare the distribution of errors from the analytical
+estimate divided by the estimated uncertainty to the analytical
+standard normal distribution.  In all cases except for distribution
+the positions sampled from the unsampled state, the QQ plot is linear
+to within noise.
+
+The [Anderson-Darling test](http://en.wikipedia.org/wiki/Anderson%E2%80%93Darling_test) printed out in the
+`harmonic-oscillators-distributions.py` code also gives a test of
+normality of the error estimates.
+
+Cutoffs for the statistic for the confidence intervals for known uncertainty and known mean are:
+
+* 15%  1.610
+* 10%  1.933
+* 5%   2.492
+* 2.5% 3.070
+* 1%   3.857
+
+However, since the sigma is generated using MBAR, then it has some
+uncertainty, and the statistic may be slightly different. 
+
+When the number of replicates becomes too high, there is a chance that
+the Anderson-Darling metric can be too sensitive, but the current
+level of 200 replicates is fine.
+
+Again, all results except the uncertainty of the position in the
+unsampled states are consistent with normal distribution of error.