9.2
4 API reference
The reference documents every public procedure. It grows as each model lands.
4.1 Fitting Gaussian models
The four core models are one routine, elnet-fit, called with different #:alpha and #:lambda; convenience wrappers name the common cases.
struct
(struct elnet-result ( intercept coefficients r-squared lambda num-passes) #:transparent) intercept : real? coefficients : (vectorof real?) r-squared : real? lambda : real? num-passes : exact-nonnegative-integer?
A fitted model. coefficients is a dense vector on the original
predictor scale (one entry per column of X); lambda is the
penalty actually used; r-squared is the fraction of null deviance
explained; num-passes is glmnet’s coordinate-descent pass count.
procedure
(elnet-fit X y #:lambda lambda [ #:alpha alpha #:standardize? standardize? #:intercept? intercept? #:thresh thresh #:max-iters max-iters]) → elnet-result? X : (and/c (listof (listof real?)) pair?) y : (and/c (listof real?) pair?) lambda : (>=/c 0) alpha : (real-in 0 1) = 1.0 standardize? : boolean? = #t intercept? : boolean? = #t thresh : (>/c 0) = 1e-7 max-iters : exact-positive-integer? = 100000
Fits a single dense Gaussian elastic-net model. X is a non-empty list
of equal-length rows; y is the matching response. alpha is
the mixing parameter (0 ridge, 1 lasso, in between elastic
net) and lambda is the penalty strength. With standardize?
the predictors are scaled to unit variance before fitting (coefficients are
reported on the original scale). Raises an error if glmnet reports a fatal
condition (e.g. zero-variance predictors).
procedure
(ols X y [ #:standardize? standardize? #:intercept? intercept? #:thresh thresh #:max-iters max-iters]) → elnet-result? X : (and/c (listof (listof real?)) pair?) y : (and/c (listof real?) pair?) standardize? : boolean? = #t intercept? : boolean? = #t thresh : (>/c 0) = 1e-10 max-iters : exact-positive-integer? = 100000
Ordinary least squares: elnet-fit with #:lambda 0.0 (the
mixing parameter is then irrelevant). Uses a tighter default thresh
than the penalized fits, since coordinate descent approaches the unpenalized
solution as the threshold tightens. See Ordinary least squares (λ = 0).
procedure
(ridge X y #:lambda lambda [ #:standardize? standardize? #:intercept? intercept? #:thresh thresh #:max-iters max-iters]) → elnet-result? X : (and/c (listof (listof real?)) pair?) y : (and/c (listof real?) pair?) lambda : (>=/c 0) standardize? : boolean? = #t intercept? : boolean? = #t thresh : (>/c 0) = 1e-7 max-iters : exact-positive-integer? = 100000
Ridge regression: elnet-fit with #:alpha 0.0 (pure L2
penalty). Shrinks every coefficient smoothly toward zero as lambda
grows but never sets one exactly to zero. See Ridge regression (L2, α = 0).
procedure
(lasso X y #:lambda lambda [ #:standardize? standardize? #:intercept? intercept? #:thresh thresh #:max-iters max-iters]) → elnet-result? X : (and/c (listof (listof real?)) pair?) y : (and/c (listof real?) pair?) lambda : (>=/c 0) standardize? : boolean? = #t intercept? : boolean? = #t thresh : (>/c 0) = 1e-7 max-iters : exact-positive-integer? = 100000
Lasso: elnet-fit with #:alpha 1.0 (pure L1 penalty). Performs
variable selection —
procedure
(elastic-net X y #:alpha alpha #:lambda lambda [ #:standardize? standardize? #:intercept? intercept? #:thresh thresh #:max-iters max-iters]) → elnet-result? X : (and/c (listof (listof real?)) pair?) y : (and/c (listof real?) pair?) alpha : (real-in 0 1) lambda : (>=/c 0) standardize? : boolean? = #t intercept? : boolean? = #t thresh : (>/c 0) = 1e-7 max-iters : exact-positive-integer? = 100000
Elastic net at an explicit alpha in (real-in 0 1): blends the
lasso’s selection with the ridge’s shrinkage. #:alpha 0.0 reduces to
ridge and #:alpha 1.0 to lasso. See
Elastic net (0 < α < 1).
4.2 Fitting binomial (logistic) models
The binomial family fits a two-class logistic model: the response is a 0/1 class label and the fit models the log-odds of class 1. logistic-fit mirrors elnet-fit’s keywords, and prediction helpers turn a fit into class-1 probabilities or hard labels.
struct
(struct logistic-result ( intercept coefficients dev-ratio lambda num-passes) #:transparent) intercept : real? coefficients : (vectorof real?) dev-ratio : real? lambda : real? num-passes : exact-nonnegative-integer?
A fitted two-class logistic model. intercept and the dense
coefficients (on the original predictor scale) are on the log-odds
scale for class 1; lambda is the penalty actually used;
dev-ratio is the fraction of null deviance explained (the logistic
analogue of elnet-result’s r-squared); num-passes is
glmnet’s coordinate-descent pass count.
procedure
(logistic-fit X y #:lambda lambda [ #:alpha alpha #:standardize? standardize? #:intercept? intercept? #:thresh thresh #:max-iters max-iters]) → logistic-result? X : (and/c (listof (listof real?)) pair?) y : (and/c (listof (or/c 0 1)) pair?) lambda : (>=/c 0) alpha : (real-in 0 1) = 1.0 standardize? : boolean? = #t intercept? : boolean? = #t thresh : (>/c 0) = 1e-7 max-iters : exact-positive-integer? = 100000
Fits a single dense two-class logistic elastic-net model. X is a
non-empty list of equal-length rows and y a matching list of 0/1 class
labels. alpha mixes the penalty (0.0 ridge logistic,
1.0 lasso logistic, in between elastic net) and lambda sets
its strength. Raises an error if glmnet reports a fatal condition —
procedure
(logistic-predict-proba fit X) → (listof (real-in 0 1))
fit : logistic-result? X : (and/c (listof (listof real?)) pair?)
The class-1 probability 1 / (1 + e^(-(β₀ + xβ))) for each row of
X. Each row must have as many features as fit has
coefficients.
procedure
(logistic-predict fit X [ #:threshold threshold]) → (listof (or/c 0 1)) fit : logistic-result? X : (and/c (listof (listof real?)) pair?) threshold : (real-in 0 1) = 0.5
4.3 Fitting multinomial (multiclass) models
The multinomial family fits a K-class classifier: the response is a list of integer class labels 0..K-1 and the fit returns K intercepts and K coefficient vectors.
struct
(struct multinomial-result ( intercepts coefficients dev-ratio lambda num-passes) #:transparent) intercepts : (vectorof real?) coefficients : (vectorof (vectorof real?)) dev-ratio : real? lambda : real? num-passes : exact-nonnegative-integer?
A fitted K-class model. intercepts is a vector of K reals;
coefficients is a vector of K coefficient vectors (each of length
ni), one per class, on the original predictor scale.
dev-ratio is the fraction of null deviance explained (the multiclass
analogue of elnet-result’s r-squared); lambda is the
penalty used; num-passes is glmnet’s pass count.
procedure
(multinomial-fit X y #:lambda lambda [ #:alpha alpha #:standardize? standardize? #:intercept? intercept? #:thresh thresh #:max-iters max-iters]) → multinomial-result? X : (and/c (listof (listof real?)) pair?) y : (and/c (listof exact-nonnegative-integer?) pair?) lambda : (>=/c 0) alpha : (real-in 0 1) = 1.0 standardize? : boolean? = #t intercept? : boolean? = #t thresh : (>/c 0) = 1e-7 max-iters : exact-positive-integer? = 100000
Fits a single dense K-class multinomial elastic-net model. y is a list
of integer class labels that must cover 0..(sub1 K)
contiguously (every class present). alpha mixes the penalty
(0.0 ridge, 1.0 lasso) and lambda sets its strength.
Raises an error on a fatal glmnet condition (e.g. a class probability
collapsing under perfect separation —
procedure
(multinomial-predict-proba fit X)
→ (listof (listof (real-in 0 1))) fit : multinomial-result? X : (and/c (listof (listof real?)) pair?)
The per-class softmax probabilities for each row of X; each inner list
has K entries summing to 1. Each row must have as many features as fit
has coefficients.
procedure
(multinomial-predict fit X)
→ (listof exact-nonnegative-integer?) fit : multinomial-result? X : (and/c (listof (listof real?)) pair?)
4.4 Fitting Cox proportional-hazards models
The Cox family fits a survival model from a follow-up time and a 0/1 event
indicator. There is no intercept —
struct
(struct cox-result (coefficients dev-ratio lambda num-passes) #:transparent) coefficients : (vectorof real?) dev-ratio : real? lambda : real? num-passes : exact-nonnegative-integer?
A fitted Cox model. coefficients is a dense vector of length
ni on the log relative-hazard scale (no intercept); dev-ratio
is the fraction of null partial-likelihood deviance explained; lambda
is the penalty used; num-passes is glmnet’s pass count.
procedure
(cox-fit X times statuses #:lambda lambda [ #:alpha alpha #:standardize? standardize? #:thresh thresh #:max-iters max-iters]) → cox-result? X : (and/c (listof (listof real?)) pair?) times : (and/c (listof (>/c 0)) pair?) statuses : (and/c (listof (or/c 0 1)) pair?) lambda : (>=/c 0) alpha : (real-in 0 1) = 1.0 standardize? : boolean? = #t thresh : (>/c 0) = 1e-7 max-iters : exact-positive-integer? = 100000
Fits a single dense Cox proportional-hazards elastic-net model. times
are positive follow-up times and statuses the matching 0/1 event
indicators (1 = event, 0 = right-censored); at least one must
be an event. alpha mixes the penalty (0.0 ridge, 1.0
lasso) and lambda sets its strength. There is no #:intercept?
keyword —
procedure
(cox-linear-predictor fit X) → (listof real?)
fit : cox-result? X : (and/c (listof (listof real?)) pair?)
The log relative hazard x·β for each row of X (no intercept).
Each row must have as many features as fit has coefficients.
procedure
(cox-relative-risk fit X) → (listof (>/c 0))
fit : cox-result? X : (and/c (listof (listof real?)) pair?)
The relative risk exp(x·β) for each row of X —
4.5 Fitting Poisson (count) models
The Poisson family fits a non-negative count response with a log link.
struct
(struct poisson-result ( intercept coefficients dev-ratio lambda num-passes) #:transparent) intercept : real? coefficients : (vectorof real?) dev-ratio : real? lambda : real? num-passes : exact-nonnegative-integer?
A fitted Poisson model. intercept and the dense coefficients
(length ni, on the original predictor scale) are on the log-mean
scale. dev-ratio is the fraction of null deviance explained;
lambda is the penalty used; num-passes is glmnet’s pass count.
procedure
(poisson-fit X y #:lambda lambda [ #:alpha alpha #:standardize? standardize? #:intercept? intercept? #:thresh thresh #:max-iters max-iters]) → poisson-result? X : (and/c (listof (listof real?)) pair?) y : (and/c (listof (>=/c 0)) pair?) lambda : (>=/c 0) alpha : (real-in 0 1) = 1.0 standardize? : boolean? = #t intercept? : boolean? = #t thresh : (>/c 0) = 1e-7 max-iters : exact-positive-integer? = 100000
Fits a single dense Poisson elastic-net model. y is a list of
non-negative counts. alpha mixes the penalty (0.0 ridge,
1.0 lasso) and lambda sets its strength. See
Poisson regression (counts).
procedure
(poisson-predict-mean fit X) → (listof (>/c 0))
fit : poisson-result? X : (and/c (listof (listof real?)) pair?)
The fitted Poisson mean exp(β₀ + x·β) for each row of X. Each
row must have as many features as fit has coefficients.
4.6 Fitting multi-response Gaussian models
The multi-response Gaussian family fits several numeric responses jointly with a grouped lasso across responses.
struct
(struct mgaussian-result ( intercepts coefficients r-squared lambda num-passes) #:transparent) intercepts : (vectorof real?) coefficients : (vectorof (vectorof real?)) r-squared : real? lambda : real? num-passes : exact-nonnegative-integer?
A fitted multi-response model. intercepts is a vector of nr reals;
coefficients is a vector of nr coefficient vectors (each of length
ni), one per response, on the original predictor scale.
r-squared is the fraction of (multi-response) variance explained;
lambda is the penalty used; num-passes is glmnet’s pass count.
procedure
(mgaussian-fit X Y #:lambda lambda [ #:alpha alpha #:standardize? standardize? #:intercept? intercept? #:thresh thresh #:max-iters max-iters]) → mgaussian-result? X : (and/c (listof (listof real?)) pair?) Y : (and/c (listof (listof real?)) pair?) lambda : (>=/c 0) alpha : (real-in 0 1) = 1.0 standardize? : boolean? = #t intercept? : boolean? = #t thresh : (>/c 0) = 1e-7 max-iters : exact-positive-integer? = 100000
Fits a single dense multi-response Gaussian elastic-net model. Y is a
response matrix (a non-empty list of equal-length rows, one column per response)
with one row per observation. The grouped lasso (alpha toward
1.0) selects predictors for all responses jointly; #:alpha 0.0
is the ridge. See Multi-response Gaussian (grouped).
procedure
(mgaussian-predict fit X) → (listof (listof real?))
fit : mgaussian-result? X : (and/c (listof (listof real?)) pair?)
The per-response predictions a0r + x·βr for each row of X —
4.7 Connectivity and self-checks
These entry points call directly into the C-ABI shim, for confirming the native library loaded and was built correctly.
procedure
The byte width of the Fortran default real in the loaded native library.
This is 8 when the library was compiled with -fdefault-real-8,
which the numeric API requires. The package raises an error at load time if it
is not 8.
procedure
The ABI version of the C-ABI shim. Bumped on any breaking change to a C entry
point.