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

In flam: Fits Piecewise Constant Models with Data-Adaptive Knots

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.

See Also

predict.flam, plot.flam, summary.flam

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

flam documentation built on May 2, 2019, 8:27 a.m.