main_function: Function to generate a Markov chain for both continuous and...
In XDNUTS: Discontinuous Hamiltonian Monte Carlo with Varying Trajectory Length

main_function

R Documentation

Function to generate a Markov chain for both continuous and discontinuous posterior distributions.

Description

The function allows to generate a single Markov Chain for sampling from both continuous and discontinuous posterior distributions using a plethora of algorithms. Classic Hamiltonian Monte Carlo \insertCiteduane1987hybridXDNUTS , NUTS \insertCitehoffman2014noXDNUTS and XHMC \insertCitebetancourt2016identifyingXDNUTS are embedded into the framework described in \insertCitenishimura2020discontinuousXDNUTS, which allows to deal with such posteriors. Furthermore, for each method, it is possible to recycle samples from the trajectories using the method proposed by \insertCiteNishimura_2020XDNUTS. This is used to improve the estimation of the mass matrix during the warm-up phase without requiring significant additional computational costs. This function should not be used directly, but only through the user interface provided by xdnuts.

Usage

main_function(
  theta0,
  nlp,
  args,
  k,
  N,
  K,
  tau,
  L,
  thin,
  chain_id,
  verbose,
  control
)

Arguments

`theta0`	a vector of length-`d` containing the starting point of the chain.
`nlp`	a function object that takes three arguments: par a vector of length-`d` containing the value of the parameters. args a list object that contains the necessary arguments, namely data and hyperparameters. eval_nlp a boolean value, `TRUE` for evaluating only the model\'s negative log posterior, `FALSE` to evaluate the gradient with respect to the continuous components of the posterior.
`args`	the necessary arguments to evaluate the negative log posterior and its gradient.
`k`	the number of parameters that induce a discontinuity in the posterior distribution.
`N`	integer containing the number of post warm-up samples to evaluate.
`K`	integer containing the number of recycled samples from each trajectory during the warm-up phase or beyond.
`tau`	the threshold for the exhaustion termination criterion described in \insertCitebetancourt2016identifyingXDNUTS.
`L`	the desired length of the trajectory of classic Hamiltonian Monte Carlo algorithm.
`thin`	integer containing the number of samples to discard in order to produce a final iteration of the chain.
`chain_id`	the identification number of the chain.
`verbose`	a boolean value that controls whether to print all the information regarding the sampling process.
`control`	an object of class `control_xdnuts` containing the specifications for the algorithm. See the set_parameters function for detail.

Value

a named list containing:

values: a N \times d matrix containing the sample from the target distribution (if convergence has been reached).
energy: a vector of length-N containing the Markov Chain of the energy level sets.
delta_energy: a vector of length-N containing the Markov Chain of the first difference energy level sets.
step_size: a vector of length-N containing the sampled step size used for each iteration.
step_length: a vector of length-N containing the length of each trajectory of the chain.
alpha: a vector of length-k + 1 containing the estimate of the Metropolis acceptance probabilities. The first element of the vector is the estimated global acceptance probability. The remaining k elements are the estimate rate of reflection for each parameters which travels coordinate-wise through some discontinuity.
warm_up: a N_{adapt} \times d matrix containing the sample of the chain coming from the warm-up phase. If keep_warm_up = FALSE inside the control argument, nothing is returned.
div_trans: a M \times d matrix containing the locations where a divergence has been encountered during the integration of Hamilton equation. Hopefully M \ll N, and even better if M = 0.
M_cont: the Mass Matrix of the continuous components estimated during the warm-up phase. Based on the M_type value of the control arguments, this could be an empty object, a vector or a matrix.
M_disc: the Mass Matrix of the discontinuous components estimated during the warm-up phase. Based on the M_type value of the control arguments, this could be an empty object or a vector.