R/welnet.R

Defines functions print.w.elnet wElnet

Documented in print.w.elnet wElnet

#' 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)
}

Try the MLSurvey package in your browser

Any scripts or data that you put into this service are public.

MLSurvey documentation built on Nov. 18, 2026, 5:11 p.m.