littlemcmc.NUTS

class littlemcmc.NUTS(logp_dlogp_func: Callable[[numpy.ndarray], Tuple[numpy.ndarray, numpy.ndarray]], model_ndim: int, scaling: Optional[numpy.ndarray] = None, is_cov: bool = False, potential=None, target_accept: float = 0.8, Emax: float = 1000, adapt_step_size: bool = True, step_scale: float = 0.25, gamma: float = 0.05, k: float = 0.75, t0: int = 10, step_rand: Optional[Callable[[float], float]] = None, path_length: float = 2.0, max_treedepth: int = 10, early_max_treedepth: int = 8)

A sampler for continuous variables based on Hamiltonian mechanics.

NUTS automatically tunes the step size and the number of steps per sample. A detailed description can be found at [1], “Algorithm 6: Efficient No-U-Turn Sampler with Dual Averaging”.

NUTS provides a number of statistics that can be accessed with trace.get_sampler_stats:

  • mean_tree_accept: The mean acceptance probability for the tree that generated this sample. The mean of these values across all samples but the burn-in should be approximately target_accept (the default for this is 0.8).
  • diverging: Whether the trajectory for this sample diverged. If there are any divergences after burnin, this indicates that the results might not be reliable. Reparametrization can often help, but you can also try to increase target_accept to something like 0.9 or 0.95.
  • energy: The energy at the point in phase-space where the sample was accepted. This can be used to identify posteriors with problematically long tails. See below for an example.
  • energy_change: The difference in energy between the start and the end of the trajectory. For a perfect integrator this would always be zero.
  • max_energy_change: The maximum difference in energy along the whole trajectory.
  • depth: The depth of the tree that was used to generate this sample
  • tree_size: The number of leafs of the sampling tree, when the sample was accepted. This is usually a bit less than 2 ** depth. If the tree size is large, the sampler is using a lot of leapfrog steps to find the next sample. This can for example happen if there are strong correlations in the posterior, if the posterior has long tails, if there are regions of high curvature (“funnels”), or if the variance estimates in the mass matrix are inaccurate. Reparametrisation of the model or estimating the posterior variances from past samples might help.
  • tune: This is True, if step size adaptation was turned on when this sample was generated.
  • step_size: The step size used for this sample.
  • step_size_bar: The current best known step-size. After the tuning samples, the step size is set to this value. This should converge during tuning.
  • model_logp: The model log-likelihood for this sample.

References

[1]Hoffman, Matthew D., & Gelman, Andrew. (2011). The No-U-Turn Sampler: Adaptively Setting Path Lengths in Hamiltonian Monte Carlo.
__init__(logp_dlogp_func: Callable[[numpy.ndarray], Tuple[numpy.ndarray, numpy.ndarray]], model_ndim: int, scaling: Optional[numpy.ndarray] = None, is_cov: bool = False, potential=None, target_accept: float = 0.8, Emax: float = 1000, adapt_step_size: bool = True, step_scale: float = 0.25, gamma: float = 0.05, k: float = 0.75, t0: int = 10, step_rand: Optional[Callable[[float], float]] = None, path_length: float = 2.0, max_treedepth: int = 10, early_max_treedepth: int = 8)

Set up the No-U-Turn sampler.

Parameters:
logp_dlogp_func : Python callable

Python callable that returns the log-probability and derivative of the log-probability, respectively.

model_ndim : int

Total number of parameters. Dimensionality of the output of logp_dlogp_func.

scaling : 1 or 2-dimensional array-like

Scaling for momentum distribution. 1 dimensional arrays are interpreted as a matrix diagonal.

is_cov : bool

Treat scaling as a covariance matrix/vector if True, else treat it as a precision matrix/vector

potential : littlemcmc.quadpotential.Potential, optional

An object that represents the Hamiltonian with methods velocity, energy, and random methods. Only one of scaling or potential may be non-None.

target_accept : float

Adapt the step size such that the average acceptance probability across the trajectories are close to target_accept. Higher values for target_accept lead to smaller step sizes. Setting this to higher values like 0.9 or 0.99 can help with sampling from difficult posteriors. Valid values are between 0 and 1 (exclusive).

Emax : float

The maximum allowable change in the value of the Hamiltonian. Any trajectories that result in changes in the value of the Hamiltonian larger than Emax will be declared divergent.

adapt_step_size : bool, default=True

If True, performs dual averaging step size adaptation. If False, k, t0, gamma and target_accept are ignored.

step_scale : float

Size of steps to take, automatically scaled down by 1 / (size ** 0.25).

gamma : float, default .05
k : float, default .75

Parameter for dual averaging for step size adaptation. Values between 0.5 and 1 (exclusive) are admissible. Higher values correspond to slower adaptation.

t0 : int, default 10

Parameter for dual averaging. Higher values slow initial adaptation.

step_rand : Python callable

Callback for step size adaptation. Called on the step size at each iteration immediately before performing dual-averaging step size adaptation.

path_length : float, default=2

total length to travel

max_treedepth : int, default=10

The maximum tree depth. Trajectories are stoped when this depth is reached.

early_max_treedepth : int, default=8

The maximum tree depth during the first 200 tuning samples.

Notes

The step size adaptation stops when self.tune is set to False. This is usually achieved by setting the tune parameter if pm.sample to the desired number of tuning steps.

Methods

__init__(logp_dlogp_func, …[, potential]) Set up the No-U-Turn sampler.
reset(start) Reset quadpotential and begin retuning.
reset_tuning(start) Reset quadpotential and step size adaptation, and begin retuning.
stop_tuning() Stop tuning.
warnings() Generate warnings from NUTS sampler.

Attributes

default_blocked
generates_stats
name
stats_dtypes