This function creates an extended BAMLSS formula. In combination with a bamlss.family object, each parameter of the response distribution is linked to a single formula. If no formula is supplied for a parameter, a simple intercept only model is created. Moreover, the function identifies hierarchical structures, see the examples. This function is useful for creating complex model.frames for (hierarchical) multi-parameter models and is used by function bamlss.frame.

bamlss.formula(formula, family = NULL, specials = NULL, env = NULL, ...)

Arguments

formula

A simple formula, or a list of simple formulae, or an extended Formula. For formula lists or extended Formulae, each single formula represents one model for the respective parameter as specified in the family object.

family

A bamlss.family object.

specials

A character vector specifying special functions to be used within formulae, see terms.object.

env

The environment that should be assigned to the formula.

...

Arguments passed to the family.

Value

A named list of class "bamlss.formula". Each list entry specifies a model, e.g., for one parameter of a provided bamlss.family object. Each entry (parameter model) then holds:

formula

A simple formula.

fake.formula

A formula with all function calls being dropped, e.g., the formula y ~ s(x1) + s(x2) is represented in the fake.formula entry as y ~ x1 + x2. The fake.formula is useful for creating model frames.

Examples

## Simple formula without family object.
f <- bamlss.formula(y ~ x1 + s(x2))
print(f)
#> Formula y:
#> ---
#> y ~ x1 + s(x2)
print(str(f))
#> List of 1
#>  $ y:List of 2
#>   ..$ formula     :Class 'formula'  language y ~ x1 + s(x2)
#>   ..$ fake.formula:Class 'formula'  language y ~ 1 + x1 + x2
#>  - attr(*, ".Environment")=<environment: 0x55a3c5e8c468> 
#>  - attr(*, "class")= chr [1:2] "bamlss.formula" "list"
#> NULL

## Complex formula with list of formulae.
f <- list(
  y1 ~ x1 + s(x2),
  y2 ~ x3 + te(lon, lat),
  u ~ x4 + x1
)

f <- bamlss.formula(f)
print(f)
#> Formula y1:
#> ---
#> y1 ~ x1 + s(x2)
#> 
#> Formula y2:
#> ---
#> y2 ~ x3 + te(lon, lat)
#> 
#> Formula u:
#> ---
#> u ~ x4 + x1
print(names(f))
#> [1] "y1" "y2" "u" 

## Same formula but using extended formulae
## of package Formula.
f <- y1|y2|u ~ x1 + s(x2)|x3 + te(lon,lat)|x4 + x1
f <- bamlss.formula(f)
print(f)
#> Formula y1:
#> ---
#> y1 ~ x1 + s(x2)
#> 
#> Formula y2:
#> ---
#> y2 ~ x3 + te(lon, lat)
#> 
#> Formula u:
#> ---
#> u ~ x4 + x1
print(names(f))
#> [1] "y1" "y2" "u" 

## Using a bamlss family object, e.g., gaussian_bamlss().
## The family has two parameters, mu and sigma, for
## each parameter one formula is returned. If no
## formula is specified an intercept only model is
## generated for the respective parameter.
f <- bamlss.formula(y ~ x1 + s(x2), family = gaussian_bamlss)

## Note, same as:
f <- bamlss.formula(y ~ x1 + s(x2), family = "gaussian")
print(f)
#> Formula mu:
#> ---
#> y ~ x1 + s(x2)
#> 
#> Formula sigma:
#> ---
#> sigma ~ 1

## Specify model for parameter sigma, too
f <- list(
  y ~ x1 + s(x2),
  sigma ~ x2 + te(lon, lat)
)
f <- bamlss.formula(f, family = "gaussian")
print(f)
#> Formula mu:
#> ---
#> y ~ x1 + s(x2)
#> 
#> Formula sigma:
#> ---
#> sigma ~ x2 + te(lon, lat)

## With complex hierarchical structures,
## each parameter is another list of formulae,
## indicated by the h1,...,hk, names.
f <- list(
  y ~ x1 + s(x2) + id1,
  sigma ~ x2 + te(lon, lat) + id2,
  id1 ~ s(x3) + x4 + s(id3),
  id3 ~ x5 + s(x5, x6),
  id2 ~ x7
)
f <- bamlss.formula(f, family = "gaussian")
print(f)
#> Formula mu:
#> ---
#> h1: y ~ x1 + s(x2) + id1
#> h2: id1 ~ s(x3) + x4 + s(id3)
#> h3: id3 ~ x5 + s(x5, x6)
#> 
#> Formula sigma:
#> ---
#> h1: sigma ~ x2 + te(lon, lat) + id2
#> h2: id2 ~ x7