EmceeSampler#

class zfit.mcmc.EmceeSampler(nwalkers=None, *, n_samples=None, n_warmup=None, moves=None, backend=None, name='EmceeSampler', verbosity=None)[source]#

Bases: BaseMCMCSampler

MCMC sampler using emcee (https://emcee.readthedocs.io).

EmceeSampler is an ensemble sampler that uses multiple ‘walkers’ to explore the posterior distribution. It’s particularly good for problems with strongly correlated parameters and doesn’t require gradients of the log-probability function.

This sampler requires all parameters to have priors defined, as it uses the product of likelihood and prior for sampling.

Examples

Basic usage with default settings:

>>> sampler = zfit.mcmc.EmceeSampler(nwalkers=32)
>>> result = sampler.sample(loss=nll, params=params, n_samples=1000)

With custom moves and settings:

>>> import emcee
>>> custom_moves = [(emcee.moves.DEMove(), 0.8), (emcee.moves.DESnookerMove(), 0.2)]
>>> sampler = zfit.mcmc.EmceeSampler(nwalkers=50,moves=custom_moves,verbosity=8)
>>> result = sampler.sample(loss=nll, params=params,
...                        n_samples=2000, n_warmup=500)

Initialize an EmceeSampler.

Parameters:

  • nwalkers (int | None) – Number of walkers to use. If None, will use max(2 * n_dims, 5) where n_dims is the number of parameters. Must be at least twice the number of dimensions.

  • n_warmup (int | None) – Default value for number of samples for warmup. The number of warmup points that will be discarded.

  • n_samples (int | None) – Default value for number of samples. The number of points to sample.

  • moves (list[tuple[Move, float]] | None) – The proposal moves to use. Can be a single move or a list of (move, weight) tuples. If None, uses emcee’s default StretchMove. See emcee documentation for available moves.

  • backend (Backend | None) – Backend to store the chain state and samples. Useful for checkpointing long runs. If None, samples are stored in memory only.

  • name (str) – Name of the sampler for identification.

  • verbosity (int | None) – Verbosity level: - 0-6: No progress bars - 7: Print sampling phases - 8+: Show progress bars during sampling

Raises:

ImportError – If emcee is not installed.

Note

The number of walkers should be at least 2 * n_params for good performance. Larger numbers of walkers can help with difficult posteriors but increase computational cost linearly.

sample(loss, params=None, n_samples=None, n_warmup=None, init=None)#

Sample from the posterior distribution using MCMC.

This method runs the MCMC sampler to generate samples from the posterior distribution. The sampling process consists of two phases: 1. Warmup/burn-in: Allow chains to find the typical set 2. Production: Generate samples for analysis

All parameters must have priors defined before sampling.

Parameters:

  • loss (ZfitLoss) – The loss function to sample from. Must be a ZfitLoss instance (e.g., UnbinnedNLL, ExtendedUnbinnedNLL).

  • params (Iterable[ZfitParameter] | None) – List of ZfitParameter objects to sample. If None, uses all floating parameters from the loss function.

  • n_samples (int | None) – Number of production samples to generate. If None, uses the default value specified in the constructor.

  • n_warmup (int | None) – Number of burn-in steps. These samples are discarded and used only to allow the chains to converge. If init is provided with PosteriorSamples, n_warmup can be 0 to skip burn-in (default behavior).

  • init (PosteriorSamples | None) – Previous posterior samples to initialize the sampler from. This allows warm-starting from a previous run, potentially skipping burn-in.

Return type:

PosteriorSamples

Returns:

Object containing posterior samples and analysis methods.

Raises:

  • TypeError – If loss is not a ZfitLoss or params contain non-ZfitParameter objects.

  • ValueError – If any parameter lacks a prior distribution.

Examples

Basic sampling:

>>> # Setup model and data
>>> nll = zfit.loss.UnbinnedNLL(model=model, data=data)
>>> sampler = zfit.mcmc.EmceeSampler(nwalkers=32)
>>> result = sampler.sample(loss=nll, n_samples=1000, n_warmup=500)

Sampling specific parameters:

>>> # Only sample mu and sigma, keep other parameters fixed
>>> params_to_sample = [mu, sigma]
>>> result = sampler.sample(loss=nll, params=params_to_sample,
...                        n_samples=2000, n_warmup=1000)

Warm-start from previous sampling:

>>> # First run
>>> result1 = sampler.sample(loss=nll, n_samples=1000, n_warmup=500)
>>>
>>> # Continue sampling from where we left off
>>> result2 = sampler.sample(loss=nll, init=result1,
...                         n_samples=2000, n_warmup=0)

Note

  • The exact behavior depends on the specific sampler implementation

  • Use verbosity >= 7 to see progress information

  • Consider using larger n_warmup for difficult posteriors

  • When using init, ensure the parameters match between runs