bamlss.frame: Create a Model Frame for BAMLSS
In bamlss: Bayesian Additive Models for Location, Scale, and Shape (and Beyond)

bamlss.frame

R Documentation

Create a Model Frame for BAMLSS

Description

This function parses the data and the model formula, or extended bamlss.formula, as well as the bamlss.family into a bamlss.frame object. The bamlss.frame then holds all model matrices and information that is needed for setting up estimation engines.

Usage

bamlss.frame(formula, data = NULL, family = "gaussian",
  weights = NULL, subset = NULL, offset = NULL,
  na.action = na.omit, contrasts = NULL,
  knots = NULL, specials = NULL, reference = NULL,
  model.matrix = TRUE, smooth.construct = TRUE,
  ytype = c("matrix", "vector", "integer"),
  scale.x = FALSE, scale.d = FALSE, ...)

Arguments

`formula`	A formula or extended formula, i.e., the `formula` can be a `list` of formulas where each list entry specifies the details of one parameter of the modeled response distribution, see `bamlss.formula`. For incorporating smooth terms, all model term constructors implemented in mgcv such as `s`, `te` and `ti` can be used, amongst others.
`data`	A `data.frame` or `list` containing the model response variable(s) and covariates specified in the `formula`. By default the variables are taken from `environment(formula)`: typically the environment from which `bamlss` is called.
`family`	A `bamlss.family` object, specifying the details of the modeled distribution such as the parameter names, the density function, link functions, etc.
`weights`	Prior weights on the data.
`subset`	An optional vector specifying a subset of observations to be used in the fitting process.
`offset`	Can be used to supply model offsets for use in fitting.
`na.action`	A function which indicates what should happen when the data contain `NA`'s. The default is set by the `na.action` setting of `options`, and is `na.omit` if set to `NULL`.
`contrasts`	An optional list. See the `contrasts.arg` of `model.matrix.default`.
`knots`	An optional list containing user specified knots, see the documentation of function `gam`.
`specials`	Specify new special terms here to be used with the `bamlss.formula`, see also `terms.object`.
`reference`	A `character` specifying a reference category, e.g., when fitting a multinomial model.
`model.matrix`	Logical, should model matrices for linear parts be returned?
`smooth.construct`	Logical, should model matrices, e.g., as returned from `smooth.construct` and `smoothCon` be part of returned `bamlss.frame`?.
`ytype`	For categorical responses, should the response be a vector or matrix. If `ytype == "matrix"` `bamlss.frame()` uses function `model.matrix` to construct the response matrix from levels. If the response is a factor `ytype == "integer"` will create an integer response.
`scale.x`	Logical, should the model matrices of the linear parts be scaled?
`scale.d`	Logical, should the numeric variables in the model frame be scaled?
`...`	Arguments passed to function `smooth.construct.bamlss.frame`.

Details

The function parses the data, the formula or the extended bamlss.formula as well as the bamlss.family into a model frame like object, the bamlss.frame. This object holds all necessary model matrices and information that is needed for model fitting engines. Per default, all package mgcv smooth term constructor functions like s, te, t2 and ti can be used (see also function smooth.construct), however, even special user defined constructors can be included, see the examples below.

Function bamlss.frame() uses function model.matrix.bamlss.frame to compute all design matrices for simple linear parts, all smooth terms are parsed with function smooth.construct.bamlss.frame.

It is also possible to create a "bamlss.frame" using hierarchical formulae, see the example below.

Value

An list of class "bamlss.frame" with the following elements:

`call`	The initial call.
`model.frame`	The `model.frame` used to compute all design matrices.
`formula`	The `bamlss.formula`.
`family`	The `bamlss.family` object.
`terms`	The `terms.bamlss` object.
`x`	A named list, the elements correspond to the parameters that are specified within the `bamlss.family` object. For each parameter the corresponding `formula`, a `fake.formula` only holding the covariate names, a `terms` object, a `model.matrix` for the linear part and a list `smooth.construct` holding all information for smooth terms as returned from function `link{smooth.construct.bamlss.frame}` is created.
`y`	The response data.

Examples

## Create a 'bamlss.frame'.
d <- GAMart()
f <- list(
  num ~ fac + s(x1) + s(x2) + te(lon, lat),
  sigma ~ id + s(x2) + s(x3)
)
bf <- bamlss.frame(f, data = d, family = "gaussian")

## Show parts of the 'bamlss.frame'.
print(bf)

## Categorical responses.
f <- list(
  cat ~ fac + s(x1) + s(x2)
)

bf <- bamlss.frame(f, data = d, family = "multinomial", reference = "low")
print(bf)

## The response is a matrix per default.
head(bf$y)

## 0/1 responses.
d <- cbind(d, model.matrix(~ -1 + cat, data = d))

f <- list(
  catnone ~ fac + s(x1),
  catlow ~ s(x2),
  catmedium ~ s(x3)
)

bf <- bamlss.frame(f, data = d, family = "multinomial")
print(bf)

## Hierarchical structures.
f <- list(
  num ~ s(x1) + s(x2) + id,
  id ~ te(lon, lat),
  sigma ~ s(x1) + fac
)

bf <- bamlss.frame(f, data = d, family = "gaussian")
print(bf)

## Special model term constructors,
## set up "new" constructor function and eval
## with bamlss.frame().
s77 <- function(...) {
  sm <- s(...)
  sm$label <- paste("s77(", paste(sm$term, collapse = ","), ")", sep = "")
  sm
}

f <- list(
  num ~ s77(x1) + s(x2) + id,
  sigma ~ s77(x1)
)

bf <- bamlss.frame(f, data = d, family = "gaussian", specials = "s77")
print(bf)
names(bf$x$mu$smooth.construct)

bamlss documentation built on Oct. 11, 2024, 5:07 p.m.