| Type: | Package |
| Title: | Contribution-Capped Elastic Net Regularization |
| Version: | 0.4.1 |
| Date: | 2026-10-28 |
| Copyright: | 2026 Harry He |
| 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>. |
| URL: | https://github.com/harryziyuhe/capnet |
| BugReports: | https://github.com/harryziyuhe/capnet/issues |
| Depends: | R (≥ 4.1) |
| Imports: | rlang, lbfgs, ggplot2, xts, zoo, Matrix, stats, parallel |
| Suggests: | knitr, rmarkdown, xtable, glmnet, testthat (≥ 3.0.0) |
| License: | GPL-2 | GPL-3 [expanded from: GPL (≥ 2)] |
| VignetteBuilder: | knitr |
| Encoding: | UTF-8 |
| Config/testthat/edition: | 3 |
| Config/roxygen2/version: | 8.1.0 |
| NeedsCompilation: | no |
| Packaged: | 2026-10-30 17:13:20 UTC; ziyuhe |
| Author: | Harry He [aut, cre, cph] |
| Maintainer: | Harry He <zih028@ucsd.edu> |
| Repository: | CRAN |
| Date/Publication: | 2026-11-18 21:00:02 UTC |
Fit a linear model with elastic net and contribution cap regularization
Description
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.
Usage
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,
...
)
Arguments
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. |
Details
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.
Value
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. |
See Also
cv_capnet(), walk_capnet(), predict.capnet(),
coef.capnet(), capnet_violations()
Examples
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
)
Check contribution-cap violations for a fitted capnet model
Description
Identifies where feature contributions exceed the specified contribution cap. Returns the indices of offending rows and columns along with the excess contribution matrix.
Usage
capnet_violations(object, z = NULL, multiplier = NULL)
Arguments
object |
A fitted |
z |
Optional numeric matrix of new data on which to evaluate
contribution caps. If |
multiplier |
Optional numeric scalar or length- |
Details
Contributions are computed as
|X_{ij} \beta_j|\times multiplier_i,
compared against the cap L_j stored in the fitted object. The returned
excess matrix gives
\max(|X_{ij} \beta_j| \times multiplier_i - L_j, 0).
Value
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.
See Also
Examples
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)
Extract coefficients from a fitted capnet model
Description
Returns the estimated intercept and coefficients from a fitted
capnet model object.
Usage
## S3 method for class 'capnet'
coef(object, ...)
Arguments
object |
A fitted object of class |
... |
Further arguments passed to or from other methods. |
Value
A (1+p)\times 1 numeric matrix. The first row is the
intercept (named "(Intercept)"); the remaining p rows are
the fitted slopes, named from colnames(X) when available.
See Also
Examples
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 only
Extract coefficient paths from a walk-forward capnet fit
Description
Extract coefficient paths from a walk-forward capnet fit
Usage
## S3 method for class 'walk_capnet'
coef(object, index = NULL, ...)
Arguments
object |
A fitted object of class |
index |
Optional integer vector of step indices (1 to |
... |
Further arguments passed to or from other methods. |
Value
A \mathrm{nrow}(z)\times(1+p) matrix (or xts if the
input z was xts). The first column is the intercept path
(named "intercept"); the remaining p 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.
See Also
walk_capnet(), predict.walk_capnet()
Examples
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 only
Calculate coefficients along a penalty path
Description
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.
Usage
coef_path(
X,
y,
L,
lambda = exp(seq(1, -5, length.out = 50)),
alpha = 0.5,
gamma = 1,
standardize = FALSE,
...
)
Arguments
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 |
Details
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.
Value
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 p 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.
See Also
Examples
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)
Perform cross-validation for capnet
Description
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.
Usage
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,
...
)
Arguments
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 |
Details
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)]
Value
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 |
See Also
capnet(), walk_capnet(), plot.cv_capnet()
Examples
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
Description
Normalize user input into a stats family object
Usage
normalize_family(family = NULL)
Arguments
family |
optional character scalar (e.g. "binomial"),
a function (e.g. |
Value
A stats family object
Plot coefficient paths along a single hyperparameter
Description
Plot coefficient paths along a single hyperparameter
Usage
## S3 method for class 'capnet_path'
plot(x, ...)
Arguments
x |
An object of class |
... |
Further arguments passed to or from other methods. |
Details
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.
Value
The ggplot object, returned invisibly. As a side effect the
plot is printed to the current graphics device.
Examples
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)
Plot cross-validation results for cv_capnet
Description
Plot cross-validation results for cv_capnet
Usage
## S3 method for class 'cv_capnet'
plot(x, alpha = NULL, lambda = NULL, ...)
Arguments
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. |
Details
Three display modes depending on which arguments are supplied:
- Neither
alphanorlambda Heatmap of ranked mean CV errors across the full
\alpha\times\lambdagrid. Lighter fill = better rank. Useful for identifying the most promising region before inspecting slices.alphaspecifiedLine plot of mean CV error (± 1 SE across folds) vs
\log\lambdaat the given\alpha. A dashed vertical line marks the best\lambda.lambdaspecifiedLine plot of mean CV error (± 1 SE) vs
\alphaat the given\lambda.
Supply at most one of alpha and lambda; both must be values
that appear in the searched grid.
Value
The ggplot object, returned invisibly. As a side effect the
plot is printed to the current graphics device.
Examples
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 slice
Plot redistribution of coefficients and contributions
Description
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.
Usage
plot_redistribution(
uncapped,
capped,
X = NULL,
multiplier = NULL,
top_n = Inf,
plot = c("raw", "delta")
)
Arguments
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 |
Details
For each model, per-row contributions are computed as
contrib_{ij} = X_{ij}\hat\beta_j \times multiplier_i; the displayed
contribution for feature j is the mean over rows:
\bar{contrib}_j = \mathrm{mean}_i(X_{ij}\hat\beta_j \times
multiplier_i).
The multiplier from the capped model is used; if the two models
were fit with different multipliers the comparison may be misleading.
Value
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. Ifplot = "delta": bar chart of changes in coefficients (capped - uncapped).p2If
plot = "raw": side-by-side bar chart of contributions for uncapped vs capped models. Ifplot = "delta": bar chart of changes in contributions (capped - uncapped).
The function prints both plots and invisibly returns the list
list("beta" = p1, "contribution" = p2)
See Also
Examples
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")
Predict from a fitted capnet model
Description
Predict from a fitted capnet model
Usage
## S3 method for class 'capnet'
predict(object, newdata = NULL, type = c("link", "response"), ...)
Arguments
object |
A fitted object of class |
newdata |
Optional numeric matrix with |
type |
Character; |
... |
Further arguments passed to or from other methods. |
Details
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 p columns (matching
length(object$beta)) but may have any number of rows.
Value
Numeric vector of length nrow(newdata) (or nrow(z) if
newdata is NULL).
See Also
Examples
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 data
Predict from a walk-forward capnet fit
Description
Predict from a walk-forward capnet fit
Usage
## S3 method for class 'walk_capnet'
predict(object, ...)
Arguments
object |
A fitted object of class |
... |
Currently unused. |
Value
A \mathrm{nrow}(z)\times 1 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).
See Also
walk_capnet(), coef.walk_capnet()
Examples
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)
Print the violation matrix from a capnet_violations object
Description
Print the violation matrix from a capnet_violations object
Usage
## S3 method for class 'capnet_violations'
print(x, ...)
Arguments
x |
An object of class |
... |
Optional arguments forwarded to |
Details
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 |z_{ij}\hat\beta_j| exceeded L_j
for that row-feature combination.
Value
x, invisibly.
See Also
Examples
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 access
Generate synthetic data for testing capnet
Description
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().
Usage
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
)
Arguments
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 |
Details
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 m \times p 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.
Value
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. |
Proxy/unstable-feature controls (used when mode = "proxy")
These arguments control the generation of unstable proxy features when
simulating data under mode = "proxy".
Examples
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_latent
Validate the family/link combination is supported
Description
Validate the family/link combination is supported
Usage
validate_family_supported(fam)
Arguments
fam |
stats family object |
Value
invisibly TRUE, errors otherwise
Perform walk-forward model fitting with contribution caps
Description
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.
Usage
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,
...
)
Arguments
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 |
Details
Given the evaluation matrix z of size S\times p, X and
y are standardized (if requested) once, up front, and held fixed
across all steps. At step s=1,\dots,S, capnet() is called
internally on this fixed training fit, with the contribution-cap penalty
restricted to rows (s-1)\times\mathrm{walk}:s\times\mathrm{walk} 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.
Value
An object of class "walk_capnet" with components (each of
length / size \mathrm{nrow}(z), or an xts with the same
index if z is xts):
intercepts |
|
betas |
|
feature_contributions |
|
predictions |
|
gammas |
|
See Also
capnet(), cv_capnet(), coef.walk_capnet(),
predict.walk_capnet()
Examples
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 failures