flam (version 3.2)

flam: 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.

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

# NOT RUN {
#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")
# }
# NOT RUN {
#'flam' returns an object of the class 'flam'
#see ?'flam-package' for an example using S3 methods for 'flam' objects

# }