Nothing
#' default_model_generators Generate appropriate model based on input arguments
#'
#' @format A named list of default model generator functions grouped by outcome
#' type.
#' @return `default_models` is a list containing built-in model generators for
#' binary, continuous, and survival outcomes.
#' @keywords internal
# ---------------------------------------------------------------------------
# Internal helper: select nrounds for XGBoost via cross-validation.
#
# Uses xgb.cv with early stopping to find the optimal number of boosting
# rounds for the given data and objective. This is the XGBoost analogue of
# cv.glmnet's lambda selection: complexity adapts to sample size, which is
# critical for calibration stability at small n.
#
# @param dtrain xgb.DMatrix (training data)
# @param params list of xgb parameters (must include objective/eval_metric)
# @param nrounds_max upper bound on rounds to search (default 500)
# @param nfold number of CV folds (default 5)
# @param early_stopping_rounds stop if no improvement for this many rounds
# @return integer best nrounds (at least 1)
# @keywords internal
.xgb_cv_nrounds <- function(
dtrain,
params,
nrounds_max = 500L,
nfold = 5L,
early_stopping_rounds = 20L
) {
cv <- xgboost::xgb.cv(
params = xgb_threaded_params(params),
data = dtrain,
nrounds = nrounds_max,
nfold = nfold,
early_stopping_rounds = early_stopping_rounds,
verbose = 0,
showsd = FALSE
)
best <- cv$best_iteration
# xgboost >= 3.x reports the best iteration under cv$early_stop instead
if (is.null(best) && !is.null(cv$early_stop)) {
best <- cv$early_stop$best_iteration
}
if (is.null(best) || is.na(best) || best < 1L) {
best <- nrounds_max
}
as.integer(best)
}
# ---------------------------------------------------------------------------
# Internal helper: xgboost parameters with the thread count set.
#
# xgboost uses every core unless told otherwise. Inside a simulation that runs
# replicates in parallel, or on a busy machine, that oversubscribes the CPU so
# badly that a fit of well under a second can take minutes. Use
# pmsims_threads(), as for ranger, unless the caller set nthread. With
# subsample < 1 (the default is 0.8), the fitted model can depend on the number
# of threads: xgboost's parallel row sampling assumes one random draw per row,
# which gcc 16's libstdc++ does not guarantee.
xgb_threaded_params <- function(params) {
if (is.null(params$nthread)) {
params$nthread <- pmsims_threads()
}
params
}
# ---------------------------------------------------------------------------
# Ridge via cv.glmnet. glmnet's default alpha = 0 path ends at a lambda that
# does not fall with n, so CV can pick its end and leave the fit over-shrunk at
# any n. Then continue the path below its end, on the same folds and grid
# spacing, one block (a factor of `block` in lambda) at a time, while each
# block lowers the CV error, down to min_ratio x lambda_max. The fit returned
# is the block holding the lowest CV error, so its lambda.min is the choice.
# Far below the default path the CV curve is flat and noisy; the block after
# the best one is always fitted, so a dip inside one block does not end the
# search early. Folds are drawn as cv.glmnet draws them, so fits whose
# lambda.min is inside the default path are unchanged. `...` is passed to every
# cv.glmnet() call (e.g. cox.ties).
cv_glmnet_ridge <- function(
x,
y,
family,
nfolds = 10L,
min_ratio = 1e-9,
block = 10,
...
) {
foldid <- sample(rep(seq(nfolds), length = nrow(x)))
fit <- glmnet::cv.glmnet(
x,
y,
alpha = 0,
family = family,
foldid = foldid,
...
)
lam <- fit$lambda
if (fit$lambda.min > min(lam) || length(lam) < 2L) {
return(fit)
}
step <- log(lam[1L]) - log(lam[2L])
floor_log <- log(lam[1L] * min_ratio)
per_block <- ceiling(log(block) / step)
start_log <- log(min(lam))
best <- NULL
repeat {
path_log <- start_log - step * seq(0, per_block)
path_log <- path_log[path_log >= floor_log - 1e-8]
if (length(path_log) < 2L) {
return(best %||% fit)
}
nxt <- glmnet::cv.glmnet(
x,
y,
alpha = 0,
family = family,
foldid = foldid,
lambda = exp(path_log),
...
)
if (!is.null(best) && min(nxt$cvm) >= min(best$cvm)) {
return(best)
}
best <- nxt
start_log <- min(path_log)
}
}
# ---------------------------------------------------------------------------
default_models <- list(
binary = list(
glm = function(d) {
stats::glm("y ~ .", data = d, family = "binomial")
},
lasso = function(d) {
require_optional_packages("glmnet", "lasso models")
# expects first column y (0/1) and remaining columns predictors
d <- as.matrix(d)
x <- d[, -1, drop = FALSE]
y <- d[, 1]
glmnet::cv.glmnet(
x,
y,
alpha = 1, # L1 penalty (LASSO)
family = "binomial"
)
},
ridge = function(d) {
# Ridge logistic regression via glmnet (alpha = 0); lambda selected by CV
d <- as.matrix(d)
x <- d[, -1, drop = FALSE]
y <- d[, 1]
cv_glmnet_ridge(x, y, family = "binomial")
},
rf = function(d) {
require_optional_packages(
c("ranger"),
"random-forest models"
)
# expects column 1 = y (0/1) and remaining columns predictors
# At least one thread; see pmsims_threads().
nthreads <- pmsims_threads()
x <- d[, -1, drop = FALSE]
y <- as.factor(d[, 1])
fit_rf <- ranger::ranger(
x = x,
y = y,
mtry = max(1, floor(ncol(x) / 3)),
probability = TRUE,
num.trees = 300,
min.node.size = 15,
num.threads = nthreads
)
fit_rf$pmsims_train <- list(y = d[["y"]])
fit_rf
},
xgboost = function(
d,
params = list(
objective = "binary:logistic",
eval_metric = "logloss",
eta = 0.05,
max_depth = 4L,
subsample = 0.8,
min_child_weight = 15L
)
) {
# expects first column y (0/1), remaining columns predictors.
# nrounds is selected automatically via xgb.cv (early stopping) so that
# model complexity adapts to sample size — the analogue of cv.glmnet's
# lambda selection. Fixed nrounds = 100 caused severe over-fitting at
# small n, collapsing the calibration slope well below 1.
x <- as.matrix(d[, -1, drop = FALSE])
y <- as.numeric(d[, 1])
dtrain <- xgboost::xgb.DMatrix(
data = x,
label = y,
nthread = xgb_threaded_params(params)$nthread
)
best_nrounds <- .xgb_cv_nrounds(dtrain, params)
xgboost::xgb.train(
params = xgb_threaded_params(params),
data = dtrain,
nrounds = best_nrounds,
verbose = 0
)
}
),
continuous = list(
lm = function(d) {
stats::glm("y ~ .", data = d, family = "gaussian")
},
lasso = function(d) {
require_optional_packages("glmnet", "lasso models")
# expects first column y (numeric), remaining columns predictors
dmat <- as.matrix(d)
x <- dmat[, -1, drop = FALSE]
y <- dmat[, 1]
glmnet::cv.glmnet(
x,
y,
alpha = 1, # L1 penalty (LASSO)
family = "gaussian"
)
},
ridge = function(d) {
# Ridge regression via glmnet (alpha = 0); lambda selected by CV
dmat <- as.matrix(d)
x <- dmat[, -1, drop = FALSE]
y <- dmat[, 1]
cv_glmnet_ridge(x, y, family = "gaussian")
},
rf = function(d) {
require_optional_packages(
c("ranger"),
"random-forest models"
)
# expects first column y (numeric), remaining columns predictors
# At least one thread; see pmsims_threads().
nthreads <- pmsims_threads()
x <- d[, -1, drop = FALSE]
y <- d[, 1]
ranger::ranger(
x = x,
y = y,
mtry = max(1, floor(ncol(x) / 3)),
num.trees = 300L,
num.threads = nthreads
)
},
xgboost = function(
d,
params = list(
objective = "reg:squarederror",
eval_metric = "rmse",
eta = 0.05,
max_depth = 4L,
subsample = 0.8,
min_child_weight = 5L
)
) {
# expects first column y (numeric), remaining columns predictors.
# nrounds is selected via xgb.cv early stopping (see .xgb_cv_nrounds).
# This is essential for continuous calibration slope stability: fixed
# nrounds = 100 led to over-dispersed predictions at small n (slope << 1)
# because XGBoost memorises training-scale variation without regularisation
# on the number of rounds.
x <- as.matrix(d[, -1, drop = FALSE])
y <- as.numeric(d[, 1])
dtrain <- xgboost::xgb.DMatrix(
data = x,
label = y,
nthread = xgb_threaded_params(params)$nthread
)
best_nrounds <- .xgb_cv_nrounds(dtrain, params)
xgboost::xgb.train(
params = xgb_threaded_params(params),
data = dtrain,
nrounds = best_nrounds,
verbose = 0
)
}
),
survival = list(
coxph = function(d) {
# expects columns named 'time' and 'event' and remaining columns predictors
formula <- stats::as.formula("survival::Surv(time, event) ~ .")
survival::coxph(formula, data = d)
},
lasso = function(d) {
require_optional_packages("glmnet", "lasso models")
# glmnet with 'cox' family: predictors as matrix, response as Surv(time, event)
# Remove time/event from predictors
stopifnot(all(c("time", "event") %in% colnames(d)))
x <- as.matrix(d[,
setdiff(colnames(d), c("time", "event")),
drop = FALSE
])
y <- survival::Surv(d$time, d$event)
# Breslow ties, glmnet's default, set explicitly: glmnet >= 5.0 warns on
# every Cox fit without it and plans to change the default to Efron.
glmnet::cv.glmnet(x, y, alpha = 1, family = "cox", cox.ties = "breslow") # L1 (LASSO)
},
ridge = function(d) {
# Ridge Cox regression via glmnet (alpha = 0); lambda selected by CV
stopifnot(all(c("time", "event") %in% colnames(d)))
x <- as.matrix(d[,
setdiff(colnames(d), c("time", "event")),
drop = FALSE
])
y <- survival::Surv(d$time, d$event)
cv_glmnet_ridge(x, y, family = "cox", cox.ties = "breslow")
},
rf = function(d) {
require_optional_packages(
c("ranger"),
"random-forest models"
)
# ranger survival forest via the x/y interface. The formula interface
# materialises a model frame that is prohibitively large at the sample
# sizes the search reaches, hence save.memory / keep.inbag = FALSE.
stopifnot(all(c("time", "event") %in% colnames(d)))
x <- d[, !(names(d) %in% c("time", "event")), drop = FALSE]
y <- survival::Surv(d$time, d$event)
fit_rf <- ranger::ranger(
x = x,
y = y,
num.trees = 300,
min.node.size = 30,
mtry = max(1, floor(ncol(x) / 3)),
importance = "none",
save.memory = TRUE,
keep.inbag = FALSE,
num.threads = pmsims_threads(),
write.forest = TRUE
)
# Carries the training outcome for the out-of-bag recalibration map
# fitted in rf_recal_survival() (see R/metric_generators.R).
fit_rf$pmsims_train <- list(time = d$time, event = d$event)
fit_rf
},
xgboost = function(
d,
params = list(
objective = "survival:cox",
eval_metric = "cox-nloglik",
eta = 0.05,
max_depth = 4L,
subsample = 0.8,
min_child_weight = 15L
)
) {
# XGBoost Cox objective: censoring is encoded in the sign of the label
# (see below), which is the encoding survival:cox actually expects.
# nrounds is selected via xgb.cv early stopping (see .xgb_cv_nrounds),
# which prevents over-fitting the training hazard at small sample sizes
# and stabilises the calibration slope toward 1 at moderate n.
stopifnot(all(c("time", "event") %in% colnames(d)))
x <- as.matrix(d[,
setdiff(colnames(d), c("time", "event")),
drop = FALSE
])
label_time <- as.numeric(d$time)
# survival:cox expects censoring encoded in the sign of the label:
# +t for an observed event, -t for a censored observation. The earlier
# label = time / weight = event encoding silently down-weighted censored
# rows to zero instead of treating them as censored.
lab <- ifelse(d$event == 1, label_time, -label_time)
dtrain <- xgboost::xgb.DMatrix(
data = x,
label = lab,
nthread = xgb_threaded_params(params)$nthread
)
best_nrounds <- .xgb_cv_nrounds(dtrain, params)
xgboost::xgb.train(
params = xgb_threaded_params(params),
data = dtrain,
nrounds = best_nrounds,
verbose = 0
)
}
)
)
#' @keywords internal
#' @noRd
default_model_generators <- function(outcome, model) {
if (!outcome %in% names(default_models)) {
stop(paste0("Outcome \"", outcome, "\" not found."))
}
if (!model %in% names(default_models[[outcome]])) {
stop(paste0(
"Model \"",
model,
"\" not found for outcome \"",
outcome,
"\""
))
}
model_function <- default_models[[outcome]][[model]]
attr(model_function, "model") <- model
return(model_function)
}
#' @keywords internal
#' @noRd
resolve_mlr_measures <- function(measure_names, task_type = NA_character_) {
require_optional_packages("mlr", "mlr measure lookup")
mlr_attached <- "package:mlr" %in% search()
if (!mlr_attached) {
base::attachNamespace(asNamespace("mlr"))
on.exit(
{
if ("package:mlr" %in% search()) {
detach("package:mlr", unload = FALSE, character.only = TRUE)
}
},
add = TRUE
)
}
available_measures <- mlr::listMeasures(task_type, create = TRUE)
available_ids <- vapply(available_measures, function(x) x$id, character(1))
lapply(measure_names, function(measure_name) {
measure_index <- match(measure_name, available_ids)
if (is.na(measure_index)) {
stop("Unknown mlr measure: ", measure_name, call. = FALSE)
}
available_measures[[measure_index]]
})
}
#' @keywords internal
#' @noRd
cv.ranger_tune <- function(
data,
formula,
type = c("regression", "classification", "survival"),
tune.parameters = c("mtry", "min.node.size"),
num.trees = 1000,
iters = 70,
iters.warmup = 30,
time.budget = NULL,
num.threads = parallel::detectCores() - 1,
measure = NULL,
build.final.model = TRUE,
show.info = TRUE,
seed = 123,
...
) {
# Dependencies
require_optional_packages(
c("tuneRanger", "mlr", "ranger"),
"ranger tuning"
)
type <- match.arg(type)
set.seed(seed)
# Build the mlr task.
# For survival, expect Surv(time, status) ~ .
if (type == "survival") {
# extract Surv var names from formula LHS
lhs <- formula[[2]]
surv_vars <- all.vars(lhs)
if (length(surv_vars) < 2) {
stop("For survival, specify Surv(time, status) on LHS of formula.")
}
time_col <- surv_vars[1]
status_col <- surv_vars[2]
task <- mlr::makeSurvTask(data = data, target = c(time_col, status_col))
} else {
resp <- all.vars(formula)[1]
if (type == "classification") {
if (!is.factor(data[[resp]])) {
warning("Converting response to factor for classification.")
data[[resp]] <- as.factor(data[[resp]])
}
task <- mlr::makeClassifTask(data = data, target = resp)
} else {
if (!is.numeric(data[[resp]])) {
warning("Regression target is not numeric.")
}
task <- mlr::makeRegrTask(data = data, target = resp)
}
}
# tuneRanger expects a list of mlr measure objects.
if (is.null(measure)) {
if (type == "regression") {
measure_obj <- list(mlr::mse)
} else if (type == "classification") {
# binary -> AUC, multiclass -> mmce (misclassification) or acc
if (length(task$task.desc$class.levels) == 2) {
measure_obj <- list(mlr::auc)
} else {
measure_obj <- list(mlr::acc)
}
} else {
# survival
measure_obj <- list(mlr::cindex)
}
} else {
# allow measure to be character, mlr measure object, or list
if (is.character(measure)) {
task_type <- switch(
type,
regression = "regr",
classification = "classif",
survival = "surv"
)
measure_obj <- resolve_mlr_measures(measure, task_type = task_type)
} else if (inherits(measure, "Measure")) {
measure_obj <- list(measure)
} else if (
is.list(measure) &&
all(sapply(measure, function(x) inherits(x, "Measure")))
) {
measure_obj <- measure
} else {
stop(
"`measure` must be NULL, a character name, an mlr::Measure, or a list of Measures."
)
}
}
# Call tuneRanger.
tune_args <- list(
task = task,
measure = measure_obj,
iters = iters,
iters.warmup = iters.warmup,
time.budget = time.budget,
num.threads = num.threads,
num.trees = num.trees,
parameters = list(),
tune.parameters = tune.parameters,
save.file.path = NULL,
build.final.model = build.final.model,
show.info = show.info
)
# Merge extra arguments.
extra_args <- list(...)
if (length(extra_args) > 0) {
tune_args <- c(tune_args, extra_args)
}
tune_res <- do.call(tuneRanger::tuneRanger, tune_args)
# Tidy the output.
out <- list(
recommended.pars = tune_res$recommended.pars,
results = tune_res$results,
measure = sapply(measure_obj, function(m) m$id)
)
if (build.final.model && !is.null(tune_res$model)) {
out$model <- tune_res$model
}
class(out) <- c("cv.ranger_tune", class(out))
return(out)
}
# Print method
#' @export
#' @keywords internal
#' @noRd
print.cv.ranger_tune <- function(x, ...) {
cat("tuneRanger results\n")
cat("-------------------\n")
cat("Optimized measure(s):", paste(x$measure, collapse = ", "), "\n\n")
cat("Recommended parameters:\n")
print(x$recommended.pars)
cat("\nTop tuning results (first 6 rows):\n")
print(utils::head(x$results))
if (!is.null(x$model)) {
cat("\nFinal model attached as $model\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.