kir: Knowledge Integration Regression for Mean and Quantile Models

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.

Mean regression: 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)

Quantile regression: 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.