emcee

Seriously Kick-Ass MCMC

Once upon a time, there was an algorithm. This algorithm became very popular but it turned out that there were better ones. Some folks came up with a better one and some other folks implemented it in Python. It's a little crazy how much it rocks.

emcee is a GPLv2 licensed pure-Python implementation of Goodman & Weare’s Affine Invariant Markov chain Monte Carlo (MCMC) Ensemble sampler and these pages will show you how to use it.

This documentation won’t teach you too much about MCMC but there are a lot of resources available for that (try this one). We also posted a paper to the arXiv explaining the emcee algorithm in much greater detail.

Basic Usage

If you wanted to draw samples from a 10 dimensional Gaussian, you would do something like:

import numpy as np
import emcee

def lnprob(x, ivar):
    return -0.5 * np.sum(ivar * x ** 2)

ndim, nwalkers = 10, 100
ivar = 1. / np.random.rand(ndim)
p0 = [np.random.rand(ndim) for i in range(nwalkers)]

sampler = emcee.EnsembleSampler(nwalkers, ndim, lnprob, args=[ivar])
sampler.run_mcmc(p0, 1000)

Testimonials

“My research—modeling strong gravitational lenses with 10-20 free parameters—would be very difficult or impossible without emcee.”

—Shane Bussmann (CfA)

Since the initial release, emcee has been used in many published scientific studies. Here is an incomplete list:

• Dorman, Guhathakurta, Fardal, et al. (2012)
• Olofsson, Juhász, Henning, et al. (2012)
• Bovy, Rix, Liu, et al. (2012)
• Lang & Hogg (2012)
• Bovy, Rix, Hogg, et al. (2012)
• Bussmann, Gurwell, Fu, et al. (2012)
• Brammer, Sánchez-Janssen, Labbé, et al. (2012)
• Brown, Rosenfeld, Andrews, et al. (2012)
• Bovy, Allende Prieto, Beers, et al. (2012)
• Roškar, Debattista, & Loebman (2012)
• Crossfield, Barman, Hansen, et al. (2012)
• Morton (2012)
• Monnier, Che, Zhao, et al. (2012)
• Huppenkothen, Watts, Uttley, et al. (2012)
• Cieza, Olofsson, Harvey, et al. (2013)
• Weisz, Fouesneau, Hogg, et al. (2013)
• Reis, Miller, Reynolds, et al. (2013)
• Sanders, & Fabian (2013)
• Akeret, Seehars, Amara, et al. (2012)
• Riechers, Bradford, Clements, et al. (2013)

Please let us know if your work should be included in this list or fork the repository and add it yourself.

User Guide

• Installation
  • Using pip
  • From source
  • Bleeding edge development version
  • Test the installation
• Quickstart
  • How to sample a multi-dimensional Gaussian
• Advanced Patterns
  • Incrementally saving progress
  • Multiprocessing
  • Arbitrary metadata blobs
  • Using MPI to distribute the computations
• Parallel-Tempering Ensemble MCMC
  • How To Sample a Multi-Modal Gaussian
  • Implementation Notes
• FAQ
  • What are “walkers”?
  • How should I initialize the walkers?
  • Troubleshooting
  • Attribution

API Documentation

• API
  • The Affine-Invariant Ensemble Sampler
  • The Parallel-Tempered Ensemble Sampler
  • Standard Metropolis-Hastings Sampler
  • Abstract Sampler Object
  • Utilities

Contributors

Author:

• Dan Foreman-Mackey (NYU)

Direct contributions to the code base:

• Alex Conley (U Colorado, Boulder)
• Will Meierjurgen Farr (Northwestern)
• David W. Hogg (NYU)
• Dustin Lang (Princeton/CMU)
• Phil Marshall (Oxford)
• Adrian Price-Whelan (Columbia)
• Jeremy Sanders (Cambridge)
• Joe Zuntz (Oxford)

Comments, corrections & suggestions:

• Eric Agol (UWash)
• Jo Bovy (IAS)
• Jacqueline Chen (MIT)
• John Gizis (Delaware)
• Jonathan Goodman (NYU)
• Jennifer Piscionere (Vanderbilt)

Changelog

1.2.1 (upcoming)

• Added checks for parameters becoming infinite or NaN.
• Added checks for log-probability becoming NaN.

1.2.0 (2013-01-30)

• Added a parallel tempering sampler PTSampler.
• Added instructions and utilities for using emcee with MPI.
• Added flatlnprobability property to the EnsembleSampler object to be consistent with the flatchain property.
• Updated document for publication in PASP.
• Various bug fixes.

1.1.3 (2012-11-22)

• Made the packaging system more robust even when numpy is not installed.

1.1.2 (2012-08-06)

• Another bug fix related to metadata blobs: the shape of the final blobs object was incorrect and all of the entries would generally be identical because we needed to copy the list that was appended at each step. Thanks goes to Jacqueline Chen (MIT) for catching this problem.

1.1.1 (2012-07-30)

• Fixed bug related to metadata blobs. The sample function was yielding the blobs object even when it wasn’t expected.

1.1.0 (2012-07-28)

• Allow the lnprobfn to return arbitrary “blobs” of data as well as the log-probability.
• Python 3 compatible (thanks Alex Conley)!
• Various speed ups and clean ups in the core code base.
• New documentation with better examples and more discussion.

1.0.1 (2012-03-31)

• Fixed transpose bug in the usage of acor in EnsembleSampler.

1.0.0 (2012-02-15)

• Initial release.