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