R: Markov Chain Monte Carlo for BAMLSS using JAGS

sam_JAGS {bamlss} | R Documentation

## Markov Chain Monte Carlo for BAMLSS using JAGS

### Description

This sampler function for BAMLSS is an interface to the JAGS library using package `rjags`. The function basically interprets the `bamlss.frame` into BUGS code, similar to the `jagam` function of package `mgcv`. I.e., the function uses the random effects representation of smooth terms, see the transformer function `randomize` to generate the BUGS code.

Note that estimating BAMLSS with JAGS is not very efficient. Also note that this function is more experimental and support is only provided for a small number of `bamlss.family` objects.

Function `BUGSeta()` therefore computes the code and data for one parameter of the modeled distribution. Function `BUGSmodel()` then collects all parameter model code and data, which can be send to JAGS.

### Usage

    ## Sampler functions:
    sam_JAGS(x, y, family, start = NULL,
      tdir = NULL, n.chains = 1, n.adapt = 100,
      n.iter = 4000, thin = 2, burnin = 1000,
      seed = NULL, verbose = TRUE, set.inits = TRUE,
      save.all = FALSE, modules = NULL, ...)

    JAGS(x, y, family, start = NULL,
      tdir = NULL, n.chains = 1, n.adapt = 100,
      n.iter = 4000, thin = 2, burnin = 1000,
      seed = NULL, verbose = TRUE, set.inits = TRUE,
      save.all = FALSE, modules = NULL, ...)

    ## Function to interpret an additive predictor into BUGS code:
    BUGSeta(x, id = NULL, ...)

    ## Function to interpret the full BAMLSS:
    BUGSmodel(x, family, is.stan = FALSE, reference = NULL, ...)

### Arguments

`x` | For function `sam_JAGS()` and `BUGSmodel()` the `x` list, as returned from function `bamlss.frame`, holding all model matrices and other information that is used for fitting the model. For function `BUGSeta()` argument `x` is one element of the `x` object, i.e., one parameter.
`y` | The model response, as returned from function `bamlss.frame`.
`family` | A bamlss family object, see `family.bamlss`.
`start` | A named numeric vector containing possible starting values, the names are based on function `parameters`.
`tdir` | The path to the temporary directory that should be used.
`n.chains` | Specifies the number of sequential MCMC chains that should be run with JAGS.
`n.adapt` | Specifies the number of iterations that should be used as an initial adaptive phase.
`n.iter` | Sets the number of MCMC iterations.
`thin` | Defines the thinning parameter for MCMC simulation. E.g., `thin = 10` means, that only every 10th sampled parameter will be stored.
`burnin` | Sets the burn-in phase of the sampler, i.e., the number of starting samples that should be removed.
`seed` | Sets the seed.
`verbose` | Print information during runtime of the algorithm.
`set.inits` | Should initial values of BAMLSS `parameters` be provided to JAGS, if available. Set in argument `start`.
`save.all` | Should all JAGS files be saved in `tdir`.
`modules` | Specify additional modules that should be loaded, see function `load.module`.
`id` | Character, the current parameter name for which the BUGS code should be produced.
`is.stan` | Should the BUGS code be translated to STAN code. Note that this is only experimental.
`reference` | A `character` specifying a reference category, e.g., when fitting a multinomial model.
`...` | Currently not used.

### Value

Function `sam_JAGS()` returns samples of parameters. The samples are provided as a `mcmc` matrix. If `n.chains > 1`, the samples are provided as a `mcmc.list`.

Function `BUGSeta()` returns the BUGS model code and preprocessed data for one additive predictor. Function `BUGSmodel()` then combines all single BUGS code chunks and the data and creates the final BUGS model code that can be send to JAGS.

### Note

Note that for setting up a new family object to be used with `sam_JAGS()` additional information needs to be supplied. The extra information must be placed within the family object in an element named `"bugs"`. The following entries should be supplied within the `..$bugs` list:

- `"dist"`. The name of the distribution in BUGS/JAGS model language.

- `"eta"`. The function that computes the BUGS code for one structured additive predictor. Function `BUGSeta()` is used per default.

- `"model"`. The function that merges all single predictor BUGS model code and data. The default function is `BUGSmodel()`.

- `"reparam"`. A named vector of character strings that specify a re-parametrization.

See also the example code of `family.bamlss`.

### See Also

`bamlss`, `bamlss.frame`, `bamlss.engine.setup`, `set.starting.values`, `bfit`, `GMCMC`

### Examples

    ## Not run: ## Simulated data example illustrating
    ## how to call the sampler function.
    ## This is done internally within
    ## the setup of function bamlss().
    d <- GAMart()
    f <- num ~ s(x1, bs = "ps")
    bf <- bamlss.frame(f, data = d, family = "gaussian")

    ## First, find starting values with optimizer.
    opt <- with(bf, opt_bfit(x, y, family))

    ## Sample with JAGS.
    if(require("rjags")) {
      samps <- with(bf, sam_JAGS(x, y, family, start = opt$parameters))
      plot(samps)

      b <- bamlss(f, data = d, family = "gaussian", sampler = sam_JAGS)
      plot(b)
    }

    ## End(Not run)

[Package bamlss version 1.1-6 Index]