R: Fit the Fused Lasso Additive Model for a Sequence of Tuning...

flam {flam}

R Documentation

Fit the Fused Lasso Additive Model for a Sequence of Tuning Parameters

Description

Fit an additive model where each component is estimated to piecewise constant with a small number of adaptively-chosen knots. The model is fit for a sequence of tuning parameters. In particular, this function implements the "fused lasso additive model", as proposed in Petersen, A., Witten, D., and Simon, N. (2014). Fused Lasso Additive Model. arXiv preprint arXiv:1409.5391.

Usage

flam(x, y, lambda.min.ratio = 0.01, n.lambda = 50, lambda.seq = NULL,
alpha.seq = 1, family = "gaussian", method = "BCD", tolerance = 10e-6)

Arguments

`x`	n x p covariate matrix. May have p > n.
`y`	n-vector containing the outcomes for the n observations in `x`.
`lambda.min.ratio`	smallest value for `lambda.seq`, as a fraction of the maximum lambda value, which is the data-derived smallest value for which all estimated functions are zero. The default is 0.01.
`n.lambda`	the number of lambda values to consider - the default is 50.
`lambda.seq`	a user-supplied sequence of positive lambda values to consider. The typical usage is to calculate `lambda.seq` using `lambda.min.ratio` and `n.lambda`, but providing `lambda.seq` overrides this. If provided, `lambda.seq` should be a decreasing sequence of values, since `flam` relies on warm starts for speed. Thus fitting the model for a whole sequence of lambda values is often faster than fitting for a single lambda value. Note that the model is fit for all combinations of `alpha.seq` and `lambda.seq`, so all values of `lambda.seq` provided should be unique.
`alpha.seq`	the value(s) of alpha to consider - default is 1. Values must be in [0,1] with values near 0 prioritizing sparsity of functions and values near 1 prioritizing limiting the number of knots. Empirical evidence suggests using alpha of 1 when p < n and alpha of 0.75 when p > n. Note that the model is fit for all combinations of `alpha.seq` and `lambda.seq`, so all values of `alpha.seq` provided should be unique.
`family`	specifies the loss function to use. Currently supports squared error loss (default; `family="gaussian"`) and logistic loss (`family="binomial"`).
`method`	specifies the optimization algorithm to use. Options are block-coordinate descent (default; `method="BCD"`), generalized gradient descent (`method="GGD"`), or generalized gradient descent with backtracking (`method="GGD.backtrack"`). This argument is ignored if `family="binomial"`.
`tolerance`	specifies the convergence criterion for the objective (default is 10e-6).

Value

An object with S3 class "flam".

`all.alpha`	vector of alpha values considered. This will be m times longer than the user-specified `alpha.seq` where m is the length of the user-specified `lambda.seq`.
`all.lambda`	vector of lambda values considered. This will be q times longer than the user-specified `lambda.seq` where q is the length of the user-specified `alpha.seq`.
`theta.hat.list`	list of estimated theta matrices of dimension n x p. Note that the predicted values `y.hat.mat[i,] = g(beta0.hat.vec[i] +` `rowSums(theta.hat.list[[i]]))` where `g` is the link function (identity if `family="gaussian"` and expit if `family="binomial"`).
`f.hat.list`	list of estimated function matrices of dimension n x p. Note that `f.hat.list[[i]]` is `theta.hat.list[[i]]` with the elements of each column ordered in terms of increasing `x[,i]`.
`beta0.hat.vec`	vector of estimated intercepts with `beta0.hat.vec[i]` being the intercept for the model with tuning parameters `all.alpha[i]` and `all.lambda[i]`.
`y.hat.mat`	matrix with `y.hat.mat[i,]` containing fitted y values for the tuning parameters `all.alpha[i]` and `all.lambda[i]`.
`non.sparse.list`	list with `non.sparse.list[[i]]` containing the indices for the predictors with non-sparse fits for the tuning parameters `all.alpha[i]` and `all.lambda[i]`.
`num.non.sparse`	vector with `num.non.sparse[i]` indicating the number of non-sparse predictor fits for the tuning parameters `all.alpha[i]` and `all.lambda[i]`.
`y`	as specified by user.
`x`	as specified by user.
`family`	as specified by user (or default).
`method`	as specified by user (or default).
`tolerance`	as specified by user (or default).
`call`	the matched call.

Author(s)

Ashley Petersen

References

Petersen, A., Witten, D., and Simon, N. (2014). Fused Lasso Additive Model. arXiv preprint arXiv:1409.5391.

Examples

#See ?'flam-package' for a full example of how to use this package

#generate data
set.seed(1)
data <- sim.data(n = 50, scenario = 1, zerof = 10, noise = 1)

#fit model for a range of lambda chosen by default and alpha's of 0.75 and 1
flam.out <- flam(x = data$x, y = data$y, alpha.seq = c(0.75, 1))
#or specify desired lambda sequence (often equally spaced on log scale)
#should be a decreasing sequence of several values for computational speed
user.lambda.seq <- exp(seq(log(50), log(1), len=40))
flam.out2 <- flam(x = data$x, y = data$y, lambda.seq = user.lambda.seq)

## Not run: 
#alternatively, generate data for logistic FLAM model
data2 <- sim.data(n = 50, scenario = 1, zerof = 10, family = "binomial")
#fit the FLAM model using logistic loss
flam.logistic.out <- flam(x = data2$x, y = data2$y, family = "binomial")

## End(Not run)

#'flam' returns an object of the class 'flam'
#see ?'flam-package' for an example using S3 methods for 'flam' objects

[Package flam version 3.2 Index]