Fit a Cox regression model with elastic net regularization for a single value of lambda

Fit a Cox regression model via penalized maximum likelihood for a single value of lambda. Can deal with (start, stop] data and strata, as well as sparse design matrices.

Usage

cox.fit(
  x,
  y,
  weights,
  lambda,
  alpha = 1,
  offset = rep(0, nobs),
  thresh = 1e-10,
  maxit = 1e+05,
  penalty.factor = rep(1, nvars),
  exclude = c(),
  lower.limits = -Inf,
  upper.limits = Inf,
  warm = NULL,
  from.cox.path = FALSE,
  save.fit = FALSE,
  trace.it = 0
)

Arguments

x: Input matrix, of dimension nobs x nvars; each row is an observation vector. If it is a sparse matrix, it is assumed to be unstandardized. It should have attributes xm and xs, where xm(j) and xs(j) are the centering and scaling factors for variable j respsectively. If it is not a sparse matrix, it is assumed that any standardization needed has already been done.
y: Survival response variable, must be a Surv or stratifySurv object.
weights: Observation weights. cox.fit does NOT standardize these weights.
lambda: A single value for the lambda hyperparameter.
alpha: See glmnet help file
offset: See glmnet help file
thresh: Convergence threshold for coordinate descent. Each inner coordinate-descent loop continues until the maximum change in the objective after any coefficient update is less than thresh times the null deviance. Default value is 1e-10.
maxit: Maximum number of passes over the data; default is 10^5. (If a warm start object is provided, the number of passes the warm start object performed is included.)
penalty.factor: See glmnet help file
exclude: See glmnet help file
lower.limits: See glmnet help file
upper.limits: See glmnet help file
warm: Either a glmnetfit object or a list (with name beta containing coefficients) which can be used as a warm start. Default is NULL, indicating no warm start. For internal use only.
from.cox.path: Was cox.fit() called from cox.path()? Default is FALSE.This has implications for computation of the penalty factors.
save.fit: Return the warm start object? Default is FALSE.
trace.it: Controls how much information is printed to screen. If trace.it=2, some information about the fitting procedure is printed to the console as the model is being fitted. Default is trace.it=0 (no information printed). (trace.it=1 not used for compatibility with glmnet.path.)

Value

An object with class "coxnet", "glmnetfit" and "glmnet". The list returned contains more keys than that of a "glmnet" object.

a0: Intercept value, NULL for "cox" family.
beta: A nvars x 1 matrix of coefficients, stored in sparse matrix format.
df: The number of nonzero coefficients.
dim: Dimension of coefficient matrix.
lambda: Lambda value used.
dev.ratio: The fraction of (null) deviance explained. The deviance calculations incorporate weights if present in the model. The deviance is defined to be 2*(loglike_sat - loglike), where loglike_sat is the log-likelihood for the saturated model (a model with a free parameter per observation). Hence dev.ratio=1-dev/nulldev.
nulldev: Null deviance (per observation). This is defined to be 2*(loglike_sat -loglike(Null)). The null model refers to the 0 model.
npasses: Total passes over the data.
jerr: Error flag, for warnings and errors (largely for internal debugging).
offset: A logical variable indicating whether an offset was included in the model.
call: The call that produced this object.
nobs: Number of observations.
warm_fit: If save.fit=TRUE, output of C++ routine, used for warm starts. For internal use only.
family: Family used for the model, always "cox".
converged: A logical variable: was the algorithm judged to have converged?
boundary: A logical variable: is the fitted value on the boundary of the attainable values?
obj_function: Objective function value at the solution.

Details

WARNING: Users should not call cox.fit directly. Higher-level functions in this package call cox.fit as a subroutine. If a warm start object is provided, some of the other arguments in the function may be overriden.

cox.fit solves the elastic net problem for a single, user-specified value of lambda. cox.fit works for Cox regression models, including (start, stop] data and strata. It solves the problem using iteratively reweighted least squares (IRLS). For each IRLS iteration, cox.fit makes a quadratic (Newton) approximation of the log-likelihood, then calls elnet.fit to minimize the resulting approximation.

In terms of standardization: cox.fit does not standardize x and weights. penalty.factor is standardized so that they sum up to nvars.