boost: Boosting BAMLSS

Description

Optimizer functions for gradient and likelihood boosting with bamlss. In each boosting iteration the function selects the model term with the largest contribution to the log-likelihood, AIC or BIC.

Usage

## Gradient boosting optimizer.
boost(x, y, family, weights = NULL,
  offset = NULL, nu = 0.1, nu.adapt = TRUE, df = 4, maxit = 400,
  mstop = NULL, maxq = NULL, qsel.splitfactor = FALSE,
  verbose = TRUE, digits = 4, flush = TRUE,
  eps = .Machine$double.eps^0.25,
  nback = NULL, plot = TRUE, initialize = TRUE,
  stop.criterion = NULL, select.type = 1,
  force.stop = TRUE, hatmatrix = !is.null(stop.criterion),
  reverse.edf = FALSE, approx.edf = FALSE,
  always = FALSE, ...)
## Modified likelihood based boosting.
boostm(x, y, family, offset = NULL,
  nu = 0.1, df = 3, maxit = 400, mstop = NULL,
  verbose = TRUE, digits = 4, flush = TRUE,
  eps = .Machine$double.eps^0.25, plot = TRUE,
  initialize = TRUE, stop.criterion = "BIC",
  force.stop = !is.null(stop.criterion),
  do.optim = TRUE, always = FALSE, ...)
## Boosting summary extractor.
boost_summary(object, ...)
## Plot all boosting paths.
boost_plot(x, which = c("loglik", "loglik.contrib", "parameters",
  "aic", "bic", "user"), intercept = TRUE, spar = TRUE, mstop = NULL,
  name = NULL, drop = NULL, labels = NULL, color = NULL, ...)
## Boosting summary printing and plotting.
# S3 method for boost_summary
print(x, summary = TRUE, plot = TRUE,
  which = c("loglik", "loglik.contrib"), intercept = TRUE,
  spar = TRUE, ...)
# S3 method for boost_summary
plot(x, ...)
## Model frame for out-of-sample selection.
boost_frame(formula, train, test, family = "gaussian", ...)

Arguments

For function boost() the x list, as returned from function bamlss.frame, holding all model matrices and other information that is used for fitting the model. For the plotting function the corresponding bamlss object fitted with the boost() optimizer.

The model response, as returned from function bamlss.frame.

family

A bamlss family object, see family.bamlss.

weights

Prior weights on the data, as returned from function bamlss.frame.

offset

Can be used to supply model offsets for use in fitting, returned from function bamlss.frame.

Numeric, between [0, 1], controls the step size, i.e., the amount that should be added to model term parameters.

nu.adapt

Logical. If set to TRUE (default) step size nu is divided by 2, if current boosting iteration did not improve the loglikelihood.

Integer, defines the initial degrees of freedom that should be assigned to each smooth model term. May also be a named vector, the names must match the model term labels, e.g., as provided in summary.bamlss.

maxit

Integer, the maximum number of boosting iterations.

mstop

For convenience, overwrites maxit.

maxq

Integer, defines the maximum number of selected base-learners. The algorithm stops if this numer is exceeded.

qsel.splitfactor

Logical, if set to TRUE dummy variables of categorical predictors are counted individually.

name

Character, the name of the coefficient (group) that should be plotted. Note that the string provided in name will be removed from the labels on the 4th axis.

drop

Character, the name of the coefficient (group) that should not be plotted.

labels

A character string of labels that should be used on the 4 axis.

color

Colors or color function that creates colors for the (group) paths.

verbose

Print information during runtime of the algorithm.

digits

Set the digits for printing when verbose = TRUE.

flush

use flush.console for displaying the current output in the console.

eps

The tolerance used as stopping mechanism, see argument nback.

nback

Integer. If nback is not NULL, then the algorithm stops if the the change in the log-likelihood of the last nback iterations is smaller or equal to eps. If maxit = NULL the maximum number of iterations is set to 10000.

plot

Should the boosting summary be printed and plotted?

initialize

Logical, should intercepts be initialized?

stop.criterion

Character, selects the information criterion that should be used to determine the optimum number of boosting iterations. Either "AIC" or "BIC" is possible. Note that this feature requires to compute hat-matrices for each distributional parameter, therefore, the routine may be slow and computer storage intensive.

select.type

Should model terms be selected by the log-likelihood contribution, select.type = 1, or by the corresponding stop.criterion, select.type = 2.

force.stop

Logical, should the algorithm stop if the information criterion increases?

do.optim

Logical. Should smoothing parameters be optimized in each boosting iteration?

hatmatrix

Logical, if set to TRUE the hat-matrices for each distributional parameter will be computed. The hat-matrices are used to determine the effective (equivalent) degrees of freedom in each boosting iteration, i.e., it is possible to compute information criteria like the AIC or BIC for selecting the optimum number of boosting iterations.

reverse.edf

Logical. Instead of computing degrees of freedom with hat-matrices, the actual smoothing parameters are reverse engineered to compute the corresponding actual smoother matrix. Note that this option is still experimental.

approx.edf

Logical. Another experimental and fast approximation of the degrees of freedom.

always

Logical or character. Should the intercepts forced to be updated in each boosting iteration? If always = TRUE each intercept of each distributional parameter is updated, if always = "best" only the intercept corresponding to the distributional of the best fitting model term is updated.

object

A bamlss object that was fitted using boost().

summary

Should the summary be printed?

which

Which of the three provided plots should be created?

intercept

Should the coefficient paths of intercepts be dropped in the plot?

spar

Should graphical parmeters be set with par?

formula

See bamlss.frame.

train, test

Data frames used for training and testing the model..

…

For function boost(), arguments passed to bamlss.engine.setup. for function boost_summary() arguments passed to function print.boost_summary().

Value

For function boost_summary() a list containing information on selection frequencies etc. For function boost() and boostm() a list containing the following objects:

fitted.values

A named list of the fitted values based on the last boosting iteration of the modeled parameters of the selected distribution.

parameters

A matrix, each row corresponds to the parameter values of one boosting iteration.

boost_summary

The boosting summary which can be printed and plotted.

WARNINGS

The function does not take care of variable scaling for the linear parts! This must be done by the user, e.g., one option is to use argument scale.d in function bamlss.frame, which uses scale.

Function boost() does not select the optimum stopping iteration! The modified likelihood based algorithm implemented in function boostm() is still experimental!

Examples

Run this code

# NOT RUN {
## Simulate data.
set.seed(123)
d <- GAMart()

## Estimate model.
f <- num ~ x1 + x2 + x3 + lon + lat +
  s(x1) + s(x2) + s(x3) + s(lon) + s(lat) + te(lon,lat)

b <- bamlss(f, data = d, optimizer = boost,
  sampler = FALSE, scale.d = TRUE, nu = 0.01,
  maxit = 1000, plot = FALSE)

## Plot estimated effects.
plot(b)

## Print and plot the boosting summary.
boost_summary(b, plot = FALSE)
boost_plot(b, which = 1)
boost_plot(b, which = 2)
boost_plot(b, which = 3, name = "mu.s.te(lon,lat).")

## Extract estimated parameters for certain
## boosting iterations.
parameters(b, mstop = 1)
parameters(b, mstop = 100)

## Also works with predict().
head(do.call("cbind", predict(b, mstop = 1)))
head(do.call("cbind", predict(b, mstop = 100)))

## Another example using the modified liklihood
## bootsing algorithm.
f <- list(
  num ~ x1 + x2 + x3 + lon + lat +
    s(x1) + s(x2) + s(x3) + s(lon) + s(lat) + te(lon,lat),
  sigma ~ x1 + x2 + x3 + lon + lat +
    s(x1) + s(x2) + s(x3) + s(lon) + s(lat) + te(lon,lat)
)

b <- bamlss(f, data = d, optimizer = boostm,
  sampler = FALSE, scale.d = TRUE, nu = 0.05,
  maxit = 400, stop.criterion = "AIC", force.stop = FALSE)

## Plot estimated effects.
plot(b)

## Plot AIC and log-lik contributions.
boost_plot(b, "AIC")
boost_plot(b, "loglik.contrib")

## Out-of-sample selection of model terms.
set.seed(123)
d <- GAMart(n = 5000)

## Split data into training and testing
i <- sample(1:2, size = nrow(d), replace = TRUE)
d.test <- subset(d, i == 1)
d.train <- subset(d, i == 2)

## Model formula
f <- list(
  num ~ s(x1) + s(x2) + s(x3),
  sigma ~ s(x1) + s(x2) + s(x3)
)

## Create model frame for out-of-sample selection.
sm <- boost_frame(f, train = d.train, test = d.test, family = "gaussian")

## Out-of-sample selection function.
sfun <- function(parameters) {
  sm$parameters <- parameters
  p <- predict(sm, type = "parameter")
  -1 * sum(sm$family$d(d.test$num, p, log = TRUE))
}

## Start boosting with out-of-sample negative
## log-likelihood selection of model terms.
b <- bamlss(f, data = d.train, sampler = FALSE, optimizer = boost,
  selectfun = sfun, always = "best")

## Plot curve of negative out-of-sample log-likelihood.
boost_plot(b, which = "user")
# }