R: Create a Model Frame for BAMLSS

bamlss.frame {bamlss} | 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"` 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)

    ## 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)

[Package bamlss version 1.1-7 Index]