walsNB {WALS}

Weighted-Average Least Squares for Negative Binomial Regression

Description

Performs model averaging for NB2 regression models using the Weighted-Average Least Squares method of Huynh (2024a).

Usage

walsNB(x, ...)

## S3 method for class 'formula'
walsNB(
  formula,
  data,
  subset = NULL,
  na.action = NULL,
  weights = NULL,
  offset = NULL,
  link = "log",
  prior = weibull(),
  controlInitNB = controlNB(),
  model = TRUE,
  keepY = TRUE,
  keepX = FALSE,
  iterate = FALSE,
  tol = 1e-06,
  maxIt = 50,
  nIt = NULL,
  verbose = FALSE,
  ...
)

## S3 method for class 'matrix'
walsNB(
  x,
  x2,
  y,
  link = "log",
  subset = NULL,
  na.action = NULL,
  weights = NULL,
  offset = NULL,
  prior = weibull(),
  controlInitNB = controlNB(),
  model = TRUE,
  keepY = TRUE,
  keepX = FALSE,
  iterate = FALSE,
  tol = 1e-06,
  maxIt = 50,
  nIt = NULL,
  verbose = FALSE,
  ...
)

## Default S3 method:
walsNB(x, ...)

Arguments

x

Design matrix of focus regressors. Usually includes a constant (column full of 1s) and can be generated using model.matrix.

...

Arguments for workhorse walsNBfit.

formula

an object of class "Formula" (or one that can be coerced to that class, e.g. "formula"): a symbolic description of the model to be fitted. The details of model specification are given under ‘Details’.

data

an optional data frame, list or environment (or object coercible by as.data.frame to a data frame) containing the variables in the model. If not found in data, the variables are taken from environment(formula), typically the environment which the function is called from.

subset

an optional vector specifying a subset of observations to be used in the fitting process.

na.action

not implemented yet.

weights

not implemented yet.

offset

not implemented yet.

link

specifies the link function, currently only "log" is supported.

prior

Object of class "familyPrior". For example weibull or laplace.

controlInitNB

Controls estimation of starting values for one-step ML, see controlNB.

model

if TRUE (default), then the model.frame is stored in the return.

keepY

if TRUE (default), then the response is stored in the return.

keepX

if TRUE, then the model matrices are stored in the return. the return.

iterate

if TRUE then the WALS algorithm is iterated using the previous estimates as starting values.

tol

Only used if iterate = TRUE and nIt = NULL. If the Euclidean distance between the previous and current coefficient vector divided by the square root of the length of the vector falls below tol and the absolute difference between the previous and current dispersion parameter falls below tol, then the algorithm stops. See walsNBfitIterate for more details.

maxIt

Only used if iterate = TRUE and nIt = NULL. Aborts iterative fitting when number of iterations exceed maxIt.

nIt

Only used if iterate = TRUE. If this is specified, then tol is ignored and the algorithm iterates nIt times. This option should not be used unless the user has a specific reason to run the algorithm nIt times, e.g. for replication purposes.

verbose

If verbose = TRUE, then it prints the iteration process of internal function walsNBfitIterate (only relevant if iterate = TRUE).

x2

Design matrix of auxiliary regressors. Usually does not include a constant column and can also be generated using model.matrix.

y

Count response as vector.

Details

Computes WALS estimates when focus regressors (X1) are present in all submodels and model averaging takes place over the auxiliary regressors (X2).

Formulas typically contain two parts, i.e. they are of the form "y ~ X11 + X12 | X21 + X22", where the variables before "|" are the focus regressors (includes a constant by default) and the ones after "|" are the auxiliary regressors. If only a one-part formula is specified, then all regressors are considered as auxiliary regressors and only a constant is employed as focus regressor, i.e. "y ~ X1 + X2" is equivalent to "y ~ 1 | X1 + X2".

WARNING: Interactions in formula do not work properly yet. It is recommended to manually create the interactions beforehand and then to insert them as 'linear terms' in the formula.

See predict.walsGLM and predict.wals for some class methods that the fitted objects inherit from "walsGLM" and "wals", respectively.

walsNB.default() raises an error if x is not an object of class "matrix" or a class that extends "matrix". Otherwise it calls walsNB.matrix(). It is a modified version of glmboost.default from the mboost package version 2.9-8 (2023-09-06) (Hofner et al. 2014).

Value

walsNB.formula() returns an object of class "walsNB" which inherits from "walsGLM" and "wals". This is a list that contains all elements returned from walsNBfitIterate and additionally

cl

Call of the function.

formula

formula used.

terms

List containing the model terms of the focus and auxiliary regressors separately, as well as for the full model.

levels

List containing the levels of the focus and auxiliary regressors separately, as well as for the full model.

contrasts

List containing the contrasts of the design matrices of focus and auxiliary regressors.

model

If model = TRUE, contains the model frame.

See returns of walsNBfit and walsNBfitIterate for more details.

walsNB.matrix() returns an object of class "walsNBmatrix", which inherits from "walsNB", "walsGLMmatrix", "walsGLM" and "wals". This is a list that contains all elements returned from walsNBfitIterate and additionally the call in cl.

walsNB.default() raises an error if x is not an object of class "matrix" or a class that extends "matrix". Otherwise returns an object of class "walsNBmatrix". See above for more details.

References

Hofner B, Mayr A, Robinzonov N, Schmid M (2014). “Model-based Boosting in R: A Hands-on Tutorial Using the R Package mboost.” Computational Statistics, 29, 3–35.

Huynh K (2024a). “Weighted-Average Least Squares for Negative Binomial Regression.” arXiv 2404.11324, arXiv.org E-Print Archive. doi:10.48550/arXiv.2404.11324.

Examples

## Example for walsNB.formula()
data("NMES1988", package = "AER")

fitWeibull <- walsNB(visits ~ health + chronic + age + gender | I((age^2)/10) +
                     married + region, data = NMES1988, prior = weibull())
summary(fitWeibull)

fitLaplace <- walsNB(visits ~ health + chronic + age + gender | I((age^2)/10) +
                     married + region, data = NMES1988, prior = laplace())
summary(fitLaplace)

## Example for walsNB.matrix()
data("NMES1988", package = "AER")
X <- model.matrix(visits ~ health + chronic + age + gender + married + region,
                  data = NMES1988)
X1 <- X[, c("(Intercept)", "healthpoor", "healthexcellent", "chronic",
        "age", "gendermale")]
X2 <- X[, c("marriedyes", "regionnortheast", "regionmidwest", "regionwest")]
y <- NMES1988$visits
fit <- walsNB(X1, X2, y, prior = weibull())
summary(fit)