Multi-core Markov-chain Monte Carlo (MC³)

A python implementation of the Markov-chain Monte Carlo algorithm.

Table of Contents:

• Team Members
• Code Description
• Install and Compile
• Interpreter Quick Examples
• Shell Quick Examples
• System Requirements
• Further Reading
• Be Kind
• License

Team Members:

• Patricio Cubillos (author) [email protected]
• Madison Stemm
• Joe Harrington
• AJ Foster
• Nate B. Lust

Code Description:

TL;DR: You provide the data and the model function, I'll give you the parameter posteriors.

MC³ provides a set of routines to sample the posterior probability distributions for the model-fitting parameters. To do so it uses Bayesian Inference through a Markov-chain Monte Carlo algorithm following, either, Differential-Evolution (recomended) or Metropolis Random Walk. It handles Bayesian priors, Gelman-Rubin convergence test, or shared parameters (p_j=p_i) over the MCMC iterations. You can run MC³ interactively through the python interpreter or from the terminal command line.

Get the extended MC3 documentation here.

Main modules summary (project's source code):

• mcmc.py

Core module that implements the MCMC algorithm.

• mccubed.py

Wrapper of mcmc.py that provides support for MPI multiprocessing and use of configuration files.

• func.py

Subroutine of mccubed.py that handles the model function in parallel under MPI.

• mcutils.py

Utility functions used in the project's code.

• mcplots.py

A set of functions to plot parameter trace curves, pairwise posterior dostributions, and marginalized posterior histograms.

Install and Compile:

To obtain the latest MCcubed code, clone the repository to your local machine with the following terminal commands. First, create a top-level directory to place the code:

mkdir MC3_demo/  
cd MC3_demo/  
topdir=`pwd`

Clone the repository to your working directory:

git clone https://github.com/pcubillos/MCcubed 

Compile the C code:

cd $topdir/MCcubed/src/cfuncs  
make  

To remove the program binaries, execute (from the respective directories):

make clean

The examples folder contains detailed examples to run MC³ from an interactive Python sesion and from the shell. But, here below are a couple of quick demo runs anyways.

Interpreter Quick Example:

import sys
import numpy as np
import matplotlib.pyplot as plt
sys.path.append("../MCcubed/src/")
import mccubed as mc3
import mcplots as mp

# Get function to model (and sample):
sys.path.append("../MCcubed/examples/")
from quadratic import quad

# Create a synthetic dataset:
x = np.linspace(0, 10, 100)          # Independent model variable
p0 = 3, -2.4, 0.5                    # True-underlying model parameters
y = quad(p0, x)                      # Noiseless model
uncert = np.sqrt(np.abs(y))          # Data points uncertainty
error = np.random.normal(0, uncert)  # Noise for the data
data = y + error                     # Noisy data set


# To see the MCMC docstring run:
help(mc3.mcmc)

# Fit the quad polynomial coefficients:
params = np.array([ 20.0, -2.0, 0.1])  # Initial guess of fitting params.

# Run the MCMC:
allp, bp = mc3.mcmc(data, uncert, func=quad, indparams=[x],
                    params=params, numit=3e4, burnin=100)

# That's it, now let's see the results:
y0 = quad(params, x)  # Initial guess values
y1 = quad(bp,     x)  # MCMC best fitting values

plt.figure(10)
plt.clf()
plt.plot(x, y, "-k", label='true')
plt.errorbar(x, data, yerr=uncert, fmt=".b", label='data')
plt.plot(x, y0, "-g", label='Initial guess')
plt.plot(x, y1, "-r", label='MCMC best fit')
plt.legend(loc="best")
plt.xlabel("X")
plt.ylabel("quad(x)")
plt.suptitle("quadratic fit")
plt.savefig("quad_fit.png")

# The module mcplots provides helpful plotting functions:
# Plot trace plot:
parname = ["constant", "linear", "quadratic"]
mp.trace(allp, title="Fitting-parameter Trace Plots", parname=parname,
         savefile="quad_trace.png")

# Plot pairwise posteriors:
mp.pairwise(allp, title="Pairwise posteriors", parname=parname,
         savefile="quad_pairwise.png")

# Plot marginal posterior histograms:
mp.histogram(allp, title="Marginal posterior histograms", parname=parname,
         savefile="quad_hist.png")

Shell Quick Example:

Create a working directory to place the files and execute the program:

cd $topdir
mkdir run
cd run

Copy the demo files to run MC3 (configuration and data files):

cp $topdir/MCcubed/examples/example02/* .

Call the MC3 executable, providing the configuration file as command-line argument:

mpirun $topdir/MCcubed/src/mccubed.py -c demc_demo.cfg

System Requirements:

This version of the code was implemented with Python 2.7.6. In addition to the basic built-in Python libraries, you will need:

• numpy
• matplotlib
• mpi4py (only required for multi-core runs)

Further Reading:

Differential-evolution Markov chain algorithm: ter Braak 2006: A Markov Chain Monte Carlo version of the genetic algorithm Differential Evolution.

Wavelet Likelihood: Carter & Winn 2009: Parameter Estimation from Time-series Data with Correlated Errors.

Be Kind:

Please reference this paper if you found this module useful for your research:
Cubillos et al. 2014: On the Correlated Noise Analyses Applied to Exoplanet Light Curves, in preparation.
Thanks!

License:

Multi-Core Markov-chain Monte Carlo (MC3), a code to estimate model-parameter best-fitting values and Bayesian posterior distributions.

This project was completed with the support of the NASA Planetary Atmospheres Program, grant NNX12AI69G, held by Principal Investigator Joseph Harrington. Principal developers included graduate student Patricio E. Cubillos and programmer Madison Stemm. Statistical advice came from Thomas J. Loredo and Nate B. Lust.

Copyright (C) 2015 University of Central Florida. All rights reserved.

This is a test version only, and may not be redistributed to any third party. Please refer such requests to us. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Our intent is to release this software under an open-source, reproducible-research license, once the code is mature and the first research paper describing the code has been accepted for publication in a peer-reviewed journal. We are committed to development in the open, and have posted this code on github.com so that others can test it and give us feedback. However, until its first publication and first stable release, we do not permit others to redistribute the code in either original or modified form, nor to publish work based in whole or in part on the output of this code. By downloading, running, or modifying this code, you agree to these conditions. We do encourage sharing any modifications with us and discussing them openly.

We welcome your feedback, but do not guarantee support. Please send feedback or inquiries to:

Patricio Cubillos [email protected]
Joseph Harrington [email protected]

or alternatively,

Joseph Harrington and Patricio Cubillos
UCF PSB 441
4111 Libra Drive
Orlando, FL 32816-2385
USA

Thank you for using MC3!