sam_BayesX {bamlss}

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() of the BayesXsrc package. 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)