R: Markov Chain Monte Carlo for BAMLSS using 'BayesX'

sam_BayesX {bamlss} | R Documentation

## Markov Chain Monte Carlo for BAMLSS using BayesX

### Description

This sampler function for BAMLSS is an interface to the BayesX (`https://www.uni-goettingen.de/de/bayesx/550513.html`) command-line binary from R. The sampler is based on the command line version and functions provided in the BayesXsrc package, which can be installed using function `get_BayesXsrc()`.

### Usage

    ## Sampler functions:
    sam_BayesX(x, y, family, start = NULL, weights = NULL, offset = NULL,
      data = NULL, control = BayesX.control(...), ...)

    BayesX(x, y, family, start = NULL, weights = NULL, offset = NULL,
      data = NULL, control = BayesX.control(...), ...)

    ## Sampler control:
    BayesX.control(n.iter = 1200, thin = 1, burnin = 200,
      seed = NULL, predict = "light", model.name = "bamlss",
      data.name = "d", prg.name = NULL, dir = NULL,
      verbose = FALSE, show.prg = TRUE, modeonly = FALSE, ...)

    ## Special BayesX smooth term constructor.
    sx(x, z = NULL, bs = "ps", by = NA, ...)

    ## Special BayesX tensor product smooth term constructor.
    tx(..., bs = "ps", k = -1,
      ctr = c("center", "main", "both", "both1", "both2",
        "none", "meanf", "meanfd", "meansimple", "nullspace"),
      xt = NULL, special = TRUE)
    tx2(...)
    tx3(..., bs = "ps", k = c(10, 5),
      ctr = c("main", "center"),
      xt = NULL, special = TRUE)
    tx4(..., ctr = c("center", "main", "both", "both1", "both2"))

    ## Smooth constructors and predict matrix.
    ## S3 method for class 'tensorX.smooth.spec'
    smooth.construct(object, data, knots, ...)
    ## S3 method for class 'tensorX.smooth'
    Predict.matrix(object, data)
    ## S3 method for class 'tensorX3.smooth.spec'
    smooth.construct(object, data, knots, ...)
    ## S3 method for class 'tensorX3.smooth'
    Predict.matrix(object, data)

    ## Family object for quantile regression with BayesX.
    quant_bamlss(prob = 0.5)

    ## Download the newest version of BayesXsrc.
    get_BayesXsrc(dir = NULL, install = TRUE)

### Arguments

`x` | For function `BayesX()` 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 `sx()` arguments `x` and `z` specify the variables the smooth should be a function of.
`y` | The model response, as returned from function `bamlss.frame`.
`z` | Second variable in a `sx()` term.
`family` | A bamlss family object, see `family.bamlss`.
`start` | A named numeric vector containing possible starting values, the names are based on function `parameters`.
`weights` | Prior weights on the data, as returned from function `bamlss.frame`.
`offset` | Can be used to supply model offsets for use in fitting, returned from function `bamlss.frame`.
`data` | The model frame that should be used for modeling. Note that argument `data` needs not to be specified when the `BayesX()` sampler function is used with `bamlss`. For the smooth constructor for `tx()` terms, see function `smooth.construct`.
`control` | List of control arguments to be send to BayesX. See below.
`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.
`predict` | Not supported at the moment, do not modify!
`model.name` | The name that should be used for the model when calling BayesX.
`data.name` | The name that should be used for the data set when calling BayesX.
`prg.name` | The name that should be used for the `.prg` file that is send to BayesX.
`dir` | Specifies the directory where BayesX should store all output files. For function `get_BayesXsrc()`, the directory where BayesXsrc should be stored.
`verbose` | Print information during runtime of the algorithm.
`show.prg` | Show the BayesX `.prg` file.
`modeonly` | Should only the posterior mode be compute, note that this is done using fixed smoothing parameters/variances.
`bs` | A `character` string, specifying the basis/type which is used for this model term.
`by` | A by variable for varying coefficient model terms.
`k` | The dimension(s) of the bases used to represent the `tx()` smooth term.
`...` | Not used in `BayesX.control`. For function `sx()` any extra arguments that should be passed to BayesX for this model term can be specified here. For function `tx()`, all variables the smooth should be a function of are specified here. For function `sam_BayesX()` all arguments that should be passed to `BayesX.control`.
`ctr` | Specifies the type of constraints that should be applied. `"main"`, both main effects should be removed; `"both"`, both main effects and varying effects should be removed; `"none"`, no constraint should be applied.
`xt` | A list of extra arguments to be passed to BayesX.
`special` | Should the `tx()` model term be treated as a special smooth. This must be set to `TRUE` if using the `sam_BayesX` sampler and should be set to `FALSE`, e.g., when using the `sam_GMCMC` sampler.
`object, knots` | See, function `smooth.construct`.
`prob` | Numeric, specifies the quantile to be modeled, see the examples.
`install` | Should package BayesXsrc be installed?

### Details

Function `sam_BayesX()` writes a BayesX `.prg` file and processes the data. Then, the function call the BayesX binary via function `run.bayesx`. After the BayesX sampler has finished, the function reads back in all the parameter samples that can then be used for further processing within `bamlss`, i.a.

The smooth term constructor functions `s` and `te` can be used with the `sam_BayesX()` sampler. When using `te` note that only one smoothing variance is estimated by BayesX.

For anisotropic penalties use function `tx()` and `tx3()`, the former currently supports smooth functions of two variables, while `tx3()` is supposed to model space-time interactions. Note that in `tx3()` the first variable represents time and the 2nd and 3rd variable the coordinates in space.

### Value

Function `sam_BayesX()` returns samples of parameters. The samples are provided as a `mcmc` matrix.

Function `BayesX.control()` returns a `list` with control arguments for BayesX.

Function `sx()` a `list` of class `"xx.smooth.spec"` and `"no.mgcv"`, where `"xx"` is a basis/type identifying code given by the `bs` argument.

Function `tx()` and `tx2()` a `list` of class `tensorX.smooth.spec`.

### Note

Note that this interface is still experimental and needs the newest version of the BayesX source code, which is not yet part of the BayesXsrc package on CRAN. The newest version can be installed with function `get_BayesXsrc`. Note that the function assumes that sh, subversion (svn) and R can be run from the command line!

Note that for setting up a new family object to be used with `sam_BayesX()` additional information needs to be supplied. The extra information must be placed within the family object in an named `list` element named `"bayesx"`. For each parameter of the distribution a character string with the corresponding BayesX `family` name and the `equationtype` must be supplied. See, e.g., the R code of `gaussian_bamlss` how the setup works.

For function `sx()` the following basis types are currently supported:

- `"ps"`: P-spline with second order difference penalty.

- `"mrf"`: Markov random fields: Defines a Markov random field prior for a spatial covariate, where geographical information is provided by a map object in boundary or graph file format (see function `read.bnd`, `read.gra` and `shp2bnd`), as an additional argument named `map`.

- `"re"`: Gaussian i.i.d. Random effects of a unit or cluster identification covariate.

Function `tx()` currently supports smooth terms with two variables.

### See Also

`bamlss`, `bamlss.frame`

### Examples

    ## Get newest version of BayesXsrc.
    ## Note: needs sh, svn and R build tools!
    ## get_BayesXsrc()
    ## Not run: if(require("BayesXsrc")) {
      ## Simulate some data
      set.seed(123)
      d <- GAMart()

      ## Estimate model with BayesX. Note
      ## that BayesX computes starting values, so
      ## these are not required by some optimizer function
      ## in bamlss()
      b1 <- bamlss(num ~ s(x1) + s(x2) + s(x3) + s(lon,lat),
        data = d, optimizer = FALSE, sampler = sam_BayesX)

      plot(b1)

      ## Same model with anisotropic penalty.
      b2 <- bamlss(num ~ s(x1) + s(x2) + s(x3) + tx(lon,lat),
        data = d, optimizer = FALSE, sampler = sam_BayesX)

      plot(b2)

      ## Quantile regression.
      b3_0.1 <- bamlss(num ~ s(x1) + s(x2) + s(x3) + tx(lon,lat),
        data = d, optimizer = FALSE, sampler = sam_BayesX,
        family = gF("quant", prob = 0.1))

      b3_0.9 <- bamlss(num ~ s(x1) + s(x2) + s(x3) + tx(lon,lat),
        data = d, optimizer = FALSE, sampler = sam_BayesX,
        family = gF("quant", prob = 0.9))

      ## Predict quantiles.
      p_0.1 <- predict(b3_0.1, term = "s(x2)")
      p_0.9 <- predict(b3_0.9, term = "s(x2)")

      ## Plot.
      plot2d(p_0.1 + p_0.9 ~ x2, data = d)
    }

    ## End(Not run)

[Package bamlss version 1.1-7 Index]