The kir package combines observed data with prior knowledge for
sparse mean and quantile regression. Use kir() for mean
models (pSCAD or pLASSO) and kiqr() for quantile models;
both families support fixed fitting, CV, and HBIC.
If you have access to the GitHub repository, install its development version with:
remotes::install_github("jiantongwanguc/KIQR-R-package")The CRAN version, once available, may be older than the GitHub version.
kir() (pSCAD and pLASSO)kir() is the mean-regression counterpart of
kiqr() with a similar interface (no tau,
huber_gamma, beta_init,
rqpen_control or lambda_scale). With
squared-error loss L and prior predictions
Yhat^p, it weights L(beta; X, Y) and
L(beta; X, Yhat^p) by 1 - zeta and
zeta, which equals penalized least squares on the
pseudo-response (1 - zeta) * Y + zeta * Yhat^p, computed
through ncvreg. The default penalty = "SCAD" gives the
prior SCAD (pSCAD) estimator; penalty = "LASSO" gives the
prior LASSO (pLASSO) of Jiang, He and Zhang (2016), with
zeta = eta / (1 + eta). Unlike kiqr(),
kir() standardizes the predictors internally (through
ncvreg), so lambda is on the standardized scale. CV uses
the mean squared error against the observed responses and the same
"min" and "1se" rules as
kiqr_cv(); method = "hbic" uses the HBIC of
kiqr_hbic() with the residual sum of squares in place of
the check loss (at least three predictors).
The automatic mean-regression lambda path follows ncvreg’s default
path for the observed data: 100 values, logarithmically spaced from
lambda_max down to
lambda_min_ratio * lambda_max. On the standardized
predictor scale, lambda_max is the smallest lambda at which
all penalized slopes are zero. The default lambda_min_ratio
is 0.001 when the number of observations exceeds the number of
nonconstant predictors and 0.05 otherwise. The same path is used for
every zeta and every fold. nlambda and
lambda_min_ratio change the path; a degenerate path
contains only zero when all penalized gradients are zero. The default
zeta grid is seq(0, 1, by = 0.1).
library(kir)
set.seed(42)
n <- 60
x <- matrix(rnorm(n * 6), n, 6)
y <- drop(1 + x[, 1] - 0.5 * x[, 2] + rnorm(n, sd = 0.5))
beta_prior <- c(0.8, 0.9, -0.4, 0, 0, 0, 0)
cv <- kir(x, y, beta_prior, foldid = rep(1:5, length.out = n))
summary(cv, rule = "1se")
plasso <- kir(x, y, beta_prior, lambda = 0.05, zeta = 0.5, penalty = "LASSO")
coef(plasso)kiqr()For quantile regression, KIQR combines observed responses with
predictions from supplied prior coefficients to fit conditional quantile
models. Use kiqr() for cross-validation (CV), selection by
a high-dimensional Bayesian information criterion (HBIC), or fitting at
fixed tuning values. The KIQR method is described by Wang, Lian, Yu, Zu
and Zhang (2026), arXiv:2406.12212.
lambda controls the penalty strength. Use
penalty = "SCAD" (the default) for smoothly clipped
absolute deviation or penalty = "LASSO" for LASSO.
zeta is the knowledge weight. At zeta = 0,
KIQR reduces to standard penalized quantile regression with the chosen
penalty using only the observed responses. For
0 < zeta < 1, it combines observed responses and
prior predictions using a Huber-smoothed quantile loss. At
zeta = 1, it uses only prior predictions with no penalty.
For positive weights, estimation uses a backtracking proximal-gradient
(PGD) solver. The intercept is never penalized.
Supply a numeric predictor matrix or data frame x
without an intercept column, a response vector y, and
beta_prior: the intercept followed by one prior coefficient
per predictor. All training inputs must be finite. The prior must match
the predictor order, coding, units, and quantile level. Coefficient
names do not reorder the prior. kiqr() does not standardize
predictors; kir() does (see above).
The following examples are self-contained. Small candidate grids keep them quick to run; choose grids appropriate to your own data.
library(kir)
set.seed(42)
n <- 41
x <- cbind(age = rnorm(n), marker = rnorm(n))
y <- drop(cbind(1, x) %*% c(1, 1, -0.5) + rnorm(n, sd = 0.2))
# A supplied prior independent of y, including the intercept.
beta_prior <- c(0.5, 0.7, 0)
foldid <- rep(1:3, length.out = n)
x_new <- x[1:2, , drop = FALSE]
# CV is the default when the two tuning values are not both scalars.
cv <- kiqr(x, y, beta_prior, tau = 0.5,
lambda = c(0.01, 0.02), zeta = c(0, 0.5), foldid = foldid,
huber_gamma = 0.1, max_iter = 3000)
coef(cv, rule = "min")
coef(cv, rule = "1se")
summary(cv, rule = "1se")
predict(cv, newdata = x_new, rule = "1se")
# Two scalar tuning values select a fixed fit when method is omitted.
fit <- kiqr(x, y, beta_prior, tau = 0.5, lambda = 0.01, zeta = 0.25,
beta_init = beta_prior, huber_gamma = 0.1)
summary(fit)
# LASSO uses the same interface, tuning methods, and penalty factors.
lasso <- kiqr(x, y, beta_prior, tau = 0.5, penalty = "LASSO",
lambda = c(0.01, 0.02), zeta = c(0, 0.5), foldid = foldid,
huber_gamma = 0.1, max_iter = 3000)
print(lasso)
summary(lasso, rule = "1se")
# HBIC requires at least three predictors, excluding the intercept.
x3 <- cbind(x, noise = seq_len(nrow(x)) / nrow(x))
hbic <- kiqr(x3, y, c(beta_prior, 0), tau = 0.5, method = "hbic",
lambda = c(0.01, 0.02), zeta = c(0, 0.5),
beta_init = c(beta_prior, 0), huber_gamma = 0.1,
max_iter = 3000)
summary(hbic)An explicit method = "cv", "hbic", or
"fit" takes precedence over automatic method selection.
Fixed fits require one value each for lambda and
zeta. In CV and HBIC modes, each scalar fixes one
parameter, each vector supplies its candidates, and each omitted or
NULL grid is generated independently. With both tuning
arguments omitted, kiqr() uses automatic CV grids. For
automatic HBIC grids, also set method = "hbic".
Automatic quantile lambda paths use only observed data by default and
do not depend on the prior or zeta grid. The path normally contains 30
values, logarithmically spaced from the observed-data upper bound
supplied by rqPen down to lambda_min_ratio times that
bound. The default lambda_min_ratio is 0.01 for
n >= p and 0.05 for n < p, where
n is the number of observations and p is the
number of predictors. nlambda and
lambda_min_ratio control the path.
lambda_scale = "combined" instead extends the upper end of
the path to cover thresholds that depend on the prior and the zeta grid.
If the observed-data bound is zero, the mixed-loss upper bound is used
instead. Degenerate paths contain only zero when lambda is irrelevant or
all thresholds are zero. The default zeta grid is
seq(0, 1, by = 0.1). The direct kiqr_cv()
interface also supports automatic grids; kiqr_hbic()
requires both grids to be supplied. HBIC requires at least two
observations and finite, strictly positive total check loss for every
scored candidate.
CV retains both minimum-loss ("min") and
one-standard-error ("1se") fits. The 1-SE rule holds zeta
at its minimum-loss value and selects the largest eligible lambda at
that zeta whose mean fold loss is within one standard error of the
minimum. Each fold has equal weight. Coefficient extraction, prediction,
and summaries default to rule = "min"; printing a CV object
shows both tuning pairs. HBIC and fixed fitting return one
kiqr_fit object. All fitted objects support
coef(), predict(), summary(), and
print(). Summaries report coefficients and diagnostics,
without standard errors or hypothesis tests. Their
threshold argument affects only the predictor count, not
coefficients or predictions. For zeta = 0 fits, solver
convergence is reported as unavailable; see ?kiqr_fit for
implementation details.
If you estimate the prior from the observed responses, supply
beta_prior_fold_fun to CV so it is estimated within each
training fold. The supplied beta_prior is still used for
the final full-data refits; the callback is not called again on the full
data. Automatic grids are constructed once from the full-data inputs.
Supply prespecified grids if they must be independent of held-out
responses.
Automatic path construction or initialization may emit quantreg’s
“Solution may be nonunique” warning, including for intercept-only median
regression with an even sample size. HBIC may repeat the same
initialization warning across candidates. This warning alone does not
establish whether the final PGD fit converged; inspect
convergence and, for CV, candidate eligibility and fold
diagnostics. kiqr() does not suppress these warnings.
Other named arguments are passed to the selected fitting function.
Unsupported, unnamed, or duplicated additional arguments are errors. See
?kiqr for method-specific options and
?kiqr_cv, ?kiqr_hbic, and
?kiqr_fit for runnable examples. Formula input is not
supported.
Summary printing is controlled by
options(kir.max_print = n) (default 30) or the
max_print argument. Use ?kir for the
mean-regression function and ?"kir-package" for an overview
of both model families.