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 multimodal 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 ForemanMackey 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 ForemanMackey 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 redblue ensemble move with parallelization as described in ForemanMackey et al. (2013).
 Parameters
nsplits (Optional[int]) – The number of subensembles to use. Each subensemble 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 subensembles. The same number of walkers will be assigned to each subensemble 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 MetropolisHastings step. If you want to do this and suppress the error, setlive_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 numpycompatible random number state.

class
emcee.moves.
StretchMove
(a=2.0, **kwargs)¶ A Goodman & Weare (2010) “stretch move” with parallelization as described in ForemanMackey 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 ForemanMackey 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=1e05, 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 MetropolisHastings 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 numpycompatible random number generator and a
(K, ndim)
list of coordinate vectors. This function should return the proposed position and the logratio 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 numpycompatible 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, axisaligned, 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.