| Title: | Contribution-Capped Elastic Net Regularization |
|---|---|
| Description: | Implements contribution-capped regularization to directly bound per-feature contributions in predictive models. Includes quasi-Newton optimization for unbounded fits and projected proximal gradient for finite coefficient bounds, as well as cross-validation, walk-forward fitting and prediction, and plotting utilities. References: Andrew and Gao (2007) <doi:10.1145/1273496.1273501>; Friedman et al. (2010) <doi:10.18637/jss.v033.i01>; James et al. (2020) <doi:10.1080/01621459.2019.1609970>; Nocedal (1980) <doi:10.1090/S0025-5718-1980-0572855-7>. |
| Authors: | Harry He [aut, cre, cph] |
| Maintainer: | Harry He <[email protected]> |
| License: | GPL (>= 2) |
| Version: | 0.4.1 |
| Built: | 2026-11-19 03:51:42 UTC |
| Source: | https://github.com/cran/capnet |
Fits a penalized linear model by maximum likelihood with an elastic net penalty and an additional penalty that caps per-feature contributions. Unbounded fits use L-BFGS when the L1 penalty is inactive and Orthant-Wise Limited-Memory Quasi-Newton (OWL-QN) when it is active. Fits with finite coefficient bounds use projected proximal gradient, with soft-thresholding for L1 regularization.
capnet( X, y, L, family = "gaussian", intercept = TRUE, standardize = TRUE, z = NULL, multiplier = 1, lambda = 0, alpha = 0, gamma = 0, lower.limits = NULL, upper.limits = NULL, tol = 1e-08, maxit = 10000L, par = NULL, ... )capnet( X, y, L, family = "gaussian", intercept = TRUE, standardize = TRUE, z = NULL, multiplier = 1, lambda = 0, alpha = 0, gamma = 0, lower.limits = NULL, upper.limits = NULL, tol = 1e-08, maxit = 10000L, par = NULL, ... )
X |
Numeric predictor matrix of shape |
y |
Numeric response vector of length |
L |
Nonnegative numeric scalar or length- |
family |
Optional character scalar (e.g. |
intercept |
Logical; should an intercept be fitted? Default |
standardize |
Logical; if |
z |
Optional numeric matrix with |
multiplier |
Optional numeric scalar or length- |
lambda |
Nonnegative numeric scalar; overall strength of the elastic-net
penalty. When |
alpha |
Numeric scalar in |
gamma |
Nonnegative numeric scalar; strength of the contribution-cap
penalty. When |
lower.limits |
Optional numeric scalar or length- |
upper.limits |
Optional numeric scalar or length- |
tol |
Nonnegative numeric convergence tolerance for fits with finite
coefficient bounds. It is the relative step-size threshold for the
projected proximal-gradient solver and has no effect on unbounded fits.
Default |
maxit |
Integer; maximum number of optimizer iterations. Default
|
par |
Optional numeric vector of length |
... |
Additional arguments used in fitting. Currently unused. |
Fits without finite coefficient bounds use OWL-QN to handle the L1
component when alpha > 0 and lambda > 0, and L-BFGS otherwise.
If any coefficient bound is finite, a projected proximal-gradient solver is
used instead. Its proximal step applies soft-thresholding for the L1 term
and then projects coefficients onto their allowed intervals. This permits
coefficients to reach zero and change sign when the bounds allow it.
tol controls the relative step-size convergence criterion for this
bounded solver. If standardize = TRUE, the model is fit on
standardized X and coefficients are mapped back to the original
scale on return; the cap penalty is always computed on the original scale.
Soft constraints: the contribution cap is a penalty, not a
hard constraint. The returned feature_contributions may still exceed
L when gamma is small or the optimizer does not fully converge.
Use capnet_violations() to check how much each cap is exceeded.
Standardization with multiplier: standardization is not recommended
when a non-unit multiplier is supplied, as the scaling step may
distort the intended contribution budget.
An object of class "capnet" with components:
a0 |
Best intercept (numeric scalar). |
beta |
Numeric vector (length |
value |
Numeric; minimized objective value. |
feature_contributions |
Numeric matrix of shape
|
z |
The evaluation matrix used for cap enforcement. |
convergence |
Integer convergence code from the optimizer:
|
message |
Character string from the optimizer (may be
|
alpha |
alpha value passed in input. |
lambda |
lambda value passed in input. |
gamma |
gamma value passed in input. |
L |
L value passed in input. |
multiplier |
multiplier value passed in input. |
family |
model family passed in input. |
call |
The matched call. |
cv_capnet(), walk_capnet(), predict.capnet(),
coef.capnet(), capnet_violations()
set.seed(1) n <- 40 p <- 8 X <- matrix(rnorm(n * p), n, p) beta <- c(2, 1.5, rep(0, p - 2)) y <- as.numeric(X %*% beta + rnorm(n)) L <- rep(1.5, p) # Standard elastic net (gamma = 0, no cap) fit0 <- capnet(X, y, lambda = 0.1, alpha = 0.5, gamma = 0, L = L) # With contribution cap penalty fit1 <- capnet(X, y, lambda = 0.1, alpha = 0.5, gamma = 1, L = L) fit1$convergence # check optimizer status; 0 = success # Enforce caps on a held-out evaluation set, not training rows X_new <- matrix(rnorm(10 * p), 10, p) fit2 <- capnet(X, y, lambda = 0.1, alpha = 0.5, gamma = 1, L = L, z = X_new) # Box constraints (non-negative coefficients) fit3 <- capnet(X, y, lambda = 0.1, alpha = 0.5, gamma = 1, L = L, lower.limits = 0 )set.seed(1) n <- 40 p <- 8 X <- matrix(rnorm(n * p), n, p) beta <- c(2, 1.5, rep(0, p - 2)) y <- as.numeric(X %*% beta + rnorm(n)) L <- rep(1.5, p) # Standard elastic net (gamma = 0, no cap) fit0 <- capnet(X, y, lambda = 0.1, alpha = 0.5, gamma = 0, L = L) # With contribution cap penalty fit1 <- capnet(X, y, lambda = 0.1, alpha = 0.5, gamma = 1, L = L) fit1$convergence # check optimizer status; 0 = success # Enforce caps on a held-out evaluation set, not training rows X_new <- matrix(rnorm(10 * p), 10, p) fit2 <- capnet(X, y, lambda = 0.1, alpha = 0.5, gamma = 1, L = L, z = X_new) # Box constraints (non-negative coefficients) fit3 <- capnet(X, y, lambda = 0.1, alpha = 0.5, gamma = 1, L = L, lower.limits = 0 )
capnet modelIdentifies where feature contributions exceed the specified contribution cap. Returns the indices of offending rows and columns along with the excess contribution matrix.
capnet_violations(object, z = NULL, multiplier = NULL)capnet_violations(object, z = NULL, multiplier = NULL)
object |
A fitted |
z |
Optional numeric matrix of new data on which to evaluate
contribution caps. If |
multiplier |
Optional numeric scalar or length- |
Contributions are computed as
,
compared against the cap stored in the fitted object. The returned
excess matrix gives
.
A list with the following components:
columns |
Integer vector of column indices (features) with any violations of the contribution cap. |
rows |
Integer vector of row indices (observations) where at least one feature exceeded its cap. |
excess |
Numeric matrix of the same dimension as |
If no violations are detected (the sum of excess is zero), the
function
prints a message and returns NULL invisibly.
set.seed(1) n <- 40 p <- 8 X <- matrix(rnorm(n * p), n, p) beta <- c(2, 1.5, rep(0, p - 2)) y <- X %*% beta + rnorm(n) fit <- capnet(X, y, lambda = 0.1, alpha = 0.5, gamma = 1, L = 1) capnet_violations(fit)set.seed(1) n <- 40 p <- 8 X <- matrix(rnorm(n * p), n, p) beta <- c(2, 1.5, rep(0, p - 2)) y <- X %*% beta + rnorm(n) fit <- capnet(X, y, lambda = 0.1, alpha = 0.5, gamma = 1, L = 1) capnet_violations(fit)
Computes fitted coefficients from capnet() along a path of
lambda values (with alpha held fixed). This is useful for
inspecting coefficient shrinkage and entry/exit as regularization increases.
coef_path( X, y, L, lambda = exp(seq(1, -5, length.out = 50)), alpha = 0.5, gamma = 1, standardize = FALSE, ... )coef_path( X, y, L, lambda = exp(seq(1, -5, length.out = 50)), alpha = 0.5, gamma = 1, standardize = FALSE, ... )
X |
Numeric predictor matrix of shape |
y |
Numeric response vector of length |
L |
Nonnegative numeric scalar or length- |
lambda |
Numeric vector (default |
alpha |
Numeric scalar in |
gamma |
Nonnegative numeric scalar; strength of the contribution-cap
penalty (default |
standardize |
Logical; if |
... |
Additional arguments forwarded to |
For each point on the path, capnet() is fit with the remaining two
hyperparameters held fixed, and the resulting coefficients are collected.
Lambda and gamma paths use log() of the parameter value as the first
column (suitable for log-scale x-axis); the alpha path uses the raw value.
Pass the result to plot() to visualize the coefficient paths.
A data.frame of class c("capnet_path", "data.frame")
with one row per point on the path. The first column is the path parameter
("lambda (log)", "gamma (log)", or "alpha"); the
remaining columns are fitted coefficients, named from
colnames(X) when available. Exactly one of lambda,
gamma, alpha may be a vector; the other two must be scalars.
set.seed(1) n <- 50 p <- 8 X <- matrix(rnorm(n * p), n, p) colnames(X) <- paste0("x", seq_len(p)) beta <- c(1.5, 0.8, 0.2, rep(0, p - 3)) y <- as.numeric(X %*% beta + rnorm(n)) path <- coef_path(X, y, L = 0.5, alpha = 0.5, lambda = exp(seq(1, -5, length.out = 50)), gamma = 1 ) plot(path)set.seed(1) n <- 50 p <- 8 X <- matrix(rnorm(n * p), n, p) colnames(X) <- paste0("x", seq_len(p)) beta <- c(1.5, 0.8, 0.2, rep(0, p - 3)) y <- as.numeric(X %*% beta + rnorm(n)) path <- coef_path(X, y, L = 0.5, alpha = 0.5, lambda = exp(seq(1, -5, length.out = 50)), gamma = 1 ) plot(path)
capnet modelReturns the estimated intercept and coefficients from a fitted
capnet model object.
## S3 method for class 'capnet' coef(object, ...)## S3 method for class 'capnet' coef(object, ...)
object |
A fitted object of class |
... |
Further arguments passed to or from other methods. |
A numeric matrix. The first row is the
intercept (named "(Intercept)"); the remaining rows are
the fitted slopes, named from colnames(X) when available.
set.seed(1) n <- 40 p <- 5 X <- matrix(rnorm(n * p), n, p) y <- as.numeric(X %*% c(1, -1, 0.5, 0, 0) + rnorm(n)) fit <- capnet(X, y, lambda = 0.1, alpha = 0.5, gamma = 1, L = 1) coef(fit) # (1 + p) x 1 matrix coef(fit)[-1, ] # slopes onlyset.seed(1) n <- 40 p <- 5 X <- matrix(rnorm(n * p), n, p) y <- as.numeric(X %*% c(1, -1, 0.5, 0, 0) + rnorm(n)) fit <- capnet(X, y, lambda = 0.1, alpha = 0.5, gamma = 1, L = 1) coef(fit) # (1 + p) x 1 matrix coef(fit)[-1, ] # slopes only
capnet fitExtract coefficient paths from a walk-forward capnet fit
## S3 method for class 'walk_capnet' coef(object, index = NULL, ...)## S3 method for class 'walk_capnet' coef(object, index = NULL, ...)
object |
A fitted object of class |
index |
Optional integer vector of step indices (1 to |
... |
Further arguments passed to or from other methods. |
A matrix (or xts if the
input z was xts). The first column is the intercept path
(named "intercept"); the remaining columns are coefficient
paths named from colnames(X). Rows within the same walk step share
identical values. NA rows indicate steps that failed to converge.
If index is supplied, only those rows are returned.
walk_capnet(), predict.walk_capnet()
set.seed(1) n <- 50 p <- 5 n_new <- 8 X <- matrix(rnorm(n * p), n, p) z <- matrix(rnorm(n_new * p), n_new, p) y <- as.numeric(X %*% c(1, -1, 0.5, 0, 0) + rnorm(n)) fit <- walk_capnet(X, y, L = 1, z = z, lambda = 0.1, alpha = 0.5, gamma = 1) coef(fit) # nrow(z) x (1 + p) path coef(fit, index = 1:3) # first three steps onlyset.seed(1) n <- 50 p <- 5 n_new <- 8 X <- matrix(rnorm(n * p), n, p) z <- matrix(rnorm(n_new * p), n_new, p) y <- as.numeric(X %*% c(1, -1, 0.5, 0, 0) + rnorm(n)) fit <- walk_capnet(X, y, L = 1, z = z, lambda = 0.1, alpha = 0.5, gamma = 1) coef(fit) # nrow(z) x (1 + p) path coef(fit, index = 1:3) # first three steps only
capnet
Runs a grid search over alpha and lambda with K-fold
cross-validation for the capnet() model. Returns the searched grid,
fold-wise errors, mean errors, and the best hyperparameters.
cv_capnet( X, y, gamma, L, family = "gaussian", lambda = exp(seq(1, -5, length.out = 50)), alpha = seq(0, 1, length.out = 5), z = NULL, multiplier = 1, intercept = TRUE, standardize = TRUE, splits = NULL, K = 5, metric = c("mse", "rsq", "logloss", "brier", "deviance"), verbose = 0, parallel = FALSE, workers = NULL, ... )cv_capnet( X, y, gamma, L, family = "gaussian", lambda = exp(seq(1, -5, length.out = 50)), alpha = seq(0, 1, length.out = 5), z = NULL, multiplier = 1, intercept = TRUE, standardize = TRUE, splits = NULL, K = 5, metric = c("mse", "rsq", "logloss", "brier", "deviance"), verbose = 0, parallel = FALSE, workers = NULL, ... )
X |
Numeric predictor matrix of shape |
y |
Numeric response vector of length |
gamma |
Nonnegative numeric scalar; strength of the contribution-cap
penalty. Unlike |
L |
Nonnegative numeric scalar or length- |
family |
Optional character scalar (e.g. "binomial"), function (e.g.
|
lambda |
Numeric vector (default |
alpha |
Numeric vector (default |
z |
Optional numeric matrix with |
multiplier |
Optional numeric scalar or length- |
intercept |
Logical; should an intercept be fitted? Default |
standardize |
Logical; if |
splits |
Optional integer vector of length |
K |
Integer |
metric |
Character string; CV scoring metric. When omitted, the default
is chosen by family: |
verbose |
Integer; |
parallel |
Logical; if |
workers |
Optional integer; number of parallel workers to use when
|
... |
Additional arguments forwarded to |
If splits is NULL, folds are generated as
sample(rep(1:K, length.out = n)). Set a seed beforehand to reproduce
the random fold allocation. If splits is supplied as an integer vector
of fold IDs, K is inferred as length(unique(splits)).
For each (alpha, lambda) pair, capnet() is fit on the
training portion of each fold and evaluated on the held-out rows using
metric.
Time-series data: the default random fold creation assumes i.i.d.
rows. For time-ordered data supply splits explicitly so that each
test fold lies strictly after its training fold:
# Walk-forward folds: fold k tests the k-th block of rows splits <- rep(seq_len(K), each = ceiling(n / K))[seq_len(n)]
An object of class "cv_capnet" with components:
alpha |
Numeric vector of alpha values searched. |
lambda |
Numeric vector of lambda values searched. |
gamma |
gamma value passed in input. |
L |
L value passed in input. |
metric |
Metric used to evaluate performance. |
splits |
Cross-validation splits. |
cv_errors |
Numeric array of shape |
mean_errors |
Numeric matrix of shape |
best_alpha |
Numeric; the selected alpha. |
best_lambda |
Numeric; the selected lambda. |
best_error |
Numeric; mean CV score at |
capnet(), walk_capnet(), plot.cv_capnet()
set.seed(1) n <- 80 p <- 10 X <- matrix(rnorm(n * p), n, p) beta <- c(1.2, 0.7, 0.5, rep(0, p - 3)) y <- as.numeric(X %*% beta + rnorm(n)) # Basic cross-validation cv <- cv_capnet(X, y, gamma = 1, L = 1.5) cv$best_alpha cv$best_lambda cv$best_error # Visualize the CV error surface plot(cv) plot(cv, alpha = cv$best_alpha) # Time-ordered data: use sequential folds to avoid leakage K <- 5 splits <- rep(seq_len(K), each = ceiling(n / K))[seq_len(n)] cv_ts <- cv_capnet(X, y, gamma = 1, L = 1.5, splits = splits)set.seed(1) n <- 80 p <- 10 X <- matrix(rnorm(n * p), n, p) beta <- c(1.2, 0.7, 0.5, rep(0, p - 3)) y <- as.numeric(X %*% beta + rnorm(n)) # Basic cross-validation cv <- cv_capnet(X, y, gamma = 1, L = 1.5) cv$best_alpha cv$best_lambda cv$best_error # Visualize the CV error surface plot(cv) plot(cv, alpha = cv$best_alpha) # Time-ordered data: use sequential folds to avoid leakage K <- 5 splits <- rep(seq_len(K), each = ceiling(n / K))[seq_len(n)] cv_ts <- cv_capnet(X, y, gamma = 1, L = 1.5, splits = splits)
Normalize user input into a stats family object
normalize_family(family = NULL)normalize_family(family = NULL)
family |
optional character scalar (e.g. "binomial"),
a function (e.g. |
A stats family object
Compares regression coefficients and per-feature contributions between an
uncapped and a capped capnet fit. Produces either side-by-side
("raw") bar charts of levels or ("delta") bar charts of changes.
plot_redistribution( uncapped, capped, X = NULL, multiplier = NULL, top_n = Inf, plot = c("raw", "delta") )plot_redistribution( uncapped, capped, X = NULL, multiplier = NULL, top_n = Inf, plot = c("raw", "delta") )
uncapped |
A |
capped |
A |
X |
Optional numeric matrix of features used to compute contributions.
If |
multiplier |
Optional numeric scalar or length- |
top_n |
Integer ( |
plot |
Character string, one of |
For each model, per-row contributions are computed as
; the displayed
contribution for feature is the mean over rows:
.
The multiplier from the capped model is used; if the two models
were fit with different multipliers the comparison may be misleading.
A list of two ggplot objects, which are also printed::
p1If plot = "raw": side-by-side bar chart of
coefficients for uncapped vs capped models. If plot = "delta":
bar chart of changes in coefficients (capped - uncapped).
p2If plot = "raw": side-by-side bar chart of
contributions for uncapped vs capped models. If plot = "delta":
bar chart of changes in contributions (capped - uncapped).
The function prints both plots and invisibly returns the list
list("beta" = p1, "contribution" = p2)
set.seed(1) n <- 40 p <- 6 X <- matrix(rnorm(n * p), n, p) beta <- c(1.5, 0.8, 0.2, rep(0, p - 3)) y <- as.numeric(X %*% beta + rnorm(n)) fit_uncap <- capnet(X, y, lambda = 0.05, alpha = 0.5, gamma = 0, L = 1) fit_cap <- capnet(X, y, lambda = 0.05, alpha = 0.5, gamma = 1, L = 1) plot_redistribution(fit_uncap, fit_cap, plot = "delta")set.seed(1) n <- 40 p <- 6 X <- matrix(rnorm(n * p), n, p) beta <- c(1.5, 0.8, 0.2, rep(0, p - 3)) y <- as.numeric(X %*% beta + rnorm(n)) fit_uncap <- capnet(X, y, lambda = 0.05, alpha = 0.5, gamma = 0, L = 1) fit_cap <- capnet(X, y, lambda = 0.05, alpha = 0.5, gamma = 1, L = 1) plot_redistribution(fit_uncap, fit_cap, plot = "delta")
Plot coefficient paths along a single hyperparameter
## S3 method for class 'capnet_path' plot(x, ...)## S3 method for class 'capnet_path' plot(x, ...)
x |
An object of class |
... |
Further arguments passed to or from other methods. |
Produces a line plot with the path parameter on the x-axis (log scale for
lambda and gamma paths, linear for alpha) and
coefficient values on the y-axis. Each feature is drawn as a separate
colored line, making it easy to see which coefficients enter, shrink, or
change sign along the path.
The ggplot object, returned invisibly. As a side effect the
plot is printed to the current graphics device.
set.seed(1) n <- 50 p <- 6 X <- matrix(rnorm(n * p), n, p) colnames(X) <- paste0("x", seq_len(p)) y <- as.numeric(X %*% c(1.5, -1, 0.5, 0, 0, 0) + rnorm(n)) path <- coef_path(X, y, L = 0.5, alpha = 0.5, lambda = exp(seq(1, -5, length.out = 30)), gamma = 1 ) plot(path)set.seed(1) n <- 50 p <- 6 X <- matrix(rnorm(n * p), n, p) colnames(X) <- paste0("x", seq_len(p)) y <- as.numeric(X %*% c(1.5, -1, 0.5, 0, 0, 0) + rnorm(n)) path <- coef_path(X, y, L = 0.5, alpha = 0.5, lambda = exp(seq(1, -5, length.out = 30)), gamma = 1 ) plot(path)
cv_capnet
Plot cross-validation results for cv_capnet
## S3 method for class 'cv_capnet' plot(x, alpha = NULL, lambda = NULL, ...)## S3 method for class 'cv_capnet' plot(x, alpha = NULL, lambda = NULL, ...)
x |
An object of class |
alpha |
Optional numeric; if provided, show CV errors vs |
lambda |
Optional numeric; if provided, show CV errors vs |
... |
Further arguments passed to or from other methods. |
Three display modes depending on which arguments are supplied:
alpha nor lambda
Heatmap of ranked mean CV
errors across the full grid. Lighter fill =
better rank. Useful for identifying the most promising region before
inspecting slices.
alpha specifiedLine plot of mean CV error (± 1 SE across
folds) vs at the given . A dashed
vertical line marks the best .
lambda specifiedLine plot of mean CV error (± 1 SE) vs
at the given .
Supply at most one of alpha and lambda; both must be values
that appear in the searched grid.
The ggplot object, returned invisibly. As a side effect the
plot is printed to the current graphics device.
set.seed(1) n <- 80 p <- 10 X <- matrix(rnorm(n * p), n, p) y <- as.numeric(X %*% c(rep(1, 3), rep(0, p - 3)) + rnorm(n)) cv <- cv_capnet(X, y, gamma = 1, L = 1.5) plot(cv) # full heatmap plot(cv, alpha = cv$best_alpha) # error vs lambda slice plot(cv, lambda = cv$best_lambda) # error vs alpha sliceset.seed(1) n <- 80 p <- 10 X <- matrix(rnorm(n * p), n, p) y <- as.numeric(X %*% c(rep(1, 3), rep(0, p - 3)) + rnorm(n)) cv <- cv_capnet(X, y, gamma = 1, L = 1.5) plot(cv) # full heatmap plot(cv, alpha = cv$best_alpha) # error vs lambda slice plot(cv, lambda = cv$best_lambda) # error vs alpha slice
capnet modelPredict from a fitted capnet model
## S3 method for class 'capnet' predict(object, newdata = NULL, type = c("link", "response"), ...)## S3 method for class 'capnet' predict(object, newdata = NULL, type = c("link", "response"), ...)
object |
A fitted object of class |
newdata |
Optional numeric matrix with |
type |
Character; |
... |
Further arguments passed to or from other methods. |
When newdata = NULL, predictions are made on object$z, which
is the evaluation matrix used when the model was fit. This is convenient for
inspecting fitted contributions without re-specifying the data. When
newdata is supplied it must have exactly columns (matching
length(object$beta)) but may have any number of rows.
Numeric vector of length nrow(newdata) (or nrow(z) if
newdata is NULL).
set.seed(1) n <- 40 p <- 5 X <- matrix(rnorm(n * p), n, p) y <- as.numeric(X %*% c(1, -1, 0.5, 0, 0) + rnorm(n)) fit <- capnet(X, y, lambda = 0.1, alpha = 0.5, gamma = 1, L = 1) predict(fit, type = "response") # fitted values on training z predict(fit, newdata = X, type = "link") # linear predictor on new dataset.seed(1) n <- 40 p <- 5 X <- matrix(rnorm(n * p), n, p) y <- as.numeric(X %*% c(1, -1, 0.5, 0, 0) + rnorm(n)) fit <- capnet(X, y, lambda = 0.1, alpha = 0.5, gamma = 1, L = 1) predict(fit, type = "response") # fitted values on training z predict(fit, newdata = X, type = "link") # linear predictor on new data
capnet fitPredict from a walk-forward capnet fit
## S3 method for class 'walk_capnet' predict(object, ...)## S3 method for class 'walk_capnet' predict(object, ...)
object |
A fitted object of class |
... |
Currently unused. |
A matrix (or xts if the
input z was xts) of predictions on the response scale,
as computed during the walk-forward evaluation. NA entries indicate
steps where the optimizer failed to converge. To extract the full
coefficient path, use coef(object).
walk_capnet(), coef.walk_capnet()
set.seed(1) n <- 50 p <- 5 n_new <- 8 X <- matrix(rnorm(n * p), n, p) z <- matrix(rnorm(n_new * p), n_new, p) y <- as.numeric(X %*% c(1, -1, 0.5, 0, 0) + rnorm(n)) fit <- walk_capnet(X, y, L = 1, z = z, lambda = 0.1, alpha = 0.5, gamma = 1) predict(fit)set.seed(1) n <- 50 p <- 5 n_new <- 8 X <- matrix(rnorm(n * p), n, p) z <- matrix(rnorm(n_new * p), n_new, p) y <- as.numeric(X %*% c(1, -1, 0.5, 0, 0) + rnorm(n)) fit <- walk_capnet(X, y, L = 1, z = z, lambda = 0.1, alpha = 0.5, gamma = 1) predict(fit)
capnet_violations objectPrint the violation matrix from a capnet_violations object
## S3 method for class 'capnet_violations' print(x, ...)## S3 method for class 'capnet_violations' print(x, ...)
x |
An object of class |
... |
Optional arguments forwarded to |
Displays the excess-contribution matrix as a sparse matrix: only non-zero
entries (i.e., actual cap violations) are printed. Each non-zero entry
gives the amount by which exceeded
for that row-feature combination.
x, invisibly.
set.seed(1) n <- 40 p <- 5 X <- matrix(rnorm(n * p), n, p) y <- as.numeric(X %*% c(2, -1.5, 0, 0, 0) + rnorm(n)) fit <- capnet(X, y, lambda = 0.05, alpha = 0.5, gamma = 0.1, L = 0.5) v <- capnet_violations(fit) if (!is.null(v)) print(v) # sparse display of excess contributions if (!is.null(v)) v$excess[1:5, ] # raw accessset.seed(1) n <- 40 p <- 5 X <- matrix(rnorm(n * p), n, p) y <- as.numeric(X %*% c(2, -1.5, 0, 0, 0) + rnorm(n)) fit <- capnet(X, y, lambda = 0.05, alpha = 0.5, gamma = 0.1, L = 0.5) v <- capnet_violations(fit) if (!is.null(v)) print(v) # sparse display of excess contributions if (!is.null(v)) v$excess[1:5, ] # raw access
capnet
Creates synthetic regression data for two scenarios with a unified return
format. In both cases the function returns X, y, the
ground-truth
coefficients beta_true, and suggested caps L. When m >
0,
an evaluation matrix Z of m rows is also returned, generated
from
the same data-generating process and ready to pass as the z argument
of
capnet() or walk_capnet().
simulate_capnet_data( n = 100, p = 20, m = 0, mode = c("basic", "proxy"), sparsity = 0.7, beta_range = c(-2, 2), sigma = 1, seed = NULL, xstar_sd = 1, a_sd = 0.3, unstable_idx = NULL, unstable_frac = 0.2, sigma_low = 1, sigma_high = 8, high_prob = 0.1, family = c("gaussian", "binomial", "poisson", "gamma"), poisson_mean = 10, gamma_mean = 10, gamma_shape = 2, binomial_prob = 0.5 )simulate_capnet_data( n = 100, p = 20, m = 0, mode = c("basic", "proxy"), sparsity = 0.7, beta_range = c(-2, 2), sigma = 1, seed = NULL, xstar_sd = 1, a_sd = 0.3, unstable_idx = NULL, unstable_frac = 0.2, sigma_low = 1, sigma_high = 8, high_prob = 0.1, family = c("gaussian", "binomial", "poisson", "gamma"), poisson_mean = 10, gamma_mean = 10, gamma_shape = 2, binomial_prob = 0.5 )
n |
Integer; number of training observations. Default |
p |
Integer; number of predictors. Default |
m |
Integer; number of evaluation rows to generate. When |
mode |
Character; one of |
sparsity |
Numeric in |
beta_range |
Numeric length-2; uniform range for nonzero
|
sigma |
Positive numeric; noise sd for |
seed |
Optional integer for reproducibility. Default |
xstar_sd |
Positive numeric; sd of latent true signal |
a_sd |
Nonnegative numeric; sd of log-scales |
unstable_idx |
Optional integer vector of columns of |
unstable_frac |
Numeric in |
sigma_low |
Positive numeric; base noise sd for |
sigma_high |
Positive numeric; intermittent high noise sd for unstable
features. Default |
high_prob |
Numeric in |
family |
Character; response family, one of |
poisson_mean |
Positive numeric; target average response when
|
gamma_mean |
Positive numeric; target average response when
|
gamma_shape |
Positive numeric; fixed Gamma shape parameter used when
|
binomial_prob |
Numeric in |
In basic mode, nonzeros in beta_true are placed uniformly at
random and drawn from runif(beta_range[1], beta_range[2]). When
family = "gaussian", y = X %*% beta_true + N(0, sigma^2).
For the other families (see the rescaling description under the
family argument above), y ~ Poisson(exp(eta)) for
"poisson", y ~ Gamma(shape = gamma_shape, rate = gamma_shape /
exp(eta)) for "gamma", and y ~ Bernoulli(plogis(eta)) for
"binomial". In all cases, the suggested caps are
L_j = pmax(|beta_true_j|, 0.1) as a simple starting point. When
m > 0, Z is an matrix of i.i.d. standard
normal draws from the same pool as X.
In proxy mode, y = X^* %*% beta_true + N(0, sigma^2) and
X = diag(a) X^* + varepsilon. For columns in unstable_idx, each
row independently uses sigma_high with probability high_prob.
When m > 0, Z is generated by applying the same noisy proxy
process to m fresh latent rows, giving the observed evaluation matrix
a practitioner would actually have available at evaluation time.
A list with the following components:
X |
|
y |
Numeric response vector of length |
beta_true |
Numeric length- |
L |
Length- |
Z |
( |
For mode = "proxy", additional fields are included:
X_latent |
|
a |
Feature scales. |
unstable_idx |
Integer vector of unstable feature indices. |
stable_idx |
Integer vector of stable feature indices. |
mode = "proxy")These arguments control the generation of unstable proxy features when
simulating data under mode = "proxy".
set.seed(42) d_basic <- simulate_capnet_data(n = 100, p = 10, m = 20, sparsity = 0.5) names(d_basic) # includes Z d_pois <- simulate_capnet_data( n = 100, p = 10, m = 20, sparsity = 0.5, family = "poisson", poisson_mean = 15 ) range(d_pois$y) d_binom <- simulate_capnet_data( n = 100, p = 10, m = 20, sparsity = 0.5, family = "binomial", binomial_prob = 0.3 ) table(d_binom$y) d_gamma <- simulate_capnet_data( n = 100, p = 10, m = 20, sparsity = 0.5, family = "gamma", gamma_mean = 5 ) range(d_gamma$y) d_proxy <- simulate_capnet_data( mode = "proxy", n = 300, p = 8, m = 50, sparsity = 0.6, unstable_frac = 0.25, sigma_low = 1, sigma_high = 6, high_prob = 0.2 ) names(d_proxy) # includes Z and X_latentset.seed(42) d_basic <- simulate_capnet_data(n = 100, p = 10, m = 20, sparsity = 0.5) names(d_basic) # includes Z d_pois <- simulate_capnet_data( n = 100, p = 10, m = 20, sparsity = 0.5, family = "poisson", poisson_mean = 15 ) range(d_pois$y) d_binom <- simulate_capnet_data( n = 100, p = 10, m = 20, sparsity = 0.5, family = "binomial", binomial_prob = 0.3 ) table(d_binom$y) d_gamma <- simulate_capnet_data( n = 100, p = 10, m = 20, sparsity = 0.5, family = "gamma", gamma_mean = 5 ) range(d_gamma$y) d_proxy <- simulate_capnet_data( mode = "proxy", n = 300, p = 8, m = 50, sparsity = 0.6, unstable_frac = 0.25, sigma_low = 1, sigma_high = 6, high_prob = 0.2 ) names(d_proxy) # includes Z and X_latent
Validate the family/link combination is supported
validate_family_supported(fam)validate_family_supported(fam)
fam |
stats family object |
invisibly TRUE, errors otherwise
Fits a linear elastic net model with an additional contribution-cap penalty
once on the full training data X, y, then walks the
contribution-cap penalty forward across the evaluation matrix z,
re-solving the objective at each step with the penalty applied only to the
next walk row(s) of z (rather than to all of z at
once, as a single call to capnet would do). The training data
is not expanded or refit incrementally as z is walked; this mirrors
a deployment setting where X, y are a data snapshot (e.g. a
rolling training window) already prepared upstream, and repeating that
preprocessing for every new evaluation row would be prohibitively
expensive. To simulate a fully expanding training window instead, call
capnet directly in a loop with an updated X, y
at each step.
walk_capnet( X, y, L, z, family = "gaussian", intercept = TRUE, standardize = TRUE, multiplier = 1, walk = 1, lambda = 0, alpha = 0, gamma = 0, max_gamma_tries = 6, parallel = FALSE, workers = NULL, ... )walk_capnet( X, y, L, z, family = "gaussian", intercept = TRUE, standardize = TRUE, multiplier = 1, walk = 1, lambda = 0, alpha = 0, gamma = 0, max_gamma_tries = 6, parallel = FALSE, workers = NULL, ... )
X |
Numeric predictor matrix of shape |
y |
Numeric response vector of length |
L |
Nonnegative numeric scalar or length- |
z |
Numeric matrix with |
family |
Optional character scalar (e.g. "binomial"), function (e.g.
|
intercept |
Logical; should an intercept be fitted? Default |
standardize |
Logical; if |
multiplier |
Optional numeric scalar or length- |
walk |
Positive integer; number of consecutive rows of |
lambda |
Nonnegative numeric scalar; overall strength of the elastic net penalty. |
alpha |
Numeric scalar in |
gamma |
Nonnegative numeric scalar; strength of the contribution-cap penalty. |
max_gamma_tries |
Positive integer; maximum number of optimizer retries
per step with a reduced |
parallel |
Logical; if |
workers |
Optional integer; number of parallel workers to use when
|
... |
Additional arguments used in fitting. See |
Given the evaluation matrix z of size , X and
y are standardized (if requested) once, up front, and held fixed
across all steps. At step , capnet() is called
internally on this fixed training fit, with the contribution-cap penalty
restricted to rows of
z; because the cap penalty (and its gradient) depend on the
evaluation slice, coefficients are genuinely re-optimized at each step, not
merely re-evaluated. Penalizing a smaller, local slice of z instead
of the whole evaluation matrix at once (as plain capnet() would)
avoids the over-penalization that comes from forcing a single fit to
satisfy contribution caps uniformly across every evaluation row
simultaneously.
An object of class "walk_capnet" with components (each of
length / size , or an xts with the same
index if z is xts):
intercepts |
|
betas |
|
feature_contributions |
|
predictions |
|
gammas |
|
capnet(), cv_capnet(), coef.walk_capnet(),
predict.walk_capnet()
set.seed(1) n <- 60 p <- 6 n_new <- 12 X <- matrix(rnorm(n * p), n, p) z <- matrix(rnorm(n_new * p), n_new, p) beta <- c(2.5, 1.5, 0.8, rep(0, p - 3)) y <- as.numeric(X %*% beta + rnorm(n)) # One prediction per step out1 <- walk_capnet(X, y, L = 0.5, z = z, lambda = 0.1, alpha = 0.5, gamma = 1, walk = 1 ) predict(out1) # nrow(z) x 1 predictions coef(out1) # nrow(z) x (1 + p) coefficient path # Batch 3 rows per step (useful for weekly or monthly evaluation) out3 <- walk_capnet(X, y, L = 0.5, z = z, lambda = 0.1, alpha = 0.5, gamma = 1, walk = 3 ) any(is.na(predict(out3))) # check for convergence failuresset.seed(1) n <- 60 p <- 6 n_new <- 12 X <- matrix(rnorm(n * p), n, p) z <- matrix(rnorm(n_new * p), n_new, p) beta <- c(2.5, 1.5, 0.8, rep(0, p - 3)) y <- as.numeric(X %*% beta + rnorm(n)) # One prediction per step out1 <- walk_capnet(X, y, L = 0.5, z = z, lambda = 0.1, alpha = 0.5, gamma = 1, walk = 1 ) predict(out1) # nrow(z) x 1 predictions coef(out1) # nrow(z) x (1 + p) coefficient path # Batch 3 rows per step (useful for weekly or monthly evaluation) out3 <- walk_capnet(X, y, L = 0.5, z = z, lambda = 0.1, alpha = 0.5, gamma = 1, walk = 3 ) any(is.na(predict(out3))) # check for convergence failures