% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/glmnetFlex.R
\name{glmnet.fit}
\alias{glmnet.fit}
\title{Fit a GLM with elastic net regularization for a single value of lambda}
\usage{
glmnet.fit(
  x,
  y,
  weights,
  lambda,
  alpha = 1,
  offset = rep(0, nobs),
  family = gaussian(),
  intercept = TRUE,
  thresh = 1e-10,
  maxit = 1e+05,
  penalty.factor = rep(1, nvars),
  exclude = c(),
  lower.limits = -Inf,
  upper.limits = Inf,
  warm = NULL,
  from.glmnet.path = FALSE,
  save.fit = FALSE,
  trace.it = 0
)
}
\arguments{
\item{x}{Input matrix, of dimension \code{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 \code{xm} and \code{xs}, where \code{xm(j)} and
\code{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.}

\item{y}{Quantitative response variable.}

\item{weights}{Observation weights. \code{glmnet.fit} does NOT standardize
these weights.}

\item{lambda}{A single value for the \code{lambda} hyperparameter.}

\item{alpha}{The elasticnet mixing parameter, with \eqn{0 \le \alpha \le 1}.
The penalty is defined as \deqn{(1-\alpha)/2||\beta||_2^2+\alpha||\beta||_1.}
\code{alpha=1} is the lasso penalty, and \code{alpha=0} the ridge penalty.}

\item{offset}{A vector of length \code{nobs} that is included in the linear
predictor. Useful for the "poisson" family (e.g. log of exposure time), or
for refining a model by starting at a current fit. Default is NULL. If
supplied, then values must also be supplied to the \code{predict} function.}

\item{family}{A description of the error distribution and link function to be
used in the model. This is the result of a call to a family function. Default
is \code{gaussian()}. (See \code{\link[stats:family]{family}} for details on
family functions.)}

\item{intercept}{Should intercept be fitted (default=TRUE) or set to zero (FALSE)?}

\item{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 \code{1e-10}.}

\item{maxit}{Maximum number of passes over the data; default is \code{10^5}.
(If a warm start object is provided, the number of passes the warm start object
performed is included.)}

\item{penalty.factor}{Separate penalty factors can be applied to each
coefficient. This is a number that multiplies \code{lambda} to allow differential
shrinkage. Can be 0 for some variables, which implies no shrinkage, and that
variable is always included in the model. Default is 1 for all variables (and
implicitly infinity for variables listed in exclude). Note: the penalty
factors are internally rescaled to sum to \code{nvars}.}

\item{exclude}{Indices of variables to be excluded from the model. Default is
none. Equivalent to an infinite penalty factor.}

\item{lower.limits}{Vector of lower limits for each coefficient; default
\code{-Inf}. Each of these must be non-positive. Can be presented as a single
value (which will then be replicated), else a vector of length \code{nvars}.}

\item{upper.limits}{Vector of upper limits for each coefficient; default
\code{Inf}. See \code{lower.limits}.}

\item{warm}{Either a \code{glmnetfit} object or a list (with names \code{beta}
and \code{a0} containing coefficients and intercept respectively) which can
be used as a warm start. Default is \code{NULL}, indicating no warm start.
For internal use only.}

\item{from.glmnet.path}{Was \code{glmnet.fit()} called from \code{glmnet.path()}?
Default is FALSE.This has implications for computation of the penalty factors.}

\item{save.fit}{Return the warm start object? Default is FALSE.}

\item{trace.it}{Controls how much information is printed to screen. If
\code{trace.it=2}, some information about the fitting procedure is printed to
the console as the model is being fitted. Default is \code{trace.it=0}
(no information printed). (\code{trace.it=1} not used for compatibility with
\code{glmnet.path}.)}
}
\value{
An object with class "glmnetfit" and "glmnet". The list
returned contains more keys than that of a "glmnet" object.
\item{a0}{Intercept value.}
\item{beta}{A \code{nvars x 1} matrix of coefficients, stored in sparse matrix
format.}
\item{df}{The number of nonzero coefficients.}
\item{dim}{Dimension of coefficient matrix.}
\item{lambda}{Lambda value used.}
\item{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.}
\item{nulldev}{Null deviance (per observation). This is defined to be
2*(loglike_sat -loglike(Null)). The null model refers to the intercept model.}
\item{npasses}{Total passes over the data.}
\item{jerr}{Error flag, for warnings and errors (largely for internal
debugging).}
\item{offset}{A logical variable indicating whether an offset was included
in the model.}
\item{call}{The call that produced this object.}
\item{nobs}{Number of observations.}
\item{warm_fit}{If \code{save.fit=TRUE}, output of FORTRAN routine, used for
warm starts. For internal use only.}
\item{family}{Family used for the model.}
\item{converged}{A logical variable: was the algorithm judged to have
converged?}
\item{boundary}{A logical variable: is the fitted value on the boundary of
the attainable values?}
\item{obj_function}{Objective function value at the solution.}
}
\description{
Fit a generalized linear model via penalized maximum likelihood for a single
value of lambda. Can deal with any GLM family.
}
\details{
WARNING: Users should not call \code{glmnet.fit} directly. Higher-level functions
in this package call \code{glmnet.fit} as a subroutine. If a warm start object
is provided, some of the other arguments in the function may be overriden.

\code{glmnet.fit} solves the elastic net problem for a single, user-specified
value of lambda. \code{glmnet.fit} works for any GLM family. It solves the
problem using iteratively reweighted least squares (IRLS). For each IRLS
iteration, \code{glmnet.fit} makes a quadratic (Newton) approximation of the
log-likelihood, then calls \code{elnet.fit} to minimize the resulting
approximation.

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