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