API

This page details the methods and classes provided by the emcee module. The main entry point is through the EnsembleSampler object.

The Ensemble Sampler

Standard usage of emcee involves instantiating an EnsembleSampler.

class emcee.EnsembleSampler(nwalkers, dim, log_prob_fn, a=None, pool=None, moves=None, args=None, kwargs=None, postargs=None, threads=None, live_dangerously=None, runtime_sortingfn=None)

An ensemble MCMC sampler

Parameters:
  • nwalkers (int) – The number of Goodman & Weare “walkers”.
  • dim (int) – Number of dimensions in the parameter space.
  • log_prob_fn (callable) – A function that takes a vector in the parameter space as input and returns the natural logarithm of the posterior probability (up to an additive constant) for that position.
  • args (Optional) – A list of extra positional arguments for log_prob_fn. log_prob_fn will be called with the sequence log_pprob_fn(p, *args, **kwargs).
  • kwargs (Optional) – A dict of extra keyword arguments for log_prob_fn. log_prob_fn will be called with the sequence log_pprob_fn(p, *args, **kwargs).
  • pool (Optional) – An object with a map method that follows the same calling sequence as the built-in map function. This is generally used to compute the log-probabilities for the ensemble in parallel.
acceptance_fraction

The fraction of proposed steps that were accepted

compute_log_prob(coords=None)

Calculate the vector of log-probability for the walkers

Parameters:pos – (Optional[ndarray[…, ndim]]) The position vector in parameter space where the probability should be calculated. This defaults to the current position unless a different one is provided.

This method returns:

  • log_prob: A vector of log-probabilities with one entry for each walker in this sub-ensemble.
  • blob: The list of meta data returned by the log_post_fn at this position or None if nothing was returned.
get_autocorr_time(discard=0, thin=1, **kwargs)

Compute an estimate of the autocorrelation time for each parameter

Parameters:
  • thin (Optional[int]) – Use only every thin steps from the chain. The returned estimate is multiplied by thin so the estimated time is in units of steps, not thinned steps. (default: 1)
  • discard (Optional[int]) – Discard the first discard steps in the chain as burn-in. (default: 0)

Other arguments are passed directly to emcee.autocorr.integrated_time().

Returns:
The integrated autocorrelation time estimate for the
chain for each parameter.
Return type:array[ndim]
get_blobs(**kwargs)

Get the chain of blobs for each sample in the chain

Parameters:
  • flat (Optional[bool]) – Flatten the chain across the ensemble. (default: False)
  • thin (Optional[int]) – Take only every thin steps from the chain. (default: 1)
  • discard (Optional[int]) – Discard the first discard steps in the chain as burn-in. (default: 0)
Returns:

The chain of blobs.
Return type:

array[.., nwalkers]
get_chain(**kwargs)

Get the stored chain of MCMC samples

Parameters:
  • flat (Optional[bool]) – Flatten the chain across the ensemble. (default: False)
  • thin (Optional[int]) – Take only every thin steps from the chain. (default: 1)
  • discard (Optional[int]) – Discard the first discard steps in the chain as burn-in. (default: 0)
Returns:

The MCMC samples.
Return type:

array[.., nwalkers, ndim]
get_log_prob(**kwargs)

Get the chain of log probabilities evaluated at the MCMC samples

Parameters:
  • flat (Optional[bool]) – Flatten the chain across the ensemble. (default: False)
  • thin (Optional[int]) – Take only every thin steps from the chain. (default: 1)
  • discard (Optional[int]) – Discard the first discard steps in the chain as burn-in. (default: 0)
Returns:

The chain of log probabilities.
Return type:

array[.., nwalkers]
random_state

The state of the internal random number generator. In practice, it’s the result of calling get_state() on a numpy.random.mtrand.RandomState object. You can try to set this property but be warned that if you do this and it fails, it will do so silently.

reset()

Reset the bookkeeping parameters

run_mcmc(pos0, N, rstate0=None, log_prob0=None, **kwargs)

Iterate sample() for N iterations and return the result

Parameters:
  • pos0 – The initial position vector. Can also be None to resume from where :func:run_mcmc left off the last time it executed.
  • N – The number of steps to run.
  • log_prob0 (Optional[ndarray[nwalkers]]) – The log posterior probabilities for the walkers at p0. If log_prob0 is None, the initial values are calculated.
  • rstate0 (Optional) – The state of the random number generator. See the EnsembleSampler.random_state property for details.

Other parameters are directly passed to sample().

This method returns the most recent result from sample(). The particular values vary from sampler to sampler, but the result is generally a tuple (pos, log_prob, rstate) or (pos, log_prob, rstate, blobs) where pos is the most recent position vector (or ensemble thereof), log_prob is the most recent log posterior probability (or ensemble thereof), rstate is the state of the random number generator, and the optional blobs are user-provided large data blobs.

sample(p0, log_prob0=None, rstate0=None, blobs0=None, iterations=1, thin=1, store=True, progress=False)

Advance the chain as a generator

Parameters:
  • p0 (ndarray[nwalkers, ndim]) – The initial positions of the walkers in the parameter space.
  • log_prob0 (Optional[ndarray[nwalkers]]) – The log posterior probabilities for the walkers at p0. If log_prob0 is None, the initial values are calculated.
  • rstate0 (Optional) – The state of the random number generator. See the EnsembleSampler.random_state property for details.
  • iterations (Optional[int]) – The number of steps to run.
  • thin (Optional[int]) – If you only want to store and yield every thin samples in the chain, set thin to an integer greater than 1.
  • store (Optional[bool]) – By default, the sampler stores (in memory) the positions and log-probabilities of the samples in the chain. If you are using another method to store the samples to a file or if you don’t need to analyze the samples after the fact (for burn-in for example) set store to False.

At each iteration, this generator yields:

  • pos - A list of the current positions of the walkers in the parameter space. The shape of this object will be (nwalkers, dim).
  • log_prob - The list of log posterior probabilities for the walkers at positions given by pos . The shape of this object is (nwalkers,).
  • rstate - The current state of the random number generator.
  • blobs - (optional) The metadata “blobs” associated with the current position. The value is only returned if log_prob_fn returns blobs too.

Moves

class emcee.moves.StretchMove(a=2.0, **kwargs)

A Goodman & Weare (2010) “stretch move” with parallelization as described in Foreman-Mackey et al. (2013).

Parameters:a – (optional) The stretch scale parameter. (default: 2.0)
propose(coords, log_probs, blobs, log_prob_fn, random)
Parameters:
  • coords – The initial coordinates of the walkers.
  • log_probs – The initial log probabilities of the walkers.
  • log_prob_fn – A function that computes the log probabilities for a subset of walkers.
  • random – A numpy-compatible random number state.
class emcee.moves.WalkMove(s=None, **kwargs)

A Goodman & Weare (2010) “walk move” with parallelization as described in Foreman-Mackey et al. (2013).

Parameters:s – (optional) The number of helper walkers to use. By default it will use all the walkers in the complement.
propose(coords, log_probs, blobs, log_prob_fn, random)
Parameters:
  • coords – The initial coordinates of the walkers.
  • log_probs – The initial log probabilities of the walkers.
  • log_prob_fn – A function that computes the log probabilities for a subset of walkers.
  • random – A numpy-compatible random number state.
class emcee.moves.KDEMove(bw_method=None, **kwargs)

Use a continuously evolving KDE proposal. This is a simplified version of the method used in kombine. If you use this proposal, you should use a lot of walkers in your ensemble.

Parameters:bw_method – The bandwidth estimation method. See the scipy docs for allowed values.
propose(coords, log_probs, blobs, log_prob_fn, random)
Parameters:
  • coords – The initial coordinates of the walkers.
  • log_probs – The initial log probabilities of the walkers.
  • log_prob_fn – A function that computes the log probabilities for a subset of walkers.
  • random – A numpy-compatible random number state.
class emcee.moves.GaussianMove(cov, mode='vector', factor=None)

A Metropolis step with a Gaussian proposal function.

Parameters:
  • cov – The covariance of the proposal function. This can be a scalar, vector, or matrix and the proposal will be assumed isotropic, axis-aligned, or general respectively.
  • mode (Optional) – Select the method used for updating parameters. This can be one of "vector", "random", or "sequential". The "vector" mode updates all dimensions simultaneously, "random" randomly selects a dimension and only updates that one, and "sequential" loops over dimensions and updates each one in turn.
  • factor (Optional[float]) – If provided the proposal will be made with a standard deviation uniformly selected from the range exp(U(-log(factor), log(factor))) * cov. This is invalid for the "vector" mode.
Raises:

ValueError – If the proposal dimensions are invalid or if any of any of the other arguments are inconsistent.
propose(coords, log_probs, blobs, log_prob_fn, random)
Parameters:
  • coords – The initial coordinates of the walkers.
  • log_probs – The initial log probabilities of the walkers.
  • log_prob_fn – A function that computes the log probabilities for a subset of walkers.
  • random – A numpy-compatible random number state.

Autocorrelation Analysis

A good heuristic for assessing convergence of samplings is the integrated autocorrelation time. emcee includes tools for computing this and the autocorrelation function itself. More details can be found in Autocorrelation analysis & convergence.

emcee.autocorr.integrated_time(x, c=5, tol=50, quiet=False)

Estimate the integrated autocorrelation time of a time series.

This estimate uses the iterative procedure described on page 16 of Sokal’s notes to determine a reasonable window size.

Parameters:
  • x – The time series. If multidimensional, set the time axis using the axis keyword argument and the function will be computed for every other axis.
  • c (Optional[float]) – The step size for the window search. (default: 5)
  • tol (Optional[float]) – The minimum number of autocorrelation times needed to trust the estimate. (default: 10)
  • quiet (Optional[bool]) – This argument controls the behavior when the chain is too short. If True, give a warning instead of raising an AutocorrError. (default: False)
Returns:

An estimate of the integrated autocorrelation time of

the time series x computed along the axis axis.

Optional[int]: The final window size that was used. Only returned if

full_output is True.
Return type:

float or array
Raises
AutocorrError: If the autocorrelation time can’t be reliably estimated
from the chain and quiet is False. This normally means that the chain is too short.
emcee.autocorr.function_1d(x)

Estimate the normalized autocorrelation function of a 1-D series

Parameters:x – The series as a 1-D numpy array.
Returns:The autocorrelation function of the time series.
Return type:array

Interruptible Pool

emcee.interruptible_pool.InterruptiblePool

alias of Pool