Merge pull request #161 from kyleabeauchamp/ex3

Moved examples from pymbar-examples

examples/README.md

@@ -1,72 +1,16 @@
-pymbar/examples
-======
+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/).
+Examples illustrating the use of [MBAR](http://github.com/choderalab/pymbar) for various applications in computational and experimental chemistry.
 
-* `README.md` - this file
-* `harmonic-oscilllators.py` - a file  
-* `harmonic-oscilllators-distributions.py`
+Contents
+--------
 
-It also contains sample output from these scripts.
+* `alchemical-free-energy/` - example illustrating calculation of free energy difference from simulations of alchemical intermediates
+* `constant-force-optical-trap/` - calculation of PMF of dsDNA extension from constant-force optical trap experiments
+* `harmonic-oscillators/` - examples all of the functionality of pymbar, including validation of the distribution of error estimates. 
+* `heat-capacity/` - calculation of heat capacities using the fluctuation theorem, including Cv at interpolated temperatures.
+* `parallel-tempering-2dpmf/` - example illustrating computation of 2D PMF from parallel tempering data
+* `umbrella-sampling-pmf/` - example illustrating computation of 1D PMF from umbrella sampling data
 
-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.

examples/alchemical-free-energy/README.md

@@ -0,0 +1,82 @@
+Script: `alchemical_analysis.py`
+
+An illustration of MBAR applied to alchemical free energy
+calculations, and comparison of MBAR to a number of other free energy
+methods described in Paliwal and Shirts, J. Chem. Theory Comp, v. 7,
+4115-4134 (2011).
+
+See description in `gromacs/README.md`, `sire/README.md`, and `amber/README.md`.
+
+
+Help for `alchemical_analysis.py` (obtained with `python alchemical_analysis.py -h`) is:
+
+```Options:
+  -h, --help            show this help message and exit
+  -a SOFTWARE, --software=SOFTWARE
+                        Package's name the data files come from: Gromacs,
+                        Sire, or AMBER. Default: Gromacs.
+  -c, --cfm             The Curve-Fitting-Method-based consistency inspector.
+                        Default: False.
+  -d DATAFILE_DIRECTORY, --dir=DATAFILE_DIRECTORY
+                        Directory in which data files are stored. Default:
+                        Current directory.
+  -f BFORWREV, --forwrev=BFORWREV
+                        Plotting the free energy change as a function of time
+                        in both directions. The number of time points (an
+                        integer) is to be followed the flag. Default: 0
+  -g, --breakdown       Plotting the free energy differences evaluated for
+                        each pair of adjacent states for all methods. Default:
+                        False.
+  -i UNCORR_THRESHOLD, --threshold=UNCORR_THRESHOLD
+                        Perform the analysis with rather all the data if the
+                        number of uncorrelated samples is found to be less
+                        than this number. If 0 is given, the time series
+                        analysis will not be performed at all. Default: 50.
+  -k BSKIPLAMBDAINDEX, --koff=BSKIPLAMBDAINDEX
+                        Give a string of lambda indices separated by '-' and
+                        they will be removed from the analysis. (Another
+                        approach is to have only the files of interest present
+                        in the directory). Default: None.
+  -m METHODS, --methods=METHODS
+                        A list of the methods to esitimate the free energy
+                        with. Default: [TI, TI-CUBIC, DEXP, IEXP, BAR, MBAR].
+                        To add/remove methods to the above list provide a
+                        string formed of the method strings preceded with +/-.
+                        For example, '-ti_cubic+gdel' will turn methods into
+                        [TI, DEXP, IEXP, BAR, MBAR, GDEL]. 'ti_cubic+gdel', on
+                        the other hand, will call [TI-CUBIC, GDEL]. 'all'
+                        calls the full list of supported methods [TI, TI-
+                        CUBIC, DEXP, IEXP, GINS, GDEL, BAR, UBAR, RBAR, MBAR].
+  -o OUTPUT_DIRECTORY, --out=OUTPUT_DIRECTORY
+                        Directory in which the output files produced by this
+                        script will be stored. Default: Same as
+                        datafile_directory.
+  -p PREFIX, --prefix=PREFIX
+                        Prefix for datafile sets, i.e.'dhdl' (default).
+  -q SUFFIX, --suffix=SUFFIX
+                        Suffix for datafile sets, i.e. 'xvg' (default).
+  -r DECIMAL, --decimal=DECIMAL
+                        The number of decimal places the free energies are to
+                        be reported with. No worries, this is for the text
+                        output only; the full-precision data will be stored in
+                        'results.pickle'. Default: 3.
+  -s EQUILTIME, --skiptime=EQUILTIME
+                        Discard data prior to this specified time as
+                        'equilibration' data. Units picoseconds. Default: 0
+                        ps.
+  -t TEMPERATURE, --temperature=TEMPERATURE
+                        Temperature in K. Default: 298 K.
+  -u UNITS, --units=UNITS
+                        Units to report energies: 'kJ', 'kcal', and 'kBT'.
+                        Default: 'kJ'
+  -v, --verbose         Verbose option. Default: False.
+  -w, --overlap         Print out and plot the overlap matrix. Default: False.
+  -x, --ignoreWL        Do not check whether the WL weights are equilibrated.
+                        No log file needed as an accompanying input.
+  -y RELATIVE_TOLERANCE, --tolerance=RELATIVE_TOLERANCE
+                        Convergence criterion for the energy estimates with
+                        BAR and MBAR. Default: 1e-10.
+  -z INIT_WITH, --initialize=INIT_WITH
+                        The initial MBAR free energy guess; either 'BAR' or
+                        'zeroes'. Default: 'BAR'.
+```