Nothing
#' Penalized Quantile Regression Coefficients Modeling
#'
#' Fits the penalized integrated loss minimization (PILM) estimator of
#' Sottile et al. (2020) along a path of values of the tuning parameter
#' \eqn{\lambda}. Quantile regression coefficients are modelled as parametric
#' functions of the quantile order \eqn{p}, and covariates are selected using
#' the information on all quantiles simultaneously.
#'
#' @param formula a two-sided formula of the form `y ~ x1 + x2 + ...`. The
#' response can be a numeric vector or a [survival::Surv()] object of type
#' `"right"` (right censoring) or `"counting"` (left truncation and right
#' censoring), as in [qrcm::iqr()].
#' @param formula.p a one-sided formula of the form `~ b1(p, ...) + b2(p, ...) + ...`
#' describing how the quantile regression coefficients depend on `p`. The
#' default is a shifted Legendre polynomial of degree 3, see [qrcm::slp()].
#' @param weights an optional vector of non-negative weights.
#' @param data an optional data frame, list or environment containing the
#' variables in `formula`.
#' @param s an optional \eqn{q \times k}{q x k} 0/1 matrix that permits excluding
#' some model coefficients (\eqn{q} = number of columns of the model matrix,
#' \eqn{k} = number of basis functions in `formula.p`).
#' @param nlambda number of values of \eqn{\lambda} (default 100).
#' @param lambda.min.ratio smallest value of \eqn{\lambda}, as a fraction of
#' \eqn{\lambda_{max}}. The default is `1e-4` if the number of observations is
#' larger than the number of columns of the model matrix, and `0.01` otherwise.
#' @param lambda an optional user-supplied decreasing sequence of values of
#' \eqn{\lambda} (on the internal scale, see Details). It overrides `nlambda`
#' and `lambda.min.ratio`.
#' @param tol convergence tolerance (default `1e-6`).
#' @param maxit maximum number of Newton iterations for each \eqn{\lambda}
#' (default 100).
#' @param penalty either `"lasso"` (default), the \eqn{\ell_1} penalty
#' \eqn{\lambda\sum_{j,h} w_j|\theta_{jh}|} of Sottile et al. (2020, eq. 3.4),
#' or `"group"`, the group lasso penalty
#' \eqn{\lambda\sum_j w_j\sqrt{k_j}\,\|\theta_{j\cdot}\|_2} that selects
#' covariates (all the coefficients \eqn{\theta_{j1},\dots,\theta_{jk}} of the
#' \eqn{j}-th covariate are either zero or nonzero). Groups are the columns of
#' the model matrix (each dummy variable of a factor is a separate group), and
#' \eqn{k_j} is the number of free coefficients of column \eqn{j}. Ignored if
#' `method = "legacy"`.
#' @param penalty.factor optional vector of non-negative penalty weights
#' \eqn{w_j}, one for each column of the model matrix except the intercept
#' (which is never penalized). A zero weight leaves the covariate unpenalized
#' (it is always in the model). The default is 1 for all covariates. Different
#' weights can be used, for example, to compute an adaptive lasso.
#' @param method `"pnewton"` (default) for the proximal Newton algorithm
#' described in Details, or `"legacy"` for the algorithm of 'qrcmNP' 0.2.x,
#' kept for reproducibility of published results.
#' @param verbose logical: if `TRUE`, the progress along the path is printed.
#' @param ... not used (an error is given for the removed argument `display`).
#'
#' @details
#' Under the quantile regression coefficients model (QRCM) of Frumento and
#' Bottai (2016), the conditional quantile function is
#' \deqn{Q(p \mid x, \theta) = x^\top \theta\, b(p),}{Q(p | x, theta) = x' theta b(p),}
#' where \eqn{b(p)} is a set of \eqn{k} known functions of \eqn{p} (defined
#' by `formula.p`) and \eqn{\theta} is a \eqn{q \times k}{q x k} matrix of
#' parameters. The penalized estimator minimizes
#' \deqn{L_{PEN}(\theta) = \int_0^1 \sum_i w_i \rho_p\{y_i - Q(p \mid x_i, \theta)\}\,dp + \lambda\,\mathrm{pen}(\theta),}{%
#' L(theta) + lambda * pen(theta),}
#' where \eqn{\rho_p} is the check loss of quantile regression. As suggested by
#' Sottile et al. (2020), \eqn{x} and \eqn{b(p)} are standardized, and the
#' response is mapped to the interval \eqn{[0, 10]}; the values of `lambda` refer
#' to this internal scale. The estimated coefficients are returned on the
#' original scale.
#'
#' With `method = "pnewton"`, for each \eqn{\lambda} the integrated loss is
#' replaced by its second-order expansion (gradient and Hessian are available in
#' closed form) and the resulting penalized quadratic problem is solved by
#' coordinate descent (`"lasso"`) or block coordinate descent (`"group"`); a
#' backtracking line search guarantees the decrease of the penalized objective
#' (proximal Newton method). The path starts from
#' \eqn{\lambda_{max}}, the smallest value at which all penalized coefficients
#' are zero, and uses warm starts, sequential strong rules and a final check of
#' the Karush-Kuhn-Tucker conditions. With censored or truncated data, the
#' estimating equations of Frumento and Bottai (2017) replace the gradient of the
#' loss; since they are not the gradient of a loss function, the symmetric part
#' of their Jacobian is used in the quadratic approximation, and the iterate with
#' the smallest violation of the KKT conditions is returned (convergence is
#' declared when the average violation is below `5e-4`).
#'
#' The intercept (the first row of \eqn{\theta}) is never penalized. Use
#' [gof.piqr()] to select \eqn{\lambda} by AIC or BIC, [cv_piqr()] for
#' cross-validation, and [refit_piqr()] to re-estimate the selected model without
#' penalty and obtain standard errors (Sottile et al., 2020, Section 3.2).
#'
#' @return An object of class `"piqr"`, a list with items:
#' \item{call}{the matched call.}
#' \item{lambda}{the sequence of values of \eqn{\lambda}.}
#' \item{coefficients}{a list (one element for each \eqn{\lambda}) of
#' \eqn{q \times k}{q x k} matrices of estimated coefficients.}
#' \item{covar}{a list of covariance matrices (only with `method = "legacy"`,
#' otherwise `NULL`; use [refit_piqr()] for inference).}
#' \item{obj.function}{the minimized (unpenalized) integrated loss, on the
#' original scale, for each \eqn{\lambda}. For censored and truncated data
#' this is the loss function of 'qrcm', which is not the function minimized.}
#' \item{df}{number of covariates (including the intercept) with nonzero
#' coefficients, for each \eqn{\lambda}.}
#' \item{npar}{number of nonzero coefficients, for each \eqn{\lambda}.}
#' \item{dl}{matrix of the \eqn{\ell_1}-norms of the rows of the (unpenalized)
#' gradient, one column for each \eqn{\lambda}.}
#' \item{seqS}{a list of 0/1 matrices indicating the nonzero coefficients.}
#' \item{penalty, penalty.factor, method}{as in the call.}
#' \item{converged}{logical vector, convergence at each \eqn{\lambda}.}
#' \item{internal}{a list of objects used by the methods.}
#'
#' @references
#' Sottile, G., Frumento, P., Chiodi, M. and Bottai, M. (2020). A penalized
#' approach to covariate selection through quantile regression coefficient
#' models. *Statistical Modelling*, 20(4), 369-385. \doi{10.1177/1471082X19825523}
#'
#' Frumento, P. and Bottai, M. (2016). Parametric modeling of quantile
#' regression coefficient functions. *Biometrics*, 72(1), 74-84.
#' \doi{10.1111/biom.12410}
#'
#' Frumento, P. and Bottai, M. (2017). Parametric modeling of quantile
#' regression coefficient functions with censored and truncated data.
#' *Biometrics*, 73(4), 1179-1188. \doi{10.1111/biom.12675}
#'
#' Friedman, J., Hastie, T. and Tibshirani, R. (2010). Regularization paths for
#' generalized linear models via coordinate descent. *Journal of Statistical
#' Software*, 33(1), 1-22. \doi{10.18637/jss.v033.i01}
#'
#' Lee, J. D., Sun, Y. and Saunders, M. A. (2014). Proximal Newton-type methods
#' for minimizing composite functions. *SIAM Journal on Optimization*, 24(3),
#' 1420-1443. \doi{10.1137/130921428}
#'
#' @seealso [gof.piqr()], [cv_piqr()], [refit_piqr()], [summary.piqr()],
#' [plot.piqr()], [predict.piqr()].
#'
#' @examples
#' set.seed(1234)
#' n <- 300
#' x1 <- rexp(n)
#' x2 <- runif(n, 0, 5)
#' x3 <- rnorm(n) # irrelevant covariate
#' # true model: beta0(p) = 1 + qnorm(p), beta1(p) = 1 + 2 p, beta2(p) = 1
#' u <- runif(n)
#' y <- 1 + qnorm(u) + (1 + 2 * u) * x1 + x2
#' dat <- data.frame(y, x1, x2, x3)
#'
#' fit <- piqr(y ~ x1 + x2 + x3, formula.p = ~ slp(p, 2), data = dat, nlambda = 30)
#' fit
#' best <- gof.piqr(fit, method = "BIC", plot = FALSE)
#' coef(fit, pos.lambda = best$posMinLambda)
#'
#' # group lasso: covariates enter or leave the model as a whole
#' fitg <- piqr(y ~ x1 + x2 + x3, formula.p = ~ slp(p, 2), data = dat,
#' nlambda = 30, penalty = "group")
#' plot(fitg, xvar = "lambda")
#'
#' # unpenalized re-estimation of the selected model (with standard errors)
#' \donttest{
#' m <- refit_piqr(fit, pos.lambda = best$posMinLambda)
#' summary(m)
#' }
#' @export
piqr <- function(formula, formula.p = ~ slp(p, 3), weights, data, s, nlambda = 100,
lambda.min.ratio = ifelse(nobs < nvars, 0.01, 1e-04), lambda,
tol = 1e-6, maxit = 100, penalty = c("lasso", "group"),
penalty.factor, method = c("pnewton", "legacy"), verbose = FALSE, ...) {
cl <- match.call()
penalty <- match.arg(penalty)
method <- match.arg(method)
dots <- names(list(...))
if ("display" %in% dots)
stop("the argument 'display' was removed in qrcmNP 1.0.0: please use 'verbose'", call. = FALSE)
if (length(dots)) stop("unused argument(s): ", paste(dots, collapse = ", "), call. = FALSE)
mf <- match.call(expand.dots = FALSE)
m <- match(c("formula", "weights", "data"), names(mf), 0L)
mf <- mf[c(1L, m)]
mf$drop.unused.levels <- TRUE
mf[[1L]] <- quote(stats::model.frame)
mf <- eval(mf, parent.frame())
A <- check_in(mf, formula.p, if (missing(s)) NULL else s)
nobs <- nrow(A$V$X)
nvars <- ncol(A$V$X)
force(lambda.min.ratio)
if (!is.numeric(nlambda) || nlambda < 1) stop("'nlambda' must be a positive integer", call. = FALSE)
if (!missing(lambda)) {
if (any(lambda < 0)) stop("'lambda' must be non-negative", call. = FALSE)
lambda <- sort(lambda, decreasing = TRUE)
} else lambda <- NULL
pf <- make_penalty_factor(if (missing(penalty.factor)) NULL else penalty.factor, A)
fit <- if (method == "pnewton") {
piqr_path(A, penalty = penalty, pf = pf, nlambda = nlambda,
lambda.min.ratio = lambda.min.ratio, lambda = lambda,
tol = tol, maxit = maxit, verbose = verbose)
} else {
if (!missing(penalty.factor)) warning("'penalty.factor' is ignored with method = \"legacy\"", call. = FALSE)
piqr_legacy(A, nlambda = nlambda, lambda.min.ratio = lambda.min.ratio, lambda = lambda,
tol = tol, maxit = maxit, verbose = verbose)
}
mf <- A$mf
S <- list(B = A$stats.B, X = A$stats.X, y = A$stats.y)
attributes(A$bfun) <- c(attributes(A$bfun), S$B)
attr(mf, "assign") <- S$X$assign
attr(mf, "stats") <- S
attr(mf, "all.vars") <- A$V
attr(mf, "bfun") <- A$bfun
attr(mf, "type") <- A$type
attr(mf, "contrasts") <- attr(A$U$X, "contrasts")
nl <- length(fit$lambda)
labs <- paste0("lambda", seq_len(nl))
cn <- list(S$X$coef.names, S$B$coef.names)
coefficients <- lapply(fit$theta, function(th) { dimnames(th) <- cn; th })
# selected coefficients: nonzero on the internal (standardised) scale, where the
# penalty acts (the back-transformation can fill the constant column of b(p))
seqS <- lapply(fit$theta.int, function(th) { s0 <- 1 * (th != 0); dimnames(s0) <- cn; s0 })
names(coefficients) <- names(seqS) <- labs
if (!is.null(fit$covar)) names(fit$covar) <- labs
dl <- fit$dl; dimnames(dl) <- list(S$X$coef.names, labs)
out <- list(call = cl, lambda = fit$lambda, coefficients = coefficients, covar = fit$covar,
obj.function = fit$obj.function,
df = vapply(seqS, function(x) sum(rowSums(x) > 0), numeric(1)),
npar = vapply(seqS, sum, numeric(1)),
dl = dl, seqS = seqS, penalty = if (method == "legacy") "legacy" else penalty,
penalty.factor = pf, method = method,
converged = fit$converged)
names(out$df) <- names(out$npar) <- labs
out$internal <- list(mf = mf, formula = formula, formula.p = formula.p,
nlambda = nl, X = A$U$X, y = A$U$y, k = ncol(A$s),
intercept = S$X$intercept, type = A$type, s = A$s, pf = pf)
attr(out$internal$y, "sd") <- stats::sd(A$U$y)
class(out) <- "piqr"
out
}
#' Penalty factor for each column of the model matrix (0 for the intercept).
#' @noRd
make_penalty_factor <- function(penalty.factor, A) {
q <- ncol(A$V$X)
intX <- A$stats.X$intercept
cX <- A$stats.X$const
nonint <- setdiff(seq_len(q), if (intX) cX else integer(0))
pf <- rep.int(1, q)
if (!is.null(penalty.factor)) {
if (!is.numeric(penalty.factor) || any(penalty.factor < 0) || anyNA(penalty.factor))
stop("'penalty.factor' must be a vector of non-negative numbers", call. = FALSE)
if (length(penalty.factor) == 1) penalty.factor <- rep.int(penalty.factor, length(nonint))
if (length(penalty.factor) != length(nonint))
stop(sprintf("'penalty.factor' must have length %d (one weight for each column of the model matrix, excluding the intercept)",
length(nonint)), call. = FALSE)
pf[nonint] <- penalty.factor
}
if (intX) pf[cX] <- 0
names(pf) <- A$stats.X$coef.names
pf
}
#' Regularisation path with the proximal Newton solver.
#' @noRd
piqr_path <- function(A, penalty, pf, nlambda, lambda.min.ratio, lambda, tol, maxit, verbose) {
V <- A$V; bfun <- A$internal.bfun; type <- A$type
free <- (A$s == 1)
q <- nrow(free); k <- ncol(free)
ee <- get_ee(type)
S <- list(B = A$stats.B, X = A$stats.X, y = A$stats.y)
pen <- list(type = penalty, free = free,
W = matrix(pf, q, k) * free,
gw = pf * sqrt(rowSums(free)))
unpen <- free & (matrix(pf, q, k) == 0)
solver <- pnewton
# null model: only unpenalized coefficients
theta <- matrix(0, q, k)
if (any(unpen)) {
theta <- start_theta(V, bfun, 1 * unpen, type)
nf <- solver(theta, V, bfun, type, lambda = 0, pen = pen, active = unpen, tol = tol,
maxit = max(maxit, 10 + 10 * sum(unpen)))
theta <- nf$theta; g <- nf$g
} else {
ps <- pstar(theta, V, bfun, type)
g <- ee(theta, V$y, V$z, V$d, V$X, V$Xw, bfun, ps$y, ps$z, J = FALSE)$g
nf <- list(theta = theta, ps = ps, g = g, converged = TRUE)
}
# metric used when J = 0 (theta = 0 without unpenalized coefficients)
H0 <- NULL
if (!any(unpen)) {
th0 <- start_theta(V, bfun, 1 * free, type)
ps0 <- pstar(th0, V, bfun, type)
J0 <- ee(th0, V$y, V$z, V$d, V$X, V$Xw, bfun, ps0$y, ps0$z, J = TRUE)$J
H0 <- (J0 + t(J0)) / 2
}
crit <- function(g) {
# dual norm of the gradient, for each element (lasso) or row (group)
G <- matrix(g, q, k) * free
if (penalty == "lasso") abs(G) / ifelse(pen$W > 0, pen$W, Inf)
else sqrt(rowSums(G^2)) / ifelse(pen$gw > 0, pen$gw, Inf)
}
lmax <- max(c(crit(g), 0))
if (lmax == 0) lmax <- 1
user.lambda <- !is.null(lambda)
if (!user.lambda) {
lambda <- if (nlambda == 1) lmax
else exp(seq(log(lmax), log(lambda.min.ratio * lmax), length.out = nlambda))
}
nl <- length(lambda)
thetas <- thetas.int <- vector("list", nl)
set_active <- function(theta) {
if (penalty == "group") unpen | (matrix(rowSums(theta != 0) > 0, q, k) & free)
else unpen | (theta != 0 & free)
}
obj <- numeric(nl); conv <- logical(nl)
dl <- matrix(0, q, nl)
lprev <- lmax
active <- set_active(theta)
for (t in seq_len(nl)) {
lam <- lambda[t]
cr <- crit(g)
strong <- if (penalty == "lasso") (cr >= 2 * lam - lprev) & free
else matrix(cr >= 2 * lam - lprev, q, k) & free
act <- active | strong
if (t == 1 && !user.lambda) act <- unpen # lambda[1] = lambda_max: the null model
repeat {
if (t == 1 && !user.lambda) { fit <- nf; break }
fit <- solver(theta, V, bfun, type, lambda = lam, pen = pen, active = act,
tol = tol, maxit = maxit, H0 = H0)
theta <- fit$theta; g <- fit$g
# KKT check on the excluded coefficients
cr <- crit(g)
viol <- if (penalty == "lasso") (cr > lam * (1 + 1e-3)) & free & !act
else matrix(cr > lam * (1 + 1e-3), q, k) & free & !act
if (!any(viol)) break
act <- act | viol
}
active <- set_active(theta)
lprev <- lam
thetas.int[[t]] <- theta
thetas[[t]] <- check_out(theta, S)$theta
obj[t] <- loss_internal(theta, V, bfun, type, fit$ps) * (S$y$M - S$y$m) / 10
conv[t] <- fit$converged
dl[, t] <- rowSums(abs(matrix(g, q, k) * free))
if (verbose) {
message(sprintf("lambda %3d: %10.5f obj.function = %10.4f df = %d npar = %d",
t, lam, obj[t], sum(rowSums(theta != 0) > 0), sum(theta != 0)))
}
}
if (!all(conv)) warning(sprintf("the algorithm did not converge for %d value(s) of lambda", sum(!conv)),
call. = FALSE)
list(lambda = lambda, theta = thetas, theta.int = thetas.int, covar = NULL, obj.function = obj,
dl = dl, converged = conv)
}
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.