xdnuts {XDNUTS}R Documentation

Discontinuous Hamiltonian Monte Carlo using both manual and automatic termination criteria.

Description

The function allows generating multiple Markov Chains for sampling from both continuous and discontinuous posterior distributions using a variety of algorithms. Classic Hamiltonian Monte Carlo (Duane et al. 1987), NUTS (Hoffman et al. 2014), and XHMC (Betancourt 2016) are embedded into the framework described in (Nishimura et al. 2020), which allows dealing with such posteriors. Furthermore, for each method, it is possible to recycle samples from the trajectories using the method proposed by (Nishimura and Dunson 2020). This is used to improve the estimate of the Mass Matrix during the warm-up phase without requiring a relevant additional computational cost.

Usage

xdnuts(
  theta0,
  nlp,
  args,
  k,
  N = 1000,
  K = 3,
  method = "NUTS",
  tau = NULL,
  L = NULL,
  thin = 1,
  control = set_parameters(),
  parallel = FALSE,
  verbose = FALSE,
  hide = FALSE
)

Arguments

theta0

a list containing the starting values for each chain. These starting values are vectors of length-d. The last k \in [0,d] elements refer to parameters which determine a discontinuity in the posterior distribution.

nlp

a function which evaluates the negative log posterior and its gradient with respect to parameters that do not induce any discontinuity in the posterior distribution (more generally, the first d-k parameters). This function must take 3 arguments:

par

a vector of length-d containing the parameter values.

args

a list object that contains the necessary arguments, namely data and hyperparameters.

eval_nlp

a boolean value, TRUE to evaluate only the negative log posterior of the models, FALSE to evaluate its gradient with respect to the continuous components of the posterior.

args

a list containing the inputs for the negative posterior function.

k

an integer value that states the number of parameters that determines a discontinuity in the posterior distribution. Actually, since the algorithm proposed in (Nishimura et al. 2020) also works for the full continuous case, k is the number of parameters specified by the user for which this algorithm is used.

N

the number of draws from the posterior distribution, after warm-up, for each chain. Default value is 1000.

K

the number of recycled samples per iteration used by default during the warm-up phase. Default value is 3. To recycle in the sampling phase too, specify recycle_only_init = FALSE in the control argument above.

method

a character value which defines the type of algorithm to exploit:

"NUTS"

applies the No U-Turn Sampler of (Hoffman et al. 2014).

"XHMC"

applies the Exhaustion Hamiltonian Monte Carlo of (Betancourt 2016).

"HMC"

applies one of the classic version of Hamiltonian Monte Carlo algorithm, in particular the one described in (Betancourt 2017), which samples from the trajectory instead of always returning the last value.

tau

the threshold for the virial termination criterion (Betancourt 2016).

L

the desired length of the trajectory of classic Hamiltonian Monte Carlo algorithm.

thin

the number of necessary and discarded samples to obtain a final iteration of one chain.

control

an object of class control_xdnuts, output of the function set_parameters.

parallel

a boolean value specifying whether the chains must be run in parallel. Default value is FALSE.

verbose

a boolean value for printing all the information regarding the sampling process.

hide

a boolean value that omits the printing to the console if set to TRUE.

Value

a list of class XDNUTS containing

chains

a list of the same length of theta0, each element containing the output from the function main_function.

d

the dimension of the parameter space.

k

the number of parameters that lead to a discontinuous posterior distribution. Or, more generally, for which the algorithm of (Nishimura et al. 2020) is exploited.

K

the number of recycled samples for each iteration during the sampling phase.

N

the number of posterior draws for each chain.

method

the MCMC method used. This could be either "NUTS", "XHMC", or "HMC".

tau

the threshold for the virial termination criterion (Betancourt 2016). Only if method = "XHMC" this value is different from zero.

L

the desired length of the trajectory of classic Hamiltonian Monte Carlo algorithm specified by the user. This argument is necessary if method = "HMC".

thin

the number of discarded samples for every final iteration, specified by the user.

control

an object of class control_xdnuts, output of the function set_parameters with arguments specified by the user.

verbose

the boolean value specified by the user regarding the printing of the sampling process information.

parallel

the boolean value specified by the user regarding parallel processing.

References

Betancourt M (2016). “Identifying the optimal integration time in Hamiltonian Monte Carlo.” arXiv preprint arXiv:1601.00225.

Betancourt M (2017). “A conceptual introduction to Hamiltonian Monte Carlo.” arXiv preprint arXiv:1701.02434.

Duane S, Kennedy AD, Pendleton BJ, Roweth D (1987). “Hybrid monte carlo.” Physics letters B, 195(2), 216–222.

Hoffman MD, Gelman A, others (2014). “The No-U-Turn sampler: adaptively setting path lengths in Hamiltonian Monte Carlo.” J. Mach. Learn. Res., 15(1), 1593–1623.

Nishimura A, Dunson D (2020). “Recycling Intermediate Steps to Improve Hamiltonian Monte Carlo.” Bayesian Analysis, 15(4). ISSN 1936-0975, doi:10.1214/19-ba1171, http://dx.doi.org/10.1214/19-BA1171.

Nishimura A, Dunson DB, Lu J (2020). “Discontinuous Hamiltonian Monte Carlo for discrete parameters and discontinuous likelihoods.” Biometrika, 107(2), 365–380.


[Package XDNUTS version 1.2 Index]