Create a Model Frame for BAMLSS

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.

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" codebamlss.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.

See also

bamlss, bamlss.formula, bamlss.family, smooth.construct.bamlss.frame, model.matrix.bamlss.frame

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)
#> 'bamlss.frame' structure: 
#>   ..$ call 
#>   ..$ model.frame 
#>   ..$ formula 
#>   ..$ family 
#>   ..$ terms 
#>   ..$ x 
#>   .. ..$ mu 
#>   .. .. ..$ formula 
#>   .. .. ..$ fake.formula 
#>   .. .. ..$ terms 
#>   .. .. ..$ model.matrix 
#>   .. .. ..$ smooth.construct 
#>   .. ..$ sigma 
#>   .. .. ..$ formula 
#>   .. .. ..$ fake.formula 
#>   .. .. ..$ terms 
#>   .. .. ..$ model.matrix 
#>   .. .. ..$ smooth.construct 
#>   ..$ y 
#>   .. ..$ num 
#>   ..$ delete 

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

bf <- bamlss.frame(f, data = d, family = "multinomial", reference = "low")
print(bf)
#> 'bamlss.frame' structure: 
#>   ..$ call 
#>   ..$ model.frame 
#>   ..$ formula 
#>   ..$ family 
#>   ..$ terms 
#>   ..$ x 
#>   .. ..$ none 
#>   .. .. ..$ formula 
#>   .. .. ..$ fake.formula 
#>   .. .. ..$ terms 
#>   .. .. ..$ model.matrix 
#>   .. .. ..$ smooth.construct 
#>   .. ..$ medium 
#>   .. .. ..$ formula 
#>   .. .. ..$ fake.formula 
#>   .. .. ..$ terms 
#>   .. .. ..$ model.matrix 
#>   .. .. ..$ smooth.construct 
#>   .. ..$ high 
#>   .. .. ..$ formula 
#>   .. .. ..$ fake.formula 
#>   .. .. ..$ terms 
#>   .. .. ..$ model.matrix 
#>   .. .. ..$ smooth.construct 
#>   ..$ y 
#>   .. ..$ cat 
#>   ..$ delete 

## The response is a matrix per default.
head(bf$y)
#>   cat.none cat.medium cat.high cat.low
#> 1        0          0        0       1
#> 2        0          0        1       0
#> 3        0          0        0       1
#> 4        1          0        0       0
#> 5        0          1        0       0
#> 6        0          0        1       0

## 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)
#> 'bamlss.frame' structure: 
#>   ..$ call 
#>   ..$ model.frame 
#>   ..$ formula 
#>   ..$ family 
#>   ..$ terms 
#>   ..$ x 
#>   .. ..$ pi 
#>   .. .. ..$ formula 
#>   .. .. ..$ fake.formula 
#>   .. .. ..$ terms 
#>   .. .. ..$ model.matrix 
#>   .. .. ..$ smooth.construct 
#>   ..$ y 
#>   .. ..$ catnone 
#>   ..$ delete 

## 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)
#> 'bamlss.frame' structure: 
#>   ..$ call 
#>   ..$ model.frame 
#>   ..$ formula 
#>   ..$ family 
#>   ..$ terms 
#>   ..$ x 
#>   .. ..$ mu 
#>   .. .. ..$ h1 
#>   .. .. .. ..$ formula 
#>   .. .. .. ..$ fake.formula 
#>   .. .. .. ..$ terms 
#>   .. .. .. ..$ model.matrix 
#>   .. .. .. ..$ smooth.construct 
#>   .. .. ..$ h2 
#>   .. .. .. ..$ formula 
#>   .. .. .. ..$ fake.formula 
#>   .. .. .. ..$ terms 
#>   .. .. .. ..$ match.index 
#>   .. .. .. ..$ nodups 
#>   .. .. .. ..$ model.matrix 
#>   .. .. .. ..$ smooth.construct 
#>   .. ..$ sigma 
#>   .. .. ..$ formula 
#>   .. .. ..$ fake.formula 
#>   .. .. ..$ terms 
#>   .. .. ..$ model.matrix 
#>   .. .. ..$ smooth.construct 
#>   ..$ y 
#>   .. ..$ num 
#>   ..$ delete 

## 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")
#> Error in s77(x1): could not find function "s77"
print(bf)
#> 'bamlss.frame' structure: 
#>   ..$ call 
#>   ..$ model.frame 
#>   ..$ formula 
#>   ..$ family 
#>   ..$ terms 
#>   ..$ x 
#>   .. ..$ mu 
#>   .. .. ..$ h1 
#>   .. .. .. ..$ formula 
#>   .. .. .. ..$ fake.formula 
#>   .. .. .. ..$ terms 
#>   .. .. .. ..$ model.matrix 
#>   .. .. .. ..$ smooth.construct 
#>   .. .. ..$ h2 
#>   .. .. .. ..$ formula 
#>   .. .. .. ..$ fake.formula 
#>   .. .. .. ..$ terms 
#>   .. .. .. ..$ match.index 
#>   .. .. .. ..$ nodups 
#>   .. .. .. ..$ model.matrix 
#>   .. .. .. ..$ smooth.construct 
#>   .. ..$ sigma 
#>   .. .. ..$ formula 
#>   .. .. ..$ fake.formula 
#>   .. .. ..$ terms 
#>   .. .. ..$ model.matrix 
#>   .. .. ..$ smooth.construct 
#>   ..$ y 
#>   .. ..$ num 
#>   ..$ delete 
names(bf$x$mu$smooth.construct)
#> NULL