Nothing
#' Weighted Elastic Net prediction models for complex survey data
#'
#'@description A model selection function fitting Elastic Net (linear or logistic) models with sampling weights
#' by a replicating weights method to select an optimal lambda for a given alpha by weighted error minimization.
#' This is extended from `wlasso::wlasso()`, which is now officially available in \code{\link[svyVarSel]{wlasso}}. For an extended
#' model selection for a sequence of alpha's by CPU parallel computing, use [par_wElnet()].
#'
#' @param data A data frame with information about the response variable and covariates, as well as sampling weights, strata, and cluster indicators. It could be \code{NULL} if the sampling design were replaced in the \code{design} argument.
#' @param col.y A numeric value indicating the index of the response variable or a string of the response variable name .
#' @param col.x A numeric vector indicating indices of covariates or a vector of strings indicating these column names.
#' @param cluster A string of a cluster identifier. It could be \code{NULL} if the sampling design were plugged in the \code{design} argument.
#' @param strata A string of a strata identifier. It could be \code{NULL} if the sampling design were plugged in the \code{design} argument.
#' @param weights A string of a sampling weights' identifier. It could be \code{NULL} if the sampling design were included in the \code{design} argument.
#' @param design An object of class \code{survey.design} generated by \code{\link[survey]{svydesign}}. It could be \code{NULL} if information about \code{cluster}, \code{strata}, \code{weights} and \code{data} were given.
#' @param family A string indicating a \code{glm} family object for fitting weighted elastic net models. Choose between \code{gaussian} (to fit linear models) or \code{binomial} (for logistic models).
#' @param lambda A sequence of lambda supplied by a user.
#' @param nlambda An integer. The number of lambda grids to be generated. Default is \code{nlambda = 100}.
#' @param lambda.min.ratio The smallest value for \code{lambda}, as a fraction of the maximum lambda. If \code{NULL} (default), this is computed internally: \code{0.01} if the number of observations is smaller than the number of covariates, otherwise \code{0.0001}. A very small value of \code{lambda.min.ratio} will lead to a saturated fit in the \code{nobs < nvars} case. This is undefined for a \code{"binomial"} model.
#' @param standardize,offset,... Optional parameters to be passed to the low level function [glmnet::glmnet()].
#' @param alpha A numeric value of the elastic net mixing parameter \deqn{0 \le \alpha \le 1,} where \code{alpha = 1} for the LASSO penalty, and \code{alpha = 0} for the Ridge penalty.
#' @param method A string indicating a method of replicate weights. Choose one of these: \code{JKn}, \code{dCV}, \code{bootstrap}, \code{subbootstrap}, \code{BRR}, \code{split}, \code{extrapolation}.
#' @param k An integer. The number of folds for the \code{dCV} method. Default is \code{k=10}.
#' @param R An integer. The number of times the sample is partitioned for \code{dCV}, \code{split} or \code{extrapolation} method. Default is \code{R=1}.
#' @param B An integer. The number of bootstrap re-samples for \code{bootstrap} and \code{subbootstrap} methods. Default is \code{B=200}.
#' @param dCV.sw.test A logical value indicating the method for estimating the error for \code{dCV} method. \code{FALSE}, (the default option) estimates the error for each test set and defines the cross-validated error based on the average strategy.
#' Option \code{TRUE} estimates the cross-validated error based on the pooling strategy.
#' @param train.prob A numeric between 0 and 1 that sets the proportion of clusters (for the method \code{split}) or strata (for the method \code{extrapolation}) in training sets. Default is \code{train.prob = 0.7}.
#' @param method.split A string of one the following replicate weights methods to be implemented under the \code{split} method in the \code{method} argument: \code{dCV}, \code{bootstrap} or \code{subbootstrap}.
#' @param print.rw A logical value. If \code{TRUE}, the data set with the replicate weights is saved in the output object. Default \code{print.rw=FALSE}.
#'
#'
#'
#' @seealso [svyVarSel::wlasso()] for detailed arguments.
#' @seealso [glmnet::glmnet()] for detailed arguments and return values.
#'
#' @return The output object of the function \code{wElnet()} is an object of class \code{w.elnet}:
#' - `lambda`: A list containing information of two elements:
#' - `grid`: A vector of all grid values for the tuning parameter.
#' - `min`: A numeric value of an optimal tuning parameter minimizing the average error.
#' - `error`: A list containing information of two elements:
#' - `average`: A numeric vector indicating the average error for each tuning parameter in \code{lambda$grid}.
#' - `all`: A numeric matrix indicating the error of each test set for each tuning parameter.
#' - `alpha`: A numeric value of the elastic net mixing parameter used to fit this model (as supplied to the `alpha` argument).
#' - `model`: A list containing information of two elements in relation to the fitted models.
#' - `grid`: A list containing information on models fitted by each tuning parameter in the \code{lambda$grid}.
#' - `a0`: A numeric vector of model intercepts across the whole grid of tuning parameters (hence, of the same length as \code{lambda$grid}).
#' - `beta`: A matrix of regression coefficients for all the covariates across the whole grid of tuning parameters (the dimension of the matrix is the size of covariates by the length of \code{lambda$grid}).
#' - `df`: A numeric vector of the degrees of freedom (i.e., the number of coefficients different from zero) across the whole grid of tuning parameters (hence, of the same length as \code{lambda$grid}).
#' - `final_model`: An object with S3 class \code{glmnet} found in r-\code{glmnet}. A list containing information on the final model fitted by the optimal tuning parameter, \code{lambda$min}.
#' i.e., the optimal tuning parameter selected from \code{lambda$grid}.
#' - `data.rw`: A data frame containing the original data set and the replicate weights added to define training and test sets. Only included in the output object if \code{print.rw=TRUE}.
#' - `call`: The call that executes this function producing the object of \code{w.elnet}.
#'
#'* Note that both `model` and `final_model` are fitted by the original \code{data}, not by one of the generated training sets by replicate weights.
#'
#'
#'
#' @examples
#'
#' data(nhanes2013_sbc)
#' # alpha can be selected based on `glmnet::glmnet()`:
#' alpha <- c(0.000, 0.001, 0.008, 0.027, 0.064, 0.125, 0.216, 0.343, 0.512, 0.729, 1.000)
#' \donttest{
#' en.dcv <- wElnet(data = nhanes2013_sbc,
#' col.y = "HBP", col.x = 2:61,
#' family = "binomial", alpha = 0.729,
#' cluster = "SDMVPSU", strata = "SDMVSTRA", weights = "WTSAF2YR",
#' method = "dCV", k=10, R=20)
#'
#' # Or equivalently:
#' des <- survey::svydesign(ids=~SDMVPSU, strata = ~SDMVSTRA, weights = ~WTSAF2YR,
#' nest = TRUE, data = nhanes2013_sbc)
#' en.dcv <- wElnet(col.y = "HBP", col.x = 2:61, design = des,
#' family = "binomial", alpha = alpha[10],
#' method = "dCV", k=10, R=20)
#'}
#'
#'@export
# source("error.f.R")
wElnet <- function(data = NULL, col.y = NULL, col.x = NULL,
cluster = NULL, strata = NULL, weights = NULL, design = NULL,
family = c("gaussian", "binomial"),
lambda = NULL, alpha = 1,
nlambda = 100, lambda.min.ratio = NULL,
method = c("dCV", "JKn", "bootstrap", "subbootstrap", "BRR", "split", "extrapolation"),
k = 10, R = 1, B = 200,
dCV.sw.test = FALSE,
train.prob = 0.7, method.split = c("dCV", "bootstrap", "subbootstrap"),
print.rw = FALSE,standardize = TRUE,offset = NULL,...){
# Stops and messages:
if(is.null(data) & is.null(design)){stop("Information about either the data set ('data') or the sampling design ('design') needed.")}
if(method == "split"){
if(is.null(train.prob)){stop("Selected replicate weights method: 'split'.\nPlease, set a value between 0 and 1 for the argument 'train.prob'.")}
if(train.prob < 0 | train.prob > 1){stop("Selected replicate weights method: 'split'.\nPlease, set a value between 0 and 1 for the argument 'train.prob'.")}
if(length(method.split)!=1){stop("Selected replicate weights method: 'split'.\nPlease, set a valid method for the argument 'method.split'. Choose between: 'dCV', 'bootstrap' or 'subbootstrap'.")}
}
if(method == "extrapolation"){
if(is.null(train.prob)){stop("Selected replicate weights method: 'extrapolation'.\nPlease, set a value between 0 and 1 for the argument 'train.prob'.")}
if(train.prob < 0 | train.prob > 1){stop("Selected replicate weights method: 'extrapolation'.\nPlease, set a value between 0 and 1 for the argument 'train.prob'.")}
}
if(method %in% c("JKn", "bootstrap", "subbootstrap", "BRR")){
if(R!=1){message("Selected method: ", method,". For this method, R = 1. Thus, the argument R = ",R, " has been ignored.")}
}
if(method %in% c("dCV", "split", "extrapolation")){
if(R != round(R)){stop("The argument 'R' must be an integer greater or equal to 1. R=",R," is not an integer.\nPlease, set a valid value for 'R' or skip the argument to select the default option R=1.")}
if(R < 1){stop("The argument 'R' must be an integer greater or equal to 1. R=",R," lower than 1.\nPlease, set a valid value for 'R' or skip the argument to select the default option R=1.")}
}
if(method != "dCV"){
if(!is.null(k) & k!=10){message("Selected method: ", method,". The argument k = ",k, " is not needed and, hence, has been ignored.")}
}
if(method == "dCV"){
if(k != round(k)){stop("The argument 'k' must be an integer. k=",k," is not an integer.\nPlease, set a valid value for 'k' or skip the argument to select the default option k=10.")}
if(k < 1){stop("The argument 'k' must be a positive integer. k=",k," is not a positive integer.\nPlease, set a valid value for 'k' or skip the argument to select the default option k=10.")}
}
if(!(method %in% c("bootstrap", "subbootstrap"))){
if(!is.null(B) & B!=200){message("Selected method: ", method,". The argument B = ",B, " is not needed and, hence, has been ignored.")}
}
if(method %in% c("bootstrap", "subbootstrap")){
if(B != round(B)){stop("The argument 'B' must be an integer. B=",B," is not an integer.\nPlease, set a valid value for 'B' or skip the argument to select the default option B=200.")}
if(B < 1){stop("The argument 'B' must be a positive integer. B=",B," is not a positive integer.\nPlease, set a valid value for 'B' or skip the argument to select the default option B=200.")}
}
# Step 0: Notation
if(!is.null(design)){
cluster <- as.character(design$call$id[2])
if(cluster == "1" || cluster == "0"){
cluster <- NULL
}
strata <- as.character(design$call$strata[2])
weights <- as.character(design$call$weights[2])
# Use design$variables (the data frame survey::svydesign() already
# stores internally) rather than get(design$call$data). The latter
# requires re-evaluating a symbol back in whatever environment this
# function happens to be called from, which is fragile and breaks
# under a properly installed package namespace (e.g. during
# devtools::check() or R CMD check) even though it may appear to work
# under devtools::load_all()'s looser scoping.
data <- design$variables
}
# Step 0b: Resolve lambda.min.ratio default now that 'data' and 'col.x'
# are both guaranteed to be available (whether supplied directly or
# recovered from 'design' above). This mirrors glmnet's own convention:
# a smaller min ratio (0.01) when nobs < nvars to avoid a saturated fit,
# otherwise a very small ratio (0.0001) close to zero.
if(is.null(lambda.min.ratio)){
nobs <- nrow(data)
nvars <- length(col.x)
lambda.min.ratio <- ifelse(nobs < nvars, 0.01, 1e-04)
}
# Step 1: Generate replicate weights based on the method
newdata <- replicate_weights(data = data, method = method,
cluster = cluster, strata = strata, weights = weights,
k = k, R = R, B = B,
train.prob = train.prob, method.split = method.split,
rw.test = TRUE, dCV.sw.test = dCV.sw.test)
# Step 2: if is.null(lambda), then initialize it
if(is.null(lambda)){
model.orig <- glmnet::glmnet(y = as.numeric(newdata[,col.y]),
x = as.matrix(newdata[,col.x]),
weights = as.numeric(newdata[,weights]),
alpha = alpha,
family = family,
nlambda = nlambda,
lambda.min.ratio = lambda.min.ratio,
standardize = standardize, offset = offset,...)
lambda <- model.orig$lambda
} else {
model.orig <- glmnet::glmnet(y = as.numeric(newdata[,col.y]),
x = as.matrix(newdata[,col.x]),
weights = as.numeric(newdata[,weights]),
family = family, alpha = alpha,
lambda = lambda,
standardize = standardize, offset = offset,...)
}
# Step 3: Fit the training models and estimate yhat for units in the sample
rwtraincols <- grep("_train", colnames(newdata))
l.yhat <- list()
# alpha <- c(0.000, 0.001, 0.008, 0.027, 0.064, 0.125, 0.216, 0.343, 0.512, 0.729, 1.000)
for(col.w in rwtraincols){
model <- glmnet::glmnet(y = as.numeric(newdata[,col.y]),
x = as.matrix(newdata[,col.x]),
weights = as.numeric(newdata[,col.w]),
lambda = lambda, alpha = alpha,
family = family,
standardize = standardize, offset = offset,...)
# Sample yhat
yhat <- predict(model, newx=as.matrix(newdata[,col.x]), type = "response")
l.yhat[[length(l.yhat) + 1]] <- yhat
names(l.yhat)[[length(l.yhat)]] <- paste0("yhat_", colnames(newdata)[col.w])
}
# Step 4: estimate the error in the test sets
error <- error.f(data = newdata, l.yhat = l.yhat,
method = method, cv.error.ind = dCV.sw.test,
R = R, k = k, B = B,
col.y = col.y, family = family, weights = weights)
mean.error <- apply(error, 2, mean)
lambda.min <- lambda[which.min(mean.error)]
model <- glmnet::glmnet(y = data[,col.y],
x = as.matrix(data[,col.x]),
weights = data[,weights],
lambda = lambda.min, alpha = alpha,
family = family,
standardize = standardize, offset = offset,...)
result <- list()
result$lambda <- list(grid = lambda,
min = lambda.min)
result$error <- list(average = mean.error,
all = error)
result$alpha <- alpha
result$model <- list()
result$model$grid <- list(a0 = model.orig$a0,
beta = model.orig$beta,
df = model.orig$df)
result$model$final_model <- model
result$call <- match.call()
if(print.rw == TRUE){result$data.rw <- newdata}
class(result) <- "w.elnet"
return(result)
}
#' Print method for \code{w.elnet} objects (single-alpha \code{wElnet()} output)
#'
#' @description Prints a short summary of a \code{\link{wElnet}} fit: the alpha used,
#' the selected \code{lambda.min} and its weighted error, the number
#' of nonzero coefficients (degrees of freedom) at that lambda, and the
#' size of the lambda grid that was searched.
#'
#' @param x An object of class \code{w.elnet}, the output of \code{\link{wElnet}}.
#' @param digits Integer number of significant digits to use when printing numeric
#' values. Default is \code{4}.
#' @param ... Currently unused; included for S3 consistency with \code{print()}.
#'
#' @return Invisibly returns \code{x}. Called for its side effect of printing to the console.
#'
#' @examples
#' \donttest{
#' library(MLSurvey)
#' data(nhanes2013_sbc)
#'
#' en.dcv <- wElnet(data = nhanes2013_sbc,
#' col.y = "HBP", col.x = 2:61,
#' family = "binomial", alpha = 0.729,
#' cluster = "SDMVPSU", strata = "SDMVSTRA", weights = "WTSAF2YR",
#' method = "dCV", k = 10, R = 20)
#'
#' en.dcv # or print(en.dcv)
#' }
#'
#' @export
print.w.elnet <- function(x, digits = 4, ...){
min.idx <- which.min(abs(x$lambda$grid - x$lambda$min))
min.error <- x$error$average[min.idx]
min.df <- x$model$grid$df[min.idx]
cat("Weighted Elastic Net (wElnet)\n\n")
cat("alpha: ", signif(x$alpha, digits), "\n")
cat("lambda (min): ", signif(x$lambda$min, digits), "\n")
cat("Weighted error at min:", signif(min.error, digits), "\n")
cat("Nonzero coefs: ", min.df, "\n")
cat("Lambda grid size: ", length(x$lambda$grid), "\n")
invisible(x)
}
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.