R/model_generators.R

Defines functions print.cv.ranger_tune cv.ranger_tune resolve_mlr_measures default_model_generators cv_glmnet_ridge xgb_threaded_params .xgb_cv_nrounds

Documented in .xgb_cv_nrounds

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

Try the pmsims package in your browser

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

pmsims documentation built on Nov. 15, 2026, 5:07 p.m.