View source: R/simulate_wrappers.R
| simulate_survival | R Documentation |
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 n meeting the chosen
performance criterion.
simulate_survival(
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,
...
)
signal_parameters |
Integer. Number of candidate predictors associated with the outcome (i.e., true signal features). |
noise_parameters |
Integer. Number of candidate predictors not associated with the outcome (noise features). Default is 0. |
complexity |
Integer in 1:4 selecting the data-generating signal
structure (see Data control). Default |
data_control |
Optional named list controlling the predictors (see
Data control). Default |
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. |
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. |
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 |
model |
Character string specifying the modelling algorithm. One of
|
metric |
Character string naming the performance metric used to assess
the sample size; defaults to
|
target_performance |
Numeric. Minimum acceptable value of the selected
performance metric |
n_reps_total |
Integer. Total number of simulation replications used by the engine across the search. |
mean_or_assurance |
Character string, either |
auto_n_reps_total |
Logical. When |
... |
Additional options passed to |
An object of class "pmsims" containing the estimated minimum sample
size and simulation diagnostics (inputs, fitted GP curve, intermediate
evaluations, and summary metrics).
Two formulations are supported.
Mean-based: find the smallest n such that the expected model
performance exceeds the target M^*, i.e.
\min_n \; \mathbb{E}_{D_n}\{ M \mid D_n \} \ge M^*.
Assurance-based: find the smallest n such that the probability
the performance exceeds M^* is at least \delta (e.g. 0.80),
i.e.
\min_n \; \mathbb{P}_{D_n}\!\left( M \mid D_n \ge M^* \right) \ge \delta.
Here, M is the chosen performance metric and the probability/expectation
is over repeated samples of training data of size n. The assurance
criterion explicitly accounts for variability across training sets; models
with higher variance typically require larger n to satisfy it.
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:
nonlinear_strengthNumeric 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.
correlationNumeric in [-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.
predictor_distributionOne 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".
binary_predictor_prevalenceNumeric 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.
simulate_binary(), simulate_continuous(), simulate_custom()
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)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.