R/simulate_wrappers.R

Defines functions secondary_metric_at simulate_survival simulate_continuous simulate_binary resolve_n_reps_total make_data_args get_param call_tuner resolve_data_control

Documented in simulate_binary simulate_continuous simulate_survival

# =============================================================================
# Internal wrappers shared by simulate_binary(), simulate_continuous() and
# simulate_survival().
#
# These helpers translate the user-facing `complexity` + `data_control`
# interface into the arguments expected by (a) the tuning functions and
# (b) the data generators, keeping the two consistent. Validation lives in
# input_validation.R (validate_complexity(), validate_data_control()).
# =============================================================================

#' Resolve a `data_control` list into generator/tuner arguments
#'
#' Validates `data_control` and maps the
#' user-facing `predictor_distribution` onto the generator's internal
#' `predictor_type` + `distribution` + `binary_prevalence`:
#' `"binary"` selects binary predictors (with the supplied prevalence); any
#' other value selects continuous predictors drawn from that family.
#'
#' @param data_control A named list or `NULL`.
#' @param complexity A single value in 1:4.
#' @return A list with `nonlinear_strength`, `correlation`, `predictor_type`,
#'   `distribution`, `binary_prevalence`, and the original
#'   `predictor_distribution` (for reporting). Also returns the *effective*
#'   values the generator will actually use — `effective_distribution` and
#'   `effective_nonlinear_strength` — which differ from the requested ones
#'   wherever the generator substitutes a complexity-level default (C4 swaps a
#'   left-at-default `"normal"` for the Friedman-canonical `"uniform"`, and an
#'   unset `nonlinear_strength` picks up the per-complexity default). These are
#'   what the wrappers record and print, so that the reported configuration
#'   describes the data that were simulated.
#' @keywords internal
#' @noRd
resolve_data_control <- function(data_control, complexity) {
  validate_data_control(data_control, complexity)

  ctrl <- utils::modifyList(
    list(
      nonlinear_strength = NULL,
      correlation = 0.3,
      predictor_distribution = "normal",
      binary_predictor_prevalence = NULL
    ),
    if (is.null(data_control)) list() else data_control
  )

  if (identical(ctrl$predictor_distribution, "binary")) {
    predictor_type <- "binary"
    distribution <- "normal" # ignored by the generator for binary predictors
    binary_prevalence <- ctrl$binary_predictor_prevalence
  } else {
    predictor_type <- "continuous"
    distribution <- ctrl$predictor_distribution
    binary_prevalence <- 0
  }

  list(
    nonlinear_strength = ctrl$nonlinear_strength,
    correlation = ctrl$correlation,
    predictor_type = predictor_type,
    distribution = distribution,
    binary_prevalence = binary_prevalence,
    predictor_distribution = ctrl$predictor_distribution,
    # Resolved through the same helpers the generator uses, so the reported
    # configuration cannot drift from the simulated configuration.
    effective_distribution = resolve_family(
      complexity = complexity,
      predictor_type = predictor_type,
      distribution = distribution,
      binary_prevalence = binary_prevalence
    ),
    effective_nonlinear_strength = resolve_nonlinear_strength(
      nonlinear_strength = ctrl$nonlinear_strength,
      complexity = complexity
    )
  )
}

#' Call a tuning function with only the data-config arguments it accepts
#'
#' The tuner must build its unit linear predictor with the *same* data-
#' generating configuration that will be used to simulate data, otherwise the
#' tuned effect size will not recover the requested performance. This helper
#' passes `complexity`, `nonlinear_strength`, `correlation`, `distribution`,
#' `predictor_type` and `binary_prevalence` to the tuner, silently dropping any
#' the tuner does not declare (so it works across the supported tuner
#' signatures). If a non-default `nonlinear_strength` cannot be passed,
#' a warning is raised because C2/C3 tuning would then be inconsistent with the
#' generated data.
#'
#' @param tuner A tuning function (e.g. `binary_tuning`).
#' @param required A named list of the tuner's required arguments. Must include
#'   `.complexity`, which is forwarded as `complexity`.
#' @param dc The list returned by `resolve_data_control()`.
#' @return The tuner's return value.
#' @keywords internal
#' @noRd
call_tuner <- function(tuner, required, dc) {
  fmls <- names(formals(tuner))
  complexity <- required$.complexity
  required$.complexity <- NULL

  data_config <- list(
    complexity = complexity,
    nonlinear_strength = dc$nonlinear_strength,
    correlation = dc$correlation,
    distribution = dc$distribution,
    predictor_type = dc$predictor_type,
    binary_prevalence = dc$binary_prevalence
  )

  if (!is.null(dc$nonlinear_strength) && !("nonlinear_strength" %in% fmls)) {
    warning(
      "The tuning function does not accept `nonlinear_strength`; the tuned ",
      "effect size may not match the generated data for complexity 2/3. ",
      "Update the tuner to the `nonlinear_strength` interface.",
      call. = FALSE
    )
  }

  optional <- data_config[names(data_config) %in% fmls]
  do.call(tuner, c(required, optional))
}

#' Extract a named element from a tuning result, with a scalar fallback
#'
#' @param tp A tuning result (named vector/list, or a bare scalar).
#' @param name The element to extract (e.g. `"beta_signal"`, `"mu_lp"`).
#' @keywords internal
#' @noRd
get_param <- function(tp, name) {
  if (!is.null(names(tp)) && name %in% names(tp)) {
    return(unname(tp[[name]]))
  }
  if (name == "beta_signal") {
    return(unname(tp[[1]])) # continuous_tuning may return a scalar
  }
  stop("Tuning result is missing `", name, "`.", call. = FALSE)
}

#' Assemble the generator argument list for a data_spec
#'
#' Uses the generators' real formal names. `nonlinear_strength` is included
#' only when non-`NULL`: `default_data_generators()` bakes args via
#' `formals(fn)[[key]] <- value`, and assigning `NULL` would *delete* the
#' formal rather than leave its default, so a `NULL` entry must be omitted.
#'
#' @keywords internal
#' @noRd
make_data_args <- function(
  signal_parameters,
  noise_parameters,
  complexity,
  dc,
  extra = list()
) {
  args <- c(
    list(
      n_signal_parameters = signal_parameters,
      noise_parameters = noise_parameters,
      complexity = complexity,
      predictor_type = dc$predictor_type,
      binary_prevalence = dc$binary_prevalence,
      correlation = dc$correlation,
      distribution = dc$distribution
    ),
    extra
  )
  if (!is.null(dc$nonlinear_strength)) {
    args$nonlinear_strength <- dc$nonlinear_strength
  }
  args
}


# Models for which the simulation budget is raised at small signal sizes.
# These are the directly-fitted learners -- one per outcome type -- i.e. the
# complement of `ml_model_families` in R/csse_internal.R. They are cheap enough
# per replication that the extra budget costs little, and they are the ones for
# which the Gaussian-process stage is budget-limited rather than
# design-limited at small p. The rule applies to method = "mlpwr" only.
budget_boost_models <- c("lm", "glm", "coxph")

#' Resolve the simulation budget shared by the outcome-specific wrappers
#'
#' With `method = "mlpwr"`, raises `n_reps_total` to `boost_to` for designs
#' that sit in the regime where the second-stage Gaussian-process search
#' is limited by simulation budget
#' rather than by the design itself: few signal parameters, fitted with one of
#' the directly-fitted models in `budget_boost_models`. In that regime the
#' spread of `min_n` across repeat runs falls roughly with the budget, so the
#' default of 1000 leaves avoidable run-to-run variability on the table.
#'
#' The rule only ever increases the budget: a caller who asks for more than
#' `boost_to` keeps their value. A caller who deliberately wants a smaller,
#' faster run can switch the rule off with `auto_n_reps_total = FALSE`. When the
#' budget is changed a message says so, so the figure reported in the result is
#' never a surprise.
#'
#' Inputs that are not usable (missing, non-numeric, length != 1) are passed
#' through untouched, leaving the wrappers' own validation to report them.
#'
#' @param n_reps_total The requested total number of simulation replications.
#' @param signal_parameters Number of signal predictors in the design.
#' @param model The resolved model string (after `check_pmsims_args()`).
#' @param method The search engine passed to [simulate_custom()]. The rule
#'   applies to `"mlpwr"` only; `NULL` means the default engine (`"curve"`).
#' @param auto Logical; `FALSE` disables the rule entirely.
#' @param boost_to The budget to raise to. Default `2000`.
#' @param max_signal_parameters The rule applies at or below this many signal
#'   parameters. Default `10`.
#' @param models Character vector of models the rule applies to.
#' @return A single number: the budget the wrapper should use.
#' @keywords internal
#' @noRd
resolve_n_reps_total <- function(
  n_reps_total,
  signal_parameters,
  model,
  method = NULL,
  auto = TRUE,
  boost_to = 2000,
  max_signal_parameters = 10,
  models = budget_boost_models
) {
  if (!isTRUE(auto) || !identical(method, "mlpwr")) {
    return(n_reps_total)
  }

  usable <- function(x) is.numeric(x) && length(x) == 1L && is.finite(x)
  if (!usable(n_reps_total) || !usable(signal_parameters)) {
    return(n_reps_total)
  }
  if (!(is.character(model) && length(model) == 1L && model %in% models)) {
    return(n_reps_total)
  }
  if (signal_parameters > max_signal_parameters) {
    return(n_reps_total)
  }
  # Only ever increase.
  if (n_reps_total >= boost_to) {
    return(n_reps_total)
  }

  message(sprintf(
    paste0(
      "n_reps_total raised from %s to %s: with %s signal parameters and ",
      "model \"%s\", the search is budget-limited at the default. ",
      "Set auto_n_reps_total = FALSE to keep %s."
    ),
    format(n_reps_total, scientific = FALSE),
    format(boost_to, scientific = FALSE),
    format(signal_parameters, scientific = FALSE),
    model,
    format(n_reps_total, scientific = FALSE)
  ))

  boost_to
}

#' Minimum sample size for binary-outcome prediction models
#'
#' Compute the minimum sample size required to develop a prediction model with a
#' binary outcome. The function wraps a simulation-based search that, by
#' default, fits a learning curve to every simulated replicate and simulates
#' further where the curve crosses the target (`method = "curve"`; see
#' [simulate_custom()]); `method = "mlpwr"` selects the Gaussian-process
#' search of earlier versions. From user inputs
#' (outcome prevalence, maximum achievable performance, target performance, etc.) it
#' constructs a data-generating function, a model-fitting
#' function, and a metric function, then searches for the smallest \eqn{n} that
#' meets the chosen performance criterion.
#'
#' @section Criteria:
#' Two formulations are supported.
#'
#' - **Mean-based**: find the smallest \eqn{n} such that the expected model
#'   performance exceeds the target \eqn{M^*}, i.e.
#'   \deqn{\min_n \; \mathbb{E}_{D_n}\{ M \mid D_n \} \ge M^*.}
#'
#' - **Assurance-based**: find the smallest \eqn{n} such that the probability
#'   the performance exceeds \eqn{M^*} is at least \eqn{\delta} (e.g. 0.80),
#'   i.e.
#'   \deqn{\min_n \; \mathbb{P}_{D_n}\!\left( M \mid D_n \ge M^* \right) \ge \delta.}
#'
#' Here, \eqn{M} is the chosen performance metric and the probability/expectation
#' is over repeated samples of training data of size \eqn{n}. The assurance
#' criterion explicitly accounts for variability across training sets; models
#' with higher variance typically require larger \eqn{n} to satisfy it.
#'
#' @section Data control:
#' `complexity` selects the signal structure of the data-generating mechanism:
#' `1` purely linear, `2` linear + quadratic, `3` linear + quadratic +
#' interaction, `4` the Friedman function. The Friedman function uses five
#' predictors, so complexity 4 requires exactly five signal predictors
#' (`signal_parameters = 5`) and stops with an error otherwise; any number of
#' noise predictors can be added. `data_control` is an optional list fine-tuning
#' the predictors:
#' \describe{
#'   \item{`nonlinear_strength`}{Numeric in `[0, 1)`. Fraction of the signal
#'     variance carried by the nonlinear, linearly-inaccessible component.
#'     Applies to complexity 2 and 3 only; ignored (with a warning) for 1 and 4.
#'     If omitted, the generator's per-complexity default is used.}
#'   \item{`correlation`}{Numeric in \eqn{[-1, 1]}. Pairwise correlation among the
#'     candidate predictors, induced through a Gaussian copula. Default `0.3`.
#'     This is the correlation of the underlying normal variables: for
#'     `"normal"` predictors it is also the observed correlation, but for other
#'     distributions the observed correlation is lower. For example, binary
#'     predictors with prevalence 0.3 correlate at about 0.18 when
#'     `correlation = 0.3`.}
#'   \item{`predictor_distribution`}{One of `"normal"`, `"uniform"`, `"binary"`,
#'     `"exponential"`, `"lognormal"`, `"t"`, `"laplace"`. `"binary"` selects
#'     0/1 predictors and requires `binary_predictor_prevalence`; any other
#'     value selects continuous predictors from that family. Default `"normal"`.}
#'   \item{`binary_predictor_prevalence`}{Numeric in `(0, 1)`. Prevalence of the
#'     binary predictors; required when `predictor_distribution = "binary"`,
#'     ignored (with a warning) otherwise. Note: binary predictors are
#'     incompatible with complexity 2/3 because squaring a 0/1 variable returns
#'     itself.}
#' }
#'
#' @param signal_parameters Integer. Number of candidate predictors associated
#'   with the outcome (i.e., true signal features).
#' @param noise_parameters Integer. Number of candidate predictors not
#'   associated with the outcome (noise features). Default is 0.
#' @param complexity Integer in 1:4 selecting the data-generating signal
#'   structure (see *Data control*). Default `1`. Complexity 4 requires
#'   `signal_parameters = 5`.
#' @param data_control Optional named list controlling the predictors (see
#'   *Data control*). Default `NULL` (generator defaults).
#' @param outcome_prevalence Numeric in (0, 1). Target prevalence of the binary
#'   outcome in the intended modelling context.
#' @param maximum_achievable_cstatistic Numeric in (0, 1). Maximum achievable
#'   C-statistic with effectively unlimited data. This is used to calibrate the
#'   data-generating mechanism and is not the minimum acceptable threshold.
#' @param model Character string specifying the modelling algorithm. One of
#'   `"glm"` (logistic regression), `"lasso"`, `"ridge"`, `"rf"` (random
#'   forest), or `"xgboost"` (gradient-boosted trees).
#' @param metric Character string naming the performance metric used to assess
#'   the sample size; defaults to `"calibration_slope"`. Metric identifiers use
#'   one canonical form throughout the package: `"calibration_slope"`,
#'   `"auc"`, `"r2"`, `"cindex"` and `"csse"`. Metrics where smaller is better,
#'   such as `"calibration_in_the_large"`, cannot be used as search targets.
#'
#'   `"calibration_slope"` is the slope from regressing the observed outcome on
#'   the model's linear predictor in held-out data; 1 indicates perfect
#'   calibration, and values below 1 indicate overfitting. Note that for the
#'   machine-learning models (`"lasso"`, `"ridge"`, `"rf"`, `"xgboost"`) this is
#'   converted internally to the calibration slope squared error for
#'   optimisation and translated back before results are returned; you don't
#'   need to do anything, and `target_performance` is still given on the
#'   calibration slope scale. Results derived this way carry a footnote marker
#'   in the printed output.
#'
#'   `"csse"` is the calibration slope squared error, \eqn{-(1 - s)^2} for a
#'   calibration slope \eqn{s}, so that larger is better and 0 is perfect
#'   calibration. It can be requested directly, which is mainly useful for
#'   advanced use and for comparison against the internal conversion described
#'   above. When requesting it directly you are responsible for supplying
#'   `target_performance` on the CSSE scale: a calibration slope target of
#'   `0.9` corresponds to a CSSE target of `-0.01`. No adjustment is applied on
#'   your behalf, and results are reported on the CSSE scale.
#' @param target_performance Numeric. Minimum acceptable value of the selected
#'   performance metric \eqn{M^*}; the algorithm searches for the smallest
#'   \eqn{n} meeting the chosen criterion with respect to this threshold.
#' @param n_reps_total Integer. Total number of simulation replications used by
#'   the engine across the search.
#' @param mean_or_assurance Character string, either `"mean"` or `"assurance"`.
#'   Controls whether the minimum \eqn{n} is defined by the mean-based criterion
#'   or the assurance-based criterion (with the assurance level \eqn{\delta}
#'   controlled by the engine's defaults or additional arguments in `...`).
#' @param auto_n_reps_total Logical. When `TRUE` (default) and
#'   `method = "mlpwr"`, `n_reps_total` is raised to 2000 for designs with at
#'   most 10 signal parameters fitted with `"lm"`, `"glm"` or `"coxph"`, where
#'   the Gaussian-process search is limited by simulation budget rather than
#'   by the design. It has no effect with the default `method = "curve"`. The rule only ever increases the budget,
#'   and reports the change with a message. Set `FALSE` to use `n_reps_total`
#'   exactly as supplied.
#' @param ... Additional options passed to [simulate_custom()] (e.g., assurance
#'   level \eqn{\delta}, per-iteration settings).
#'
#' @return An object of class `"pmsims"` containing the estimated minimum sample
#'   size and simulation diagnostics (inputs, fitted GP curve, intermediate
#'   evaluations, and summary metrics).
#'
#' @seealso [simulate_continuous()], [simulate_survival()], [simulate_custom()]
#'
#' @examples
#' \donttest{
#' set.seed(123)
#' est <- simulate_binary(
#'   signal_parameters = 3,
#'   noise_parameters = 0,
#'   complexity = 1,
#'   data_control = list(correlation = 0),
#'   outcome_prevalence = 0.50,
#'   maximum_achievable_cstatistic = 0.80,
#'   model = "glm",
#'   metric = "calibration_slope",
#'   target_performance = 0.9,
#'   mean_or_assurance = "assurance",
#'   min_sample_size = 50,
#'   max_sample_size = 1000,
#'   n_reps_total = 1000,
#'   auto_n_reps_total = FALSE,
#'   test_n = 30000,
#'   progress = FALSE
#' )
#' est
#' est$min_n
#' plot(est)
#' }
#' @export
simulate_binary <- function(
  # Predictors
  signal_parameters,
  noise_parameters = 0,
  complexity = 1,
  data_control = NULL,
  # Outcome
  outcome_prevalence,
  # Performance
  maximum_achievable_cstatistic,
  # Model
  model = c("glm", "lasso", "ridge", "rf", "xgboost"),
  metric = "calibration_slope",
  target_performance,
  # Engine
  n_reps_total = 1000,
  mean_or_assurance = "assurance",
  auto_n_reps_total = TRUE,
  ...
) {
  model <- check_pmsims_args(model, c("glm", "lasso", "ridge", "rf", "xgboost"))
  validate_metric_constraints(
    metric = metric,
    target_performance = target_performance,
    maximum_achievable_performance = maximum_achievable_cstatistic
  )
  # Machine learning models search on the CSSE scale internally; see
  # R/csse_internal.R.
  csse_plan <- plan_internal_csse(metric, model, target_performance)
  validate_complexity(complexity, signal_parameters)
  validate_outcome_prevalence(outcome_prevalence)
  dc <- resolve_data_control(data_control, complexity)

  # Shared budget rule; see resolve_n_reps_total(). Applied after validation so
  # that bad inputs are still reported by the checks above, and before the
  # engine call so that output$n_reps_total records what was actually used.
  n_reps_total <- resolve_n_reps_total(
    n_reps_total = n_reps_total,
    signal_parameters = signal_parameters,
    model = model,
    method = list(...)$method,
    auto = auto_n_reps_total
  )

  candidate_features <- signal_parameters + noise_parameters
  proportion_noise_features <- noise_parameters / candidate_features

  # Tune the data-generating function under the SAME data configuration.
  tune_param <- call_tuner(
    binary_tuning,
    required = list(
      target_prevalence = outcome_prevalence,
      target_performance = maximum_achievable_cstatistic,
      candidate_features = candidate_features,
      proportion_noise_features = proportion_noise_features,
      .complexity = complexity
    ),
    dc = dc
  )

  data_spec <- list(
    type = "binary",
    args = make_data_args(
      signal_parameters,
      noise_parameters,
      complexity,
      dc,
      extra = list(
        mu_lp = get_param(tune_param, "mu_lp"),
        beta_signal = get_param(tune_param, "beta_signal"),
        baseline_prob = outcome_prevalence
      )
    )
  )

  data_function <- default_data_generators(data_spec)
  outcome_type <- attr(data_function, "outcome")
  model_function <- default_model_generators(outcome_type, model)

  simulate_custom_args <- utils::modifyList(
    list(
      metric_function = describe_as_calibration_slope(
        default_metric_generator(csse_plan$metric, data_function),
        csse_plan
      ),
      target_performance = csse_plan$target_performance,
      c_statistic = maximum_achievable_cstatistic,
      data_function = data_function,
      model_function = model_function,
      n_reps_total = n_reps_total,
      n_reps_per = 20,
      method = "curve",
      mean_or_assurance = mean_or_assurance,
      test_n = 30000
    ),
    list(...)
  )

  output <- do.call(simulate_custom, simulate_custom_args)

  # Put any internally-converted results back on the calibration slope scale.
  output <- restore_calibration_slope_scale(output, csse_plan)

  metric_2 <- if (metric %in% c("csse", "calibration_slope")) {
    "auc"
  } else {
    "calibration_slope"
  }

  metric_function_2 <- default_metric_generator(metric_2, data_function)

  metric_2_at_n <- secondary_metric_at(output, metric_function_2)

  output$metric_2_at_n <- metric_2_at_n
  output$metric_2 <- metric_2

  output$signal_parameters <- signal_parameters
  output$noise_parameters <- noise_parameters
  output$complexity <- complexity
  # Effective, not requested: see resolve_data_control().
  output$nonlinear_strength <- dc$effective_nonlinear_strength
  output$correlation <- dc$correlation
  output$predictor_distribution <- dc$effective_distribution
  output$predictor_type <- dc$predictor_type
  output$binary_predictor_prevalence <- dc$binary_prevalence
  output$outcome_prevalence <- outcome_prevalence
  output$maximum_achievable_cstatistic <- maximum_achievable_cstatistic
  output$model <- model
  output$metric <- metric
  output$n_reps_total <- n_reps_total
  output$mean_or_assurance <- mean_or_assurance
  est <- output
  class(est) <- "pmsims"
  est
}

#' Minimum sample size for continuous‐outcome prediction models
#'
#' Compute the minimum sample size required to develop a prediction model with a
#' **continuous** outcome. This wraps the same simulation engine as
#' [simulate_binary()]: by default a learning curve fitted to every simulated
#' replicate (`method = "curve"`), or the Gaussian-process search with
#' `method = "mlpwr"`. From user inputs (maximum achievable performance, target
#' performance, etc.) it constructs a
#' data-generating function, model-fitting function, and metric function, then
#' searches for the smallest \eqn{n} meeting the chosen criterion.
#'
#' @inheritSection simulate_binary Criteria
#' @inheritSection simulate_binary Data control
#'
#' @inheritParams simulate_binary
#' @param maximum_achievable_rsquared Numeric in (0, 1). Maximum achievable
#'   \eqn{R^2} with effectively unlimited data. This is used to calibrate the
#'   data-generating mechanism and is not the minimum acceptable threshold.
#' @param model Character string specifying the modelling algorithm. One of
#'   `"lm"` (linear regression), `"lasso"`, `"ridge"`, `"rf"` (random forest),
#'   or `"xgboost"` (gradient-boosted trees).
#'
#' @return An object of class `"pmsims"` containing the estimated minimum sample
#'   size and simulation diagnostics (inputs, fitted GP curve, intermediate
#'   evaluations, and summary metrics).
#'
#' @seealso [simulate_binary()], [simulate_survival()], [simulate_custom()]
#'
#' @examples
#' \donttest{
#' set.seed(123)
#' est <- simulate_continuous(
#'   signal_parameters = 3,
#'   noise_parameters = 0,
#'   complexity = 1,
#'   data_control = list(correlation = 0),
#'   maximum_achievable_rsquared = 0.50,
#'   model = "lm",
#'   metric = "calibration_slope",
#'   target_performance = 0.9,
#'   mean_or_assurance = "assurance",
#'   min_sample_size = 50,
#'   max_sample_size = 1000,
#'   n_reps_total = 1000,
#'   auto_n_reps_total = FALSE,
#'   test_n = 30000,
#'   progress = FALSE
#' )
#' est
#' est$min_n
#' plot(est)
#' }
#' @export
simulate_continuous <- function(
  signal_parameters,
  noise_parameters = 0,
  complexity = 1,
  data_control = NULL,
  maximum_achievable_rsquared,
  model = c("lm", "lasso", "ridge", "rf", "xgboost"),
  metric = "calibration_slope",
  target_performance,
  n_reps_total = 1000,
  mean_or_assurance = "assurance",
  auto_n_reps_total = TRUE,
  ...
) {
  model <- check_pmsims_args(model, c("lm", "lasso", "ridge", "rf", "xgboost"))
  validate_metric_constraints(
    metric = metric,
    target_performance = target_performance,
    maximum_achievable_performance = maximum_achievable_rsquared
  )
  # Machine learning models search on the CSSE scale internally; see
  # R/csse_internal.R.
  csse_plan <- plan_internal_csse(metric, model, target_performance)
  validate_complexity(complexity, signal_parameters)
  dc <- resolve_data_control(data_control, complexity)

  # Shared budget rule; see resolve_n_reps_total(). Applied after validation so
  # that bad inputs are still reported by the checks above, and before the
  # engine call so that output$n_reps_total records what was actually used.
  n_reps_total <- resolve_n_reps_total(
    n_reps_total = n_reps_total,
    signal_parameters = signal_parameters,
    model = model,
    method = list(...)$method,
    auto = auto_n_reps_total
  )

  candidate_features <- signal_parameters + noise_parameters
  proportion_noise_features <- noise_parameters / candidate_features

  # Tune the data-generating function under the SAME data configuration.
  tune_param <- call_tuner(
    continuous_tuning,
    required = list(
      r2 = maximum_achievable_rsquared,
      candidate_features = candidate_features,
      proportion_noise_features = proportion_noise_features,
      .complexity = complexity
    ),
    dc = dc
  )

  data_spec <- list(
    type = "continuous",
    args = make_data_args(
      signal_parameters,
      noise_parameters,
      complexity,
      dc,
      extra = list(beta_signal = get_param(tune_param, "beta_signal"))
    )
  )

  data_function <- default_data_generators(data_spec)
  outcome_type <- attr(data_function, "outcome")
  model_function <- default_model_generators(outcome_type, model)

  simulate_custom_args <- utils::modifyList(
    list(
      metric_function = describe_as_calibration_slope(
        default_metric_generator(csse_plan$metric, data_function),
        csse_plan
      ),
      target_performance = csse_plan$target_performance,
      c_statistic = maximum_achievable_rsquared,
      data_function = data_function,
      model_function = model_function,
      n_reps_total = n_reps_total,
      n_reps_per = 20,
      method = "curve",
      mean_or_assurance = mean_or_assurance,
      test_n = 30000
    ),
    list(...)
  )

  output <- do.call(simulate_custom, simulate_custom_args)

  # Put any internally-converted results back on the calibration slope scale.
  output <- restore_calibration_slope_scale(output, csse_plan)

  metric_2 <- if (metric %in% c("csse", "calibration_slope")) {
    "r2"
  } else {
    "calibration_slope"
  }

  metric_function_2 <- default_metric_generator(metric_2, data_function)

  metric_2_at_n <- secondary_metric_at(output, metric_function_2)

  output$metric_2_at_n <- metric_2_at_n
  output$metric_2 <- metric_2

  output$signal_parameters <- signal_parameters
  output$noise_parameters <- noise_parameters
  output$complexity <- complexity
  # Effective, not requested: see resolve_data_control().
  output$nonlinear_strength <- dc$effective_nonlinear_strength
  output$correlation <- dc$correlation
  output$predictor_distribution <- dc$effective_distribution
  output$predictor_type <- dc$predictor_type
  output$binary_predictor_prevalence <- dc$binary_prevalence
  output$maximum_achievable_rsquared <- maximum_achievable_rsquared
  output$model <- model
  output$metric <- metric
  output$n_reps_total <- n_reps_total
  output$mean_or_assurance <- mean_or_assurance
  class(output) <- "pmsims"
  output
}

#' Minimum sample size for survival‐outcome prediction models
#'
#' Compute the minimum sample size required to develop a prediction model with a
#' **time-to-event (survival)** outcome. As with the other wrappers, this uses a
#' simulation-based learning curve, fitted by default to every simulated
#' replicate (`method = "curve"`; `method = "mlpwr"` uses a Gaussian-process
#' surrogate instead), to locate the smallest \eqn{n} meeting the chosen
#' performance criterion.
#'
#' @inheritSection simulate_binary Criteria
#' @inheritSection simulate_binary Data control
#'
#' @inheritParams simulate_binary
#' @param maximum_achievable_cindex Numeric in (0, 1). Maximum achievable
#'   C-index with effectively unlimited data. This is used to calibrate the
#'   data-generating mechanism and is not the minimum acceptable threshold.
#' @param baseline_hazard Numeric greater than 0. Baseline hazard level used by the
#'   data-generating mechanism (e.g., the constant hazard in an exponential
#'   baseline). Larger values imply shorter event times, all else equal.
#' @param censoring_rate Numeric in [0, 1). Proportion of individuals expected
#'   to be censored in the simulated datasets (administrative or random
#'   censoring). Higher values imply fewer observed events for a fixed \eqn{n}.
#' @param model Character string specifying the modelling algorithm. One of
#'   `"coxph"` (Cox proportional hazards), `"lasso"`, `"ridge"`, `"rf"` (random
#'   survival forest), or `"xgboost"` (gradient boosting with a Cox objective).
#'
#' @return An object of class `"pmsims"` containing the estimated minimum sample
#'   size and simulation diagnostics (inputs, fitted GP curve, intermediate
#'   evaluations, and summary metrics).
#'
#' @seealso [simulate_binary()], [simulate_continuous()], [simulate_custom()]
#'
#' @examples
#' \donttest{
#' set.seed(123)
#' est <- simulate_survival(
#'   signal_parameters = 1,
#'   noise_parameters = 0,
#'   complexity = 1,
#'   data_control = list(correlation = 0),
#'   maximum_achievable_cindex = 0.70,
#'   baseline_hazard = 0.01,
#'   censoring_rate = 0.30,
#'   model = "coxph",
#'   metric = "calibration_slope",
#'   target_performance = 0.9,
#'   mean_or_assurance = "assurance",
#'   min_sample_size = 25,
#'   max_sample_size = 500,
#'   n_reps_total = 1000,
#'   auto_n_reps_total = FALSE,
#'   test_n = 30000,
#'   progress = FALSE
#' )
#' est
#' est$min_n
#' plot(est)
#' }
#' @export
simulate_survival <- function(
  signal_parameters,
  noise_parameters = 0,
  complexity = 1,
  data_control = NULL,
  maximum_achievable_cindex,
  baseline_hazard = 1,
  censoring_rate,
  model = c("coxph", "lasso", "ridge", "rf", "xgboost"),
  metric = "calibration_slope",
  target_performance,
  n_reps_total = 1000,
  mean_or_assurance = "assurance",
  auto_n_reps_total = TRUE,
  ...
) {
  model <- check_pmsims_args(
    model,
    c("coxph", "lasso", "ridge", "rf", "xgboost")
  )
  validate_metric_constraints(
    metric = metric,
    target_performance = target_performance,
    maximum_achievable_performance = maximum_achievable_cindex
  )
  # Machine learning models search on the CSSE scale internally; see
  # R/csse_internal.R.
  csse_plan <- plan_internal_csse(metric, model, target_performance)
  validate_complexity(complexity, signal_parameters)
  dc <- resolve_data_control(data_control, complexity)

  # Shared budget rule; see resolve_n_reps_total(). Applied after validation so
  # that bad inputs are still reported by the checks above, and before the
  # engine call so that output$n_reps_total records what was actually used.
  n_reps_total <- resolve_n_reps_total(
    n_reps_total = n_reps_total,
    signal_parameters = signal_parameters,
    model = model,
    method = list(...)$method,
    auto = auto_n_reps_total
  )

  candidate_features <- signal_parameters + noise_parameters
  proportion_noise_features <- noise_parameters / candidate_features

  # Tune the data-generating function under the SAME data configuration.
  tune_param <- call_tuner(
    survival_tuning,
    required = list(
      target_prevalence = 1 - censoring_rate,
      target_performance = maximum_achievable_cindex,
      candidate_features = candidate_features,
      proportion_noise_features = proportion_noise_features,
      .complexity = complexity
    ),
    dc = dc
  )

  data_spec <- list(
    type = "survival",
    args = make_data_args(
      signal_parameters,
      noise_parameters,
      complexity,
      dc,
      extra = list(
        baseline_hazard = baseline_hazard,
        beta_signal = get_param(tune_param, "beta_signal"),
        censoring_rate = censoring_rate
      )
    )
  )

  data_function <- default_data_generators(data_spec)
  outcome_type <- attr(data_function, "outcome")
  model_function <- default_model_generators(outcome_type, model)

  simulate_custom_args <- utils::modifyList(
    list(
      metric_function = describe_as_calibration_slope(
        default_metric_generator(csse_plan$metric, data_function),
        csse_plan
      ),
      target_performance = csse_plan$target_performance,
      c_statistic = maximum_achievable_cindex,
      data_function = data_function,
      model_function = model_function,
      n_reps_total = n_reps_total,
      n_reps_per = 20,
      method = "curve",
      mean_or_assurance = mean_or_assurance,
      test_n = 30000
    ),
    list(...)
  )

  output <- do.call(simulate_custom, simulate_custom_args)

  # Put any internally-converted results back on the calibration slope scale.
  output <- restore_calibration_slope_scale(output, csse_plan)

  metric_2 <- if (metric %in% c("csse", "calibration_slope")) {
    "cindex"
  } else {
    "calibration_slope"
  }

  metric_function_2 <- default_metric_generator(metric_2, data_function)

  metric_2_at_n <- secondary_metric_at(output, metric_function_2)

  output$metric_2_at_n <- metric_2_at_n
  output$metric_2 <- metric_2

  # Append input parameters
  output$signal_parameters <- signal_parameters
  output$noise_parameters <- noise_parameters
  output$complexity <- complexity
  # Effective, not requested: see resolve_data_control().
  output$nonlinear_strength <- dc$effective_nonlinear_strength
  output$correlation <- dc$correlation
  output$predictor_distribution <- dc$effective_distribution
  output$predictor_type <- dc$predictor_type
  output$binary_predictor_prevalence <- dc$binary_prevalence
  output$baseline_hazard <- baseline_hazard
  output$censoring_rate <- censoring_rate
  output$maximum_achievable_cindex <- maximum_achievable_cindex
  output$model <- model
  output$metric <- metric
  output$n_reps_total <- n_reps_total
  output$mean_or_assurance <- mean_or_assurance
  class(output) <- "pmsims"
  output
}

# Secondary metric at the returned sample size, averaged over `reps`
# replicates on their own random streams. NA when there is no sample size.
secondary_metric_at <- function(output, metric_function_2, reps = 10L) {
  n <- suppressWarnings(as.numeric(output$min_n))
  if (length(n) != 1L || !is.finite(n)) {
    return(NA_real_)
  }
  # Same cores as the search; each replicate has its own stream, so the
  # value does not depend on them.
  cores <- output$cores %||% 1L
  if (cores > 1L) {
    old_threads <- options(pmsims.threads = 1L)
    on.exit(options(old_threads), add = TRUE)
  }
  evaluator <- new_evaluator(
    data_function = output$data_function,
    model_function = output$model_function,
    metric_function = metric_function_2,
    test_n = output$test_n,
    value_on_error = NA_real_,
    streams = new_simulation_streams(output$rng_base_seed),
    parallel = cores > 1L,
    cores = cores
  )
  mean(evaluator$batch(n, reps, "secondary"), na.rm = TRUE)
}

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.