View source: R/simulate_wrappers.R
| simulate_binary | R Documentation |
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 n that
meets the chosen performance criterion.
simulate_binary(
signal_parameters,
noise_parameters = 0,
complexity = 1,
data_control = NULL,
outcome_prevalence,
maximum_achievable_cstatistic,
model = c("glm", "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 |
outcome_prevalence |
Numeric in (0, 1). Target prevalence of the binary outcome in the intended modelling context. |
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. |
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_continuous(), simulate_survival(), simulate_custom()
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)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.