R: Fit a Cox regression model with elastic net regularization...

cox.fit {glmnet} | R Documentation

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

### Description

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`.)

### 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`.

### 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 FORTRAN 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.

[Package glmnet version 4.1-2 Index]