The Ensemble Sampler¶
Standard usage of emcee
involves instantiating an
EnsembleSampler
.
-
class
emcee.
EnsembleSampler
(nwalkers, ndim, log_prob_fn, pool=None, moves=None, args=None, kwargs=None, backend=None, vectorize=False, blobs_dtype=None, a=None, postargs=None, threads=None, live_dangerously=None, runtime_sortingfn=None)¶ An ensemble MCMC sampler
Parameters: - nwalkers (int) – The number of walkers in the ensemble.
- ndim (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.
- moves (Optional) – This can be a single move object, a list of moves,
or a “weighted” list of the form
[(emcee.moves.StretchMove(), 0.1), ...]
. When running, the sampler will randomly select a move from this list (optionally with weights) for each proposal. (default:StretchMove
) - args (Optional) – A list of extra positional arguments for
log_prob_fn
.log_prob_fn
will be called with the sequencelog_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 sequencelog_pprob_fn(p, *args, **kwargs)
. - pool (Optional) – An object with a
map
method that follows the same calling sequence as the built-inmap
function. This is generally used to compute the log-probabilities for the ensemble in parallel. - backend (Optional) – Either a
backends.Backend
or a subclass (likebackends.HDFBackend
) that is used to store and serialize the state of the chain. By default, the chain is stored as a set of numpy arrays in memory, but new backends can be written to support other mediums. - vectorize (Optional[bool]) – If
True
,log_prob_fn
is expected to accept a list of position vectors instead of just one. Note thatpool
will be ignored if this isTrue
. (default:False
)
-
acceptance_fraction
¶ The fraction of proposed steps that were accepted
-
compute_log_prob
(coords)¶ Calculate the vector of log-probability for the walkers
Parameters: coords – (ndarray[…, ndim]) The position vector in parameter space where the probability should be calculated. 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 orNone
if nothing was returned.
-
get_autocorr_time
(**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 bythin
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] - thin (Optional[int]) – Use only every
-
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]
- flat (Optional[bool]) – Flatten the chain across the ensemble.
(default:
-
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]
- flat (Optional[bool]) – Flatten the chain across the ensemble.
(default:
-
get_last_sample
(**kwargs)¶ Access the most recent sample in the chain
-
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]
- flat (Optional[bool]) – Flatten the chain across the ensemble.
(default:
-
random_state
¶ The state of the internal random number generator. In practice, it’s the result of calling
get_state()
on anumpy.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
(initial_state, nsteps, **kwargs)¶ Iterate
sample()
fornsteps
iterations and return the resultParameters: - initial_state – The initial state or position vector. Can also be
None
to resume from where :func:run_mcmc
left off the last time it executed. - nsteps – The number of steps to run.
Other parameters are directly passed to
sample()
.This method returns the most recent result from
sample()
.- initial_state – The initial state or position vector. Can also be
-
sample
(initial_state, log_prob0=None, rstate0=None, blobs0=None, iterations=1, tune=False, skip_initial_state_check=False, thin_by=1, thin=None, store=True, progress=False)¶ Advance the chain as a generator
Parameters: - initial_state (State or ndarray[nwalkers, ndim]) – The initial
State
or positions of the walkers in the parameter space. - iterations (Optional[int]) – The number of steps to generate.
- tune (Optional[bool]) – If
True
, the parameters of some moves will be automatically tuned. - thin_by (Optional[int]) – If you only want to store and yield every
thin_by
samples in the chain, setthin_by
to an integer greater than 1. When this is set,iterations * thin_by
proposals will be made. - 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
toFalse
. - progress (Optional[bool or str]) – If
True
, a progress bar will be shown as the sampler progresses. If a string, will select a specifictqdm
progress bar - most notable is'notebook'
, which shows a progress bar suitable for Jupyter notebooks. IfFalse
, no progress bar will be shown. - skip_initial_state_check (Optional[bool]) – If
True
, a check that the initial_state can fully explore the space will be skipped. (default:False
)
Every
thin_by
steps, this generator yields theState
of the ensemble.- initial_state (State or ndarray[nwalkers, ndim]) – The initial
Note that several of the EnsembleSampler
methods return or consume
State
objects:
-
class
emcee.
State
(coords, log_prob=None, blobs=None, random_state=None, copy=False)¶ The state of the ensemble during an MCMC run
For backwards compatibility, this will unpack into
coords, log_prob, (blobs), random_state
when iterated over (whereblobs
will only be included if it exists and is notNone
).Parameters: - coords (ndarray[nwalkers, ndim]) – The current positions of the walkers in the parameter space.
- log_prob (ndarray[nwalkers, ndim], Optional) – Log posterior
probabilities for the walkers at positions given by
coords
. - blobs (Optional) – The metadata “blobs” associated with the current position. The value is only returned if lnpostfn returns blobs too.
- random_state (Optional) – The current state of the random number generator.