---
title: "Variations in using runMCMCbtadjust with Nimble: samplers"
author: "Frédéric Gosselin"
email: "frederic.gosselin@inrae.fr"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
bibliography: references.bib
csl: ecology.csl 
vignette: >
  %\VignetteEngine{knitr::knitr}
  %\VignetteIndexEntry{Variations in using runMCMCbtadjust with Nimble: samplers}
  %\usepackage[UTF-8]{inputenc}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
knitr::opts_chunk$set(message = FALSE)
knitr::opts_chunk$set(warnings = FALSE)

### first calculates conditional (logical) variables to activate - or not - child documents whether the environment is OK to build this vignette
condition_rstan<-TRUE
if (nchar(system.file(package='rstan'))==0) {condition_rstan<-FALSE}

condition_parallel<-TRUE
if (nchar(system.file(package='parallel'))==0) {condition_parallel<-FALSE}

condition_nimble<-TRUE   
	  if (nchar(system.file(package='nimble'))==0) {condition_nimble<-FALSE}

condition_nimbleAPT<-TRUE   
	  if (nchar(system.file(package='nimbleAPT'))==0) {condition_nimbleAPT<-FALSE}

condition_nimbleHMC<-TRUE   
	  if (nchar(system.file(package='nimbleHMC'))==0) {condition_nimbleHMC<-FALSE}


```

# Introduction

This file is meant to present the possibilities of the function `runMCMC_btadjust` in the `runMCMCbtadjust` package when using Bayesian models written with the `Nimble` language, and the **capabilities of the packages `nimble`, `nimbleHMC` and `nimbleAPT` in terms of MCMC samplers**. The aim of the `runMCMC_btadjust` function is to run a Markov Chain Monte Carlo (MCMC) for a specified Bayesian model while adapting automatically the burn-in and thinning parameters to meet pre-specified targets in terms of MCMC convergence and number of effective values of MCMC outputs - where the term "number of effective values" for the MCMC outputs refers to sample size adjusted for autocorrelation. This is done in only one call to the function that repeatedly calls the MCMC until criteria for convergence and number of effective values are met. This allows to obtain a MCMC output that is out of the transient phase of the MCMC (convergence) and that contains a pre-specified number of nearly independent draws from the posterior distribution (number of effective values).

This function has four main advantages: (i) it saves the analyst's programming time since he/she does not have to repeatedly diagnose and re-run MCMCs until desired levels of convergence and number of effective values are reached; (ii) it allows a minimal, normalized quality control of MCMC outputs by allowing to meet pre-specified levels in terms of convergence and number of quasi-independent values; (iii) it may save computer's time when compared to cases where we have to restart the MCMC from the beginning if it has not converged or reached the specified number of effective values (as e.g. with `runMCMC` function in `NIMBLE`); and (iv) it can be applied with different MCMC R languages, with a stronger integration with `NIMBLE`.

We will **here restrict our attention on the `NIMBLE` language and show a first axis of strong integration with `NIMBLE`**. Indeed, the last versions of the package `nimble` provide a still **improved flexibility for the user, especially in terms of MCMC samplers** since `nimble` allows the user to choose the MCMC sampler parameter by parameter, which is one of its great strength. We will demonstrate the way we can use these possibilities on a very simple, yet problematic statistical model. The simulated data we wish to model correspond to a simple linear model with a strongly uncentered explanatory variable - a situation which is known to pose problems with classical MCMCs due top strong correlation of the Intercept and slope parameters.

```{r Simulating data}
set.seed(1)
nobs<-1000
x<-rnorm(nobs)+100
y<-y1000<-rnorm(n=length(x),mean=x,sd=1)

```



```{r, child=if (condition_nimble & condition_parallel) "../man/fragments/Nimble_samplers1_fragment.Rmd"}
```

```{r, child=if (condition_nimble & condition_parallel & condition_nimbleHMC) "../man/fragments/Nimble_samplers_HMC_fragment.Rmd"}
```

```{r, child=if (condition_nimble & condition_parallel & condition_nimbleAPT) "../man/fragments/Nimble_samplers_APT_fragment.Rmd"}
```



# Conclusion

We have here shown how to use the capabilities of `runMCMC_btadjust()` in terms of coupling with `NIMBLE` for changing and controlling MCMC samplers. This is something that I have found very powerful in various contexts, with also the possibility to write your own samplers. There are other samplers provided by Nimble that the user may find useful (cf. Nimble user guide, Nimble web site: https://r-nimble.org/ and Nimble users mailing list). This is a real strength of `NIMBLE` that `runMCMC_btadjust()` permits to use quite easily. 


# Acknowledgements
I wished to thank David Pleydell for help on the package `nimbleAPT` and the `NIMBLE` users mailing list.

The initial development of this package (up to version 1.1.1) was performed within the GAMBAS project funded by the French Agence Nationale pour la Recherche (ANR-18-CE02-0025) (cf. <https://gambas.cirad.fr/>).

<img src="../man/figures/logo_gambas.jpg">

# References
