as.families: Include 'gamlss' families in the boosting framework of...

View source: R/as.families.R

as.familiesR Documentation

Include gamlss families in the boosting framework of gamboostLSS

Description

The function as.families() provides an interface to apply the available distributions (families) of the gamlss.dist package for boosting GAMLSS via gamboostLSS.

The function automatically builds sub-families for every distribution parameter and uses the constructor function Families to build a families object, which can be then included in the fitting functions gamboostLSS and glmboostLSS.

Usage

as.families(fname = "NO", stabilization = c("none", "MAD", "L2"),
            mu = NULL, sigma = NULL, nu = NULL, tau = NULL,
            mu.link = NULL, sigma.link = NULL, nu.link = NULL, 
            tau.link = NULL)

## a wrapper to as.families:
gamlss.Families(...)

Arguments

fname

name of the distribution in the gamlss framework, as specified in the gamlss.dist package (e.g., "NO" for a normal distribution with parameters mu and sigma). Alternatively, one can directly specify the function (i.e., NO) or the evaluated function NO().

mu

possible offset value for parameter mu.

sigma

possible offset value for parameter sigma.

nu

possible offset value for parameter nu.

tau

possible offset value for parameter tau.

mu.link

different link function for parameter mu.

sigma.link

different link function for parameter sigma.

nu.link

different link function for parameter nu.

tau.link

different link function for parameter tau.

stabilization

governs if the negative gradient should be standardized in each boosting step. It can be either "none" or "MAD". For details see Families.

...

same arguments as above.

Details

The function aims at providing an interface to include all available GAMLSS distributions which are implemented with the original gamlss.dist package in the model-based boosting framework. The user specifies the name of the family (as it is called in gamlss.dist), and the function automatically builds the corresponding mboost-like sub-families and the final families object, which can be then used with the fitting functions gamboostLSS and glmboostLSS.

If no different link functions are specified, the standard links for the corresponding family in gamlss.dist are applied.

To extract the necessary information regarding partial derivatives (for the ngradient - see Family for details) and the log-likelihood (for the loss) the gamlss.dist package is loaded. If the package is not installed yet, this will prompt an error message.

The functions gamlss1parMu, gamlss2parMu, gamlss2parSigma, ... , gamlss4parTau are called internally to construct the sub-families. For one-parametric distributions, the function will prompt a warning and returns a mboost family, which can be then used by the fitting functions of the mboost package.

For information on GAMLSS theory see Rigby and Stasinopoulos (2005), lists of available distributions are provided at https://www.gamlss.com/. For more on details boosting GAMLSS see Mayr et al. (2012). Hofner et al. (2016) provides a worked example and more details on as.families.

To (potentially) stabilize the model estimation by standardizing the negative gradients one can use the argument stabilization of the families. See Families for details.

Value

An object of class families. If the user specifies a one-parametric distribution, an object of class family is returned.

Author(s)

The help of Mikis Stasinpoulos during the work on this function is gratefully acknowledged.

References

B. Hofner, A. Mayr, M. Schmid (2016). gamboostLSS: An R Package for Model Building and Variable Selection in the GAMLSS Framework. Journal of Statistical Software, 74(1), 1-31.

Available as vignette("gamboostLSS_Tutorial").

Mayr, A., Fenske, N., Hofner, B., Kneib, T. and Schmid, M. (2012): Generalized additive models for location, scale and shape for high-dimensional data - a flexible approach based on boosting. Journal of the Royal Statistical Society, Series C (Applied Statistics) 61(3): 403-427.

Rigby, R. A. and D. M. Stasinopoulos (2005). Generalized additive models for location, scale and shape (with discussion). Journal of the Royal Statistical Society, Series C (Applied Statistics), 54, 507-554.

See Also

gamlss.dist for available distributions in the gamlss framework.

Families for a documentation of pre-implemented distributions for gamboostLSS, as well as possibilities for user-defined distributions.

Examples

## simulate small example
set.seed(123)
x <- runif(1000)

y <- rnorm(mean = 2 + 3 * x,        # effect on mu
           sd   = exp( 1 - 1 * x ), # effect on sigma
           n    = 1000)

## boosting
glmss <- glmboostLSS(y ~ x, families = as.families("NO"))
## the same:
if (require("gamlss.dist")) {
    glmss <- glmboostLSS(y ~ x, families = as.families(NO))
    glmss <- glmboostLSS(y ~ x, families = as.families(NO()))
}

coef(glmss, off2int = TRUE)

## compare to gamlss
library(gamlss)
glmss2 <- gamlss(y ~ x, sigma.formula = ~x, family = "NO")
coef(glmss2)
glmss2$sigma.coef


gamboostLSS documentation built on March 31, 2023, 9:35 p.m.