xdnuts function

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

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 \insertCite duane1987hybridXDNUTS, NUTS \insertCite hoffman2014noXDNUTS, and XHMC \insertCite betancourt2016identifyingXDNUTS are embedded into the framework described in \insertCite nishimura2020discontinuousXDNUTS, which allows dealing 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 estimate of the Mass Matrix during the warm-up phase without requiring a relevant additional computational cost.

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

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 \insertCite nishimura2020discontinuousXDNUTS 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 \insertCite hoffman2014noXDNUTS.
  • "XHMC": applies the Exhaustion Hamiltonian Monte Carlo of \insertCite betancourt2016identifyingXDNUTS.
  • "HMC": applies one of the classic version of Hamiltonian Monte Carlo algorithm, in particular the one described in \insertCite betancourt2017conceptualXDNUTS, which samples from the trajectory instead of always returning the last value.

• tau: the threshold for the virial termination criterion \insertCite betancourt2016identifyingXDNUTS.

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

• loadLibraries: A character vector indicating the names of the packages to load on each cluster if parallel is set to TRUE.

• loadRObject: A character vector indicating the names of the R objects to load on each cluster if parallel is set to TRUE.

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

• logfile: The pathname of the log file. The default value is "". On Linux or macOS systems, this allows the output to be printed directly to the console. Unfortunately, this is not possible on Windows systems.

Returns

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

\insertAllCited