README

Synopsis

BayesWHAM.py - a Bayesian implementation of the weighted histogram analysis method (WHAM) to make statistically optimal estimates of multidimensional molecular free energy surface (FES) from an ensemble of umbrella sampling simulations. The code functions in n-dimensions, natively supports uniform, symmetric Dirichlet, and Gaussian priors, and rigorously estimates uncertainties by Metropolis-Hastings sampling of the Bayes posterior. The source code may be straightforwardly modified to support arbitrary user-defined priors by augmenting two switch statements defining the MAP expression and the Metropolis acceptance criterion.

BayesWHAM_plotter.py - a utility code to plot the 1, 2, and 3-dimensional output of BayesWHAM.py

BayesReweight.py - a tool to project the unbiased FES calculated by BayesWHAM into any number of arbitrary variables beyond those in which umbrella sampling was conducted.

BayesReweight_plotter.py - a utility code to plot the 1, 2, and 3-dimensional output of BayesReweight.py

Version

v1.0 - 08/2016

Installation

No installation required. These are Python 2.7 scripts functions that can be called and executed directly from the Python interpreter.

I/O

Full details of required inputs, input files and formatting, and output files are provided in the headers of each script. Example calculations detailing the execution steps and providing all input and output files are detailed below.

./diala_phi_EXAMPLE/traj_aux__phi_psi - trajectories of projection variables [phi,psi] into which we wish to reweight the FES recorded over the course of each umbrella sampling calculation at the same frequency as those in ./diala_phi_EXAMPLE/traj; the projection variables are arbitrary and need not contain the umbrella sampling variable

We solve the generalized WHAM equations to a tolerance of 1E-15 under a Dirichlet prior with concentration parameter alpha = 2 (i.e., adding 1 pseudo count to each bin). Uncertainties are estimated by performing 1E6 rounds of Metropolis-Hastings sampling from the Bayes posterior and saving every 1E3 realizations. In practice, many more rounds of sampling should be performed until the log likelihood stabilizes indicating the Markov chain burn-in period has passed and samples are being drawn from the stationary distribution.

Copies of all files generated by this calculation are provided in ./diala_phi_EXAMPLE/BayesWHAM_OUTPUT

Reweighting of the biased simulation data and the free energy shifts calculated from solution of the generalized WHAM equations under the Dirichlet prior to estimate F(phi,psi). Phi and psi are backbone dihedral angles with range [-180 deg, 180 deg] and 360 deg periodicity. Within this projection we anticipate good sampling in the driven variable phi but not so in psi where exploration is reliant on spontaneous thermal fluctuations.

Copies of all files generated by this calculation are provided in ./diala_phi_EXAMPLE/BayesReweight_OUTPUT

./diala_phi_psi_EXAMPLE/hist - [phi,psi] histograms compiled over [phi,psi] trajectories in ./diala_phi_psi_EXAMPLE/traj in row major order

./diala_phi_psi_EXAMPLE/traj_aux__phi_psi_theta - trajectories of projection variables [phi,psi,theta] into which we wish to reweight the FES recorded over the course of each umbrella sampling calculation at the same frequency as those in ./diala_phi_psi_EXAMPLE/traj; the projection variables are arbitrary and need not contain the umbrella sampling variables

We solve the generalized WHAM equations to a tolerance of 1E-15 under a uniform prior. Uncertainties are estimated by performing 1E6 rounds of Metropolis-Hastings sampling from the Bayes posterior and saving every 1E3 realizations. In practice, many more rounds of sampling should be performed until the log likelihood stabilizes indicating the Markov chain burn-in period has passed and samples are being drawn from the stationary distribution.

Copies of all files generated by this calculation are provided in ./diala_phi_psi_EXAMPLE/BayesWHAM_OUTPUT

Reweighting of the biased simulation data and the free energy shifts calculated from solution of the generalized WHAM equations under the uniform prior to estimate F(phi,psi,theta). Phi, psi, and theta are backbone dihedral angles with range [-180 deg, 180 deg] and 360 deg periodicity. Within this projection we anticipate good sampling in the driven variables phi and psi but not so in theta where exploration is reliant on spontaneous thermal fluctuations.

Copies of all files generated by this calculation are provided in ./diala_phi_psi_EXAMPLE/BayesReweight_OUTPUT