glmnet.control: Internal glmnet algorithm parameters

Description

View and/or change the factory default parameters that control glmnet's numerical algorithms.

Usage

glmnet.control(
  fdev = 1e-05,
  devmax = 0.999,
  eps = 1e-06,
  big = 9.9e+35,
  mnlam = 5,
  pmin = 1e-09,
  exmx = 250,
  prec = 1e-10,
  mxit = 100,
  itrace = 0,
  epsnr = 1e-06,
  mxitnr = 25,
  thresh = 1e-07,
  maxit = 1e+05,
  dfmax = NULL,
  pmax = NULL,
  trace.it = 0,
  factory = FALSE
)

Value

A list with named elements as in the argument list.

Arguments

fdev: Path-termination parameter: minimum fractional change in deviance between consecutive lambdas for the path to continue. Scope: both paths. Factory default 1.0e-5.
devmax: Path-termination parameter: maximum fraction of null deviance the path is allowed to explain before stopping. Scope: both paths. Factory default 0.999.
eps: Path-termination parameter: floor on lambda.min.ratio (smallest allowed \(\lambda_{\min} / \lambda_{\max}\)). Scope: both paths. Factory default 1.0e-6.
big: Numerical guard: finite substitute for Inf in lower.limits / upper.limits. Scope: both paths. Factory default 9.9e35.
mnlam: Path-termination parameter: minimum number of lambda values to compute before early stopping is allowed. Scope: both paths. Factory default 5.
pmin: Numerical guard: floor on predicted probability in logistic-family kernels (prevents log(0)). Implies a max of 1 - pmin. Scope: engine only (logistic-family kernels). Factory default 1.0e-9.
exmx: Numerical guard: cap on exp() arguments in logistic-family kernels (prevents overflow). Scope: engine only (logistic-family kernels). Factory default 250.
prec: Bounds-subsolver convergence tolerance. Used by the engine's bnorm() subroutine when a coefficient has a finite lower or upper bound. Scope: engine only (bounds-constrained fits). Factory default 1.0e-10.
mxit: Bounds-subsolver iteration budget. Paired with prec. Scope: engine only (bounds-constrained fits). Factory default 100.
itrace: Progress-bar flag. 1 enables the progress bar in glmnet() and cv.glmnet(). Scope: both paths. Aliased with trace.it (setting one sets the other). Factory default 0.
epsnr: Newton-Raphson convergence tolerance for the R-level IRLS loop in glmnet.fit(). Scope: R-IRLS path only --- the core-engine kernels do not read this parameter. Factory default 1.0e-6.
mxitnr: Newton-Raphson iteration budget for the R-level IRLS loop in glmnet.fit(). Scope: R-IRLS path only. Factory default 25.
thresh: Inner coordinate-descent convergence threshold. Each inner CD loop continues until the maximum change in the objective after any coefficient update is less than thresh times the null deviance. Scope: both paths. Factory default 1e-7. Can also be set per-call via control = list(thresh = ...) in glmnet().
maxit: Inner coordinate-descent iteration budget: maximum total passes over the data across all lambda values. Scope: both paths. Factory default 100000. Can also be set per-call via control = list(maxit = ...).
dfmax: Coefficient-count cap: limit the maximum number of variables in the model at any lambda. Scope: both paths. Factory default NULL, which resolves at call time to nvars + 1 (i.e., unconstrained). Can also be set per-call via control = list(dfmax = ...).
pmax: Coefficient-count cap: limit the maximum number of variables ever to be nonzero anywhere on the path. Scope: both paths. Factory default NULL, which resolves at call time to min(dfmax * 2 + 20, nvars). Can also be set per-call via control = list(pmax = ...).
trace.it: Progress-bar flag (alias of itrace). Scope: both paths. Factory default 0.
factory: If TRUE, reset all parameters to their factory defaults. Default is FALSE.

Parameter taxonomy

glmnet has two execution paths, and not every control parameter is consumed by both:

Core-engine path --- family passed as a character string ("gaussian", "binomial", "poisson", "multinomial", "mgaussian", "cox") routes to purpose-built C++ glmnetpp kernels.
GLM-family (R-IRLS) path --- family passed as a family() object (or glmnet.path() / glmnet.fit() called directly) runs an IRLS loop implemented in R that uses the C++ wls kernel as its inner solver.

The table below shows the role and the scope of each parameter. "Scope: engine" means the parameter is only meaningful on the core-engine path; "Scope: R-IRLS" means only on the GLM-family path; "Scope: both" means consulted by both.

Parameter	Role	Scope	Notes
`fdev`	path termination	both	C++ name `sml`; min fractional deviance change
`devmax`	path termination	both	C++ name `rsqmax`; max explained-deviance ratio
`mnlam`	path termination	both	min lambda count before early stop
`eps`	path termination	both	lambda.min.ratio floor
`thresh`	CD tolerance	both	inner coordinate-descent convergence
`maxit`	CD budget	both	max CD passes across all lambdas
`dfmax`	coefficient-count cap	both	default resolves to `nvars + 1` at call time
`pmax`	coefficient-count cap	both	default resolves to `min(dfmax*2+20, nvars)` at call time
`big`	numerical guard	both	`Inf` substitute for bounds limits
`itrace`	progress	both	aliased with `trace.it`
`trace.it`	progress	both	aliased with `itrace`
`pmin`	probability floor	engine	logistic-family kernels only (`lognet`, `multnet`)
`exmx`	exp() cap	engine	logistic-family kernels only
`prec`	bounds-subsolver tolerance	engine	active when a coefficient has finite `lower` / `upper`
`mxit`	bounds-subsolver budget	engine	paired with `prec` via C++ `chg_bnorm()`
`epsnr`	Newton-Raphson tolerance	R-IRLS	inert on the core-engine path; only `glmnet.fit()` reads it
`mxitnr`	Newton-Raphson budget	R-IRLS	inert on the core-engine path; only `glmnet.fit()` reads it

The naming zoo (three tolerances, three iteration budgets) reflects the fact that glmnet contains three nested loops:

Outer path: iterate over lambda values. Early termination governed by fdev, devmax, mnlam, eps.
Middle Newton/IRLS loop (only on the R-IRLS path): convergence by epsnr, budget by mxitnr.
Inner coordinate descent: convergence by thresh, budget by maxit.
Bounds subsolver (only for coefficients with finite lower/upper): convergence by prec, budget by mxit.

Author

Jerome Friedman, Kenneth Tay, Trevor Hastie
Maintainer: Trevor Hastie hastie@stanford.edu

Details

If called with no arguments, glmnet.control() returns a list with the current settings of these parameters. Any arguments included in the call set those parameters to the new values, and then silently return the updated settings. Values set via glmnet.control() persist for the duration of the R session. All parameters listed here can also be supplied per-call via the control = list(...) argument of glmnet(), which does not mutate the session state; see that function's documentation for the precedence rules.

Examples

Run this code


glmnet.control(fdev = 0)  # continue along path even though not much changes
glmnet.control(thresh = 1e-8)  # tighten CD convergence for session
glmnet.control()  # view current settings
glmnet.control(factory = TRUE)  # reset all the parameters to their default

Run the code above in your browser using DataLab