R/optim.wxgb.para.R

Defines functions generate_wxgb_params optim_wxgb_para

Documented in generate_wxgb_params optim_wxgb_para

#' Optimal (hyper-) parameter search for weighted XGBoost (wXGBoost) for complex survey data
#'
#' @description
#' A function to automate an optimal search for (hyper-) parameter via random sampling and to perform cross validation
#' by replicate weights methods, `wXGBoost`.  The final model is not estimated (`final.model=FALSE`).
#'
#' @param y A numeric vector of response variable.
#' @param col.x A numeric vector indicating indices of the covariates or a string vector indicating these column names.
#' @param custom_space A named list passed downwards to modify structural parameters or samplers. Defaults to an empty \code{list()}.
#'                    See also [generate_wxgb_params()]. The complete list of parameters is found on
#'                     [xgboost::xgb.train()] or \url{https://xgboost.readthedocs.io/en/latest/parameter.html}.
#' @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 added to the \code{design} argument.
#' @param nitr The number of iterations in the \code{for}-loop to search for optimal (hyper-) parameters.  Default is `50`.
#' @param nfolds The number of folds to be defined for \code{dCV} method. Default is \code{nfolds=10}.
#' @param R The number of times the sample is partitioned for the \code{dCV}, \code{split}, or \code{extrapolation} methods. Default is \code{R=1}.
#' @param B The number of bootstrap re-samples for \code{bootstrap} and \code{subbootstrap} methods. Default is \code{B=200}, matching \code{\link{wXGBoost}}'s own default.
#' @param nRounds The maximum number of boosting iterations.
#' @param missing Default is set to `NA`, which means that `NA` values should be considered as 'missing' by the algorithm.  Sometimes, `0` or other extreme values might be used to represent missing values. This parameter is only used when input is a dense matrix.
#' @param method A character 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 train.prob A numeric between 0 and 1, indicating the proportion of clusters (for the method \code{split}) or strata (for the method \code{extrapolation}) to be set in the training sets. Default is \code{train.prob = 0.7}, matching \code{\link{wXGBoost}}'s own default. Only applies to \code{split} and \code{extrapolation} methods.
#' @param method.split A string of one the following replicate weights methods to be implemented under the \code{split} in the \code{method} argument: \code{dCV}, \code{bootstrap} or \code{subbootstrap}. Default is \code{"dCV"}, matching \code{\link{wXGBoost}}'s own default. Only applies to the \code{split} method.
#' @param nstop \code{NULL} does not trigger the early stopping function. Setting to an integer k will stop training with a validation set unless the performance improve for k rounds.  Setting this parameter engages the `cb.early.stop` callback.
#' @param seed An integer to set the seed for random parameter reproducibility.  This is not for `wXGBoost()` implementation but for `generate_wxgb_params()`.
#' @param maximize If \code{nstop} is set, then this parameter must be set as well. Default is `FALSE` since the weighted loss function is used for minimization. This parameter is passed to the cb.early.stop callback.
#' @param cluster A character string of a cluster identifier. It could be \code{NULL} if the sampling design were plugged in the \code{design} argument.
#' @param strata A character string of a strata identifier. It could be \code{NULL} if the sampling design were plugged in the \code{design} argument.
#' @param weights A character string of a sampling weights' identifier. It could be \code{NULL} if the sampling design were plugged in the \code{design} argument.
#' @param design An object of class \code{survey.design} generated by \code{survey::svydesign()}. It could be \code{NULL} if information about \code{cluster}, \code{strata}, \code{weights} and \code{data} were given.
#' @param print_every_n Print each n-th iteration evaluation messages when verbose>0. Default is `50L` printing every 50th iteration message. This parameter is passed to the `cb.print.evaluation` callback.
#' @param ... optional parameters to be passed to the low level function \code{xgboost::xgb.train()} or \code{xgboost::xgboost()}.
#'
#' @seealso [xgboost::xgb.train()] for relevant arguments and return values in detail.
#' @seealso [wXGBoost()], [replicate_weights()] for detailed information on implementation.
#'
#' @return   A list of return values for optimal (hyper-)parameters as follows:
#' - `nrounds` : The best iteration number having the best evaluation metric value, i.e., minimum mean test error
#' - `params`  : A list of optimal (hyper-) parameters selected among all the `nitr` models implemented by `wxgboost(final.model=FALSE)`.
#' - `min_test_errors`: A table of all minimum weighted test errors and corresponding best iteration numbers for `nitr` iterations.  One can check how `nrounds` has
#'                     been chosen to be optimal by the minimum weighted test error.
#'
#' @examples
#'  ## Set user defined (hyper-)parameters for random search:
#'  custom  <- list(nthread=3,
#'                max_depth = 5,
#'                eta = function() runif(1, 0.05, 0.15),
#'                subsample = 0.5, # much smaller for large N
#'                max_delta_step = sample(1:10, 1) ) # for very imbalanced case
#'
#'   ## search for optimal parameters
#'\donttest{
#'  data(nhanes2013_sbc)
#'  Mydesign <- survey::svydesign(ids=~SDMVPSU, strata = ~SDMVSTRA,
#'                      weights = ~WTSAF2YR,nest = TRUE, data = nhanes2013_sbc)
#'  opt.par<- optim_wxgb_para(nhanes2013_sbc$HBP,2:61,custom,method="dCV",
#'                            design=Mydesign,print_every_n=250L)
#'
#'  ## search using bootstrap instead, with a custom B:
#'  opt.par.boot <- optim_wxgb_para(nhanes2013_sbc$HBP,2:61,custom,method="bootstrap",
#'                            B = 50, design=Mydesign,print_every_n=250L)
#'}
#' \donttest{
#'  ## fitting the optimal model
#'
#'  ### The data needs to be a sparse matrix without intercept.
#'  ### Generate a sparse matrix from a regular dataset for training
#'  unwtData<-nhanes2013_sbc[,-c(62:66)]   #excluding weight related vectors
#'  Mat<- Matrix::sparse.model.matrix(HBP~. ,data = unwtData )[,-1]   #dropping intercept
#'  wtData <- xgboost::xgb.DMatrix(data = nhanes2013_sbc,label=nhanes2013_sbc$HBP,
#'                        weight=nhanes2013_sbc$WTSAF2YR)
#'
#' # Can include test data--it should be a xgb.DMatrix object--
#' # e.g., `eval=list(train=data1,test=data2)`.
#'  wxgb<-xgboost::xgb.train(data=wtData, params=opt.par$params, nrounds=opt.par$nrounds,
#'            evals=list(train=wtData),
#'            custom_metric = evalerror_bin, verbose=0)
#'}
#' @export
optim_wxgb_para<-function(y,col.x,custom_space = list(),nitr=50,nfolds=10,R=1,B=200,nRounds=10000,nstop=5,seed= 120,
                          method = c("dCV", "JKn", "bootstrap", "subbootstrap", "BRR", "split", "extrapolation"),
                          train.prob = 0.7, method.split = c("dCV", "bootstrap", "subbootstrap"),
                          missing = NA, maximize=FALSE,cluster = NULL, strata = NULL, weights = NULL,
                          design = NULL,data=NULL,print_every_n=50L,...){

  method.split <- match.arg(method.split)

  # 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])
    data <- design$variables
  }

  # for reproducibility
  set.seed(seed)

  mt_errors<-numeric(nitr); mitrs<-numeric(nitr);mpara<-vector("list", nitr)

                 for (iter in seq_len(nitr)) {
                   # Generate parameters dynamically using the custom space configuration
                   param <- generate_wxgb_params(custom_space)

                   # Run Cross-Validation safely inside a tryCatch block
                    wxgb<- tryCatch({
                          wXGBoost(data = data, y =y, col.x = col.x,missing = missing,
                                   cluster = cluster, strata = strata, weights = weights,
                                   params = param, nrounds=nRounds, verbose = 0, print_every_n = print_every_n,
                                   early_stopping_rounds = nstop, final.model=FALSE,
                                   method = method,maximize=maximize,
                                   k = nfolds, R = R, B = B, dCV.sw.test = FALSE,
                                   train.prob = train.prob, method.split = method.split,
                                   print.rw = FALSE, save_period = NULL, save_name = "wxgboost.model",
                                    callbacks = list())}, error = function(e) {
                                      # This prints the specific error message to your console
                                      message(paste0("!! Warning: Iteration ", iter, " failed. Error details: ", e$message))
                                      return(NULL)
                                    })
                    # Handle failed iterations gracefully
                    if (is.null(wxgb)) {
                        mt_errors[iter] <- NA
                        mitrs[iter]     <- NA
                        mpara[[iter]]   <- param
                        next
                      }


                      mt_errors[iter]<-wxgb$CV.eval_log$Best_iteration[["mean.test.error"]]
                      mitrs[iter] <- wxgb$CV.iterations$best_iteration # having the best evaluation metric value
                      mpara[[iter]] <-param
                 }

         valid_indices <- which(!is.na(mt_errors))
    if (length(valid_indices) == 0) stop("All cross-validation iterations failed.")

        best_idx <- valid_indices[which.min(mt_errors[valid_indices])]


   return(list(nrounds=mitrs[best_idx],
               params = mpara[[best_idx]],
               min_test_errors = data.frame(min_iter=mitrs,min_test_error=mt_errors)))
 }



#' Generate randomized wXGBoost hyperparameters for tuning
#'
#' @description
#' A helper function creating a complete list of valid wXGBoost hyperparameters.
#' It combines core structural configurations, regularization parameters, and
#' tree-building criteria. By default, it sets up a diverse random search space,
#' but users can inject fixed overrides or custom sampling closures.
#'
#' @param custom_space A named list of values or functions to override defaults. The list can contain static values (e.g., \code{subsample = 0.8})
#'                     or anonymous functions that return a single value when called (e.g., \code{function() sample(3:10, 1)}).
#'                     Default \code{objective} is `binary:logistic` for binary classification; `reg:squarederror` is set for linear regression.
#'                     The default search space is defined as follows:
#'                      \preformatted{
#'                        defaults <- list(
#'                          # General Parameters
#'                          objective           = "binary:logistic",
#'                          nthread             = 1,
#'                          # Tree Booster Hyperparameters
#'                          eta                 = runif(1, 0.01, 0.3),
#'                          gamma               = runif(1, 0.0, 10.0),
#'                          max_depth           = sample(3:10, 1),
#'                          min_child_weight    = sample(1:20, 1),
#'                          max_delta_step      = 0,               # for very imbalanced case : (1:10) helps
#'                          subsample           = runif(1, 0.5, 1.0),
#'                          colsample_bytree    = runif(1, 0.5, 1.0),
#'                          colsample_bylevel   = 1.0,
#'                          colsample_bynode    = 1.0,
#'                          alpha               = runif(1, 0.0, 1.0), # L1 regularization
#'                          lambda              = runif(1, 1.0, 4.0), # L2 regularization
#'                          tree_method         = "auto",
#'                          scale_pos_weight    = 1.0,
#'                          # Random Seed
#'                          seed                = sample.int(100000, 1)
#'                          )
#'                      }
#'
#' @return A named list of parameters ready to be parsed by \code{wXGBoost()}.
#'
#'
#' @note
#' The function is encapsulated in `optim_wxgb_para()` to dynamically create a (hyper)parameter set
#' for `wXGBoost()` per iteration for optimzation.
#' This function can also be used for [xgboost::xgb.train()] or [xgboost::xgb.cv()].
#'
#' @examples
#' # Generate using default search spaces
#' para.default<-generate_wxgb_params()
#'
#' # Force a static max_depth and pass a custom eta sampler
#' custom.para<- generate_wxgb_params(list(
#'   max_depth = 6,
#'   eta = function() runif(1, 0.05, 0.15)
#' ))
#'
#' @export
generate_wxgb_params <- function(custom_space = list()) {

  # 1. Define the exhaustive default search space (Core + Tree Booster)
  defaults <- list(
    # General Parameters
    objective           = "binary:logistic",
    nthread             = 1,

    # Tree Booster Hyperparameters
    eta                 = runif(1, 0.01, 0.3),
    gamma               = runif(1, 0.0, 10.0),
    max_depth           = sample(3:10, 1),
    min_child_weight    = sample(1:20, 1),
    max_delta_step      = 0,               # for very imbalanced case : (1:10) helps
    subsample           = runif(1, 0.5, 1.0),
    colsample_bytree    = runif(1, 0.5, 1.0),
    colsample_bylevel   = 1.0,
    colsample_bynode    = 1.0,
    alpha               = runif(1, 0.0, 1.0), # L1 regularization
    lambda              = runif(1, 1.0, 4.0), # L2 regularization
    tree_method         = "auto",
    scale_pos_weight    = 1.0,

    # Random Seed
    seed                = sample.int(100000, 1)
  )

  # 2. Merge user custom space overrides into the defaults
  search_space <- modifyList(defaults, custom_space)

  # 3. Evaluate the space (executes the functions to get the actual numbers)
  params <- lapply(search_space, function(x) {
    if (is.function(x)) {
      x() # Execute user or default random function
    } else {
      x   # Return fixed value as-is
    }
  })

  return(params)
}

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.