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.

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        1          0        0       0
#> 2        0          0        0       1
#> 3        0          0        1       0
#> 4        0          1        0       0
#> 5        0          0        1       0
#> 6        0          1        0       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

Arguments

Details

Value

See also

Examples