Moves#

emcee was originally built on the “stretch move” ensemble method from Goodman & Weare (2010), but starting with version 3, emcee nows allows proposals generated from a mixture of “moves”. This can be used to get a more efficient sampler for models where the stretch move is not well suited, such as high dimensional or multi-modal probability surfaces.

A “move” is an algorithm for updating the coordinates of walkers in an ensemble sampler based on the current set of coordinates in a manner that satisfies detailed balance. In most cases, the update for each walker is based on the coordinates in some other set of walkers, the complementary ensemble.

These moves have been designed to update the ensemble in parallel following the prescription from Foreman-Mackey et al. (2013). This means that computationally expensive models can take advantage of multiple CPUs to accelerate sampling (see the Parallelization tutorial for more information).

The moves are selected using the moves keyword for the EnsembleSampler and the mixture can optionally be a weighted mixture of moves. During sampling, at each step, a move is randomly selected from the mixture and used as the proposal.

The default move is still the moves.StretchMove, but the others are described below. Many standard ensemble moves are available with parallelization provided by the moves.RedBlueMove abstract base class that implements the parallelization method described by Foreman-Mackey et al. (2013). In addition to these moves, there is also a framework for building Metropolis–Hastings proposals that update the walkers using independent proposals. moves.MHMove is the base class for this type of move and a concrete implementation of a Gaussian Metropolis proposal is found in moves.GaussianMove.

Note

The Using different moves tutorial shows a concrete example of how to use this interface.

Ensemble moves#

class emcee.moves.RedBlueMove(nsplits=2, randomize_split=True, live_dangerously=False)#

An abstract red-blue ensemble move with parallelization as described in Foreman-Mackey et al. (2013).

Parameters:

  • nsplits (Optional[int]) – The number of sub-ensembles to use. Each sub-ensemble is updated in parallel using the other sets as the complementary ensemble. The default value is 2 and you probably won’t need to change that.

  • randomize_split (Optional[bool]) – Randomly shuffle walkers between sub-ensembles. The same number of walkers will be assigned to each sub-ensemble on each iteration. By default, this is True.

  • live_dangerously (Optional[bool]) – By default, an update will fail with a RuntimeError if the number of walkers is smaller than twice the dimension of the problem because the walkers would then be stuck on a low dimensional subspace. This can be avoided by switching between the stretch move and, for example, a Metropolis-Hastings step. If you want to do this and suppress the error, set live_dangerously = True. Thanks goes (once again) to @dstndstn for this wonderful terminology.

propose(model, state)#

Use the move to generate a proposal and compute the acceptance

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.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)

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.

class emcee.moves.KDEMove(bw_method=None, **kwargs)#

A proposal using a KDE of the complementary ensemble

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.

class emcee.moves.DEMove(sigma=1e-05, gamma0=None, **kwargs)#

A proposal using differential evolution.

This Differential evolution proposal is implemented following Nelson et al. (2013).

Parameters:

  • sigma (float) – The standard deviation of the Gaussian used to stretch the proposal vector.

  • gamma0 (Optional[float]) – The mean stretch factor for the proposal vector. By default, it is \(2.38 / \sqrt{2\,\mathrm{ndim}}\) as recommended by the two references.

class emcee.moves.DESnookerMove(gammas=1.7, **kwargs)#

A snooker proposal using differential evolution.

Based on Ter Braak & Vrugt (2008).

Credit goes to GitHub user mdanthony17 for proposing this as an addition to the original emcee package.

Parameters:

gammas (Optional[float]) – The mean stretch factor for the proposal vector. By default, it is \(1.7\) as recommended by the reference.

Metropolis–Hastings moves#

class emcee.moves.MHMove(proposal_function, ndim=None)#

A general Metropolis-Hastings proposal

Concrete implementations can be made by providing a proposal_function argument that implements the proposal as described below. For standard Gaussian Metropolis moves, moves.GaussianMove can be used.

Parameters:

  • proposal_function – The proposal function. It should take 2 arguments: a numpy-compatible random number generator and a (K, ndim) list of coordinate vectors. This function should return the proposed position and the log-ratio of the proposal probabilities (\(\ln q(x;\,x^\prime) - \ln q(x^\prime;\,x)\) where \(x^\prime\) is the proposed coordinate).

  • ndim (Optional[int]) – If this proposal is only valid for a specific dimension of parameter space, set that here.

propose(model, state)#

Use the move to generate a proposal and compute the acceptance

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.