main_function function

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

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 \insertCite duane1987hybridXDNUTS , NUTS \insertCite hoffman2014noXDNUTS and XHMC \insertCite betancourt2016identifyingXDNUTS are embedded into the framework described in \insertCite nishimura2020discontinuousXDNUTS, 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 \insertCite Nishimura_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 .

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 \insertCite betancourt2016identifyingXDNUTS.

• 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.

Returns

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.

References

\insertAllCited