R/data.R

#' Precomputed sample-size simulations
#'
#' Results from four completed sample-size searches, one for each of the
#' package's entry points. A search repeatedly simulates datasets, fits a
#' prediction model to each and evaluates its performance across a range of
#' candidate sample sizes, so a realistic run takes minutes to hours. These
#' objects were computed once, with the calls shown under *Source*, so that the
#' examples and the vignette can demonstrate the output without recomputing it.
#'
#' Each object is a `"pmsims"` object, as returned by [simulate_binary()],
#' [simulate_continuous()], [simulate_survival()] and [simulate_custom()], and
#' can be used with [print()] and [plot()] in the usual way.
#'
#' @format A list of class `"pmsims"`. The most useful components are:
#' \describe{
#'   \item{`min_n`}{The estimated minimum sample size.}
#'   \item{`perf_n`}{Expected performance at `min_n`.}
#'   \item{`target_performance`}{The performance target the search aimed for.}
#'   \item{`metric`}{The performance metric used.}
#'   \item{`model`}{The model fitted to each simulated dataset.}
#'   \item{`status`}{`"ok"` when the search found `min_n` and a check at
#'     `min_n` confirmed it; see [simulate_custom()] for other values.}
#'   \item{`data`}{The simulated performance values at each sample size,
#'     used by [plot()].}
#'   \item{`diagnostics`}{Details of the search, including the fitted
#'     learning curve and the interval for `min_n` (`diagnostics$curve`).}
#'   \item{`summaries`}{Aggregated performance summaries across replications.}
#'   \item{`simulation_time`}{Elapsed time of the original run, in seconds.}
#' }
#'
#' Objects produced by the wrapper functions additionally record the
#' data-generating configuration (for example `outcome_prevalence`,
#' `correlation` and `complexity`); see [simulate_binary()] for the full set.
#'
#' @source Generated by `data-raw/precomputed-examples.R`.
#'
#' `binary_example`:
#' ```r
#' set.seed(123)
#' simulate_binary(
#'   signal_parameters = 20,
#'   noise_parameters = 0,
#'   complexity = 1,
#'   data_control = list(correlation = 0.3),
#'   outcome_prevalence = 0.30,
#'   maximum_achievable_cstatistic = 0.80,
#'   model = "glm",
#'   metric = "calibration_slope",
#'   target_performance = 0.85,
#'   n_reps_total = 1000,
#'   mean_or_assurance = "assurance"
#' )
#' ```
#'
#' `continuous_example`:
#' ```r
#' set.seed(123)
#' simulate_continuous(
#'   signal_parameters = 15,
#'   noise_parameters = 0,
#'   complexity = 1,
#'   data_control = list(correlation = 0.3),
#'   maximum_achievable_rsquared = 0.50,
#'   model = "lm",
#'   metric = "calibration_slope",
#'   target_performance = 0.95,
#'   n_reps_total = 1000,
#'   mean_or_assurance = "assurance"
#' )
#' ```
#'
#' `survival_example`:
#' ```r
#' set.seed(123)
#' simulate_survival(
#'   signal_parameters = 15,
#'   noise_parameters = 0,
#'   complexity = 1,
#'   data_control = list(correlation = 0.3),
#'   maximum_achievable_cindex = 0.70,
#'   baseline_hazard = 0.01,
#'   censoring_rate = 0.30,
#'   model = "coxph",
#'   metric = "calibration_slope",
#'   target_performance = 0.90,
#'   n_reps_total = 1000,
#'   mean_or_assurance = "assurance"
#' )
#' ```
#'
#' `custom_example`: a linear model with three independent predictors and a
#' population \eqn{R^2} of 0.5, targeting a calibration slope of 0.9 with
#' 80% assurance. The search uses bounds of 25 to 1,000 participants, 1,000
#' replications and 30,000 test observations. See [simulate_custom()] for the
#' generating functions and executable call (seed 123).
#'
#' @seealso [simulate_binary()], [simulate_continuous()],
#'   [simulate_survival()], [simulate_custom()]
#'
#' @examples
#' binary_example
#' binary_example$min_n
#' @name precomputed
#' @keywords datasets
NULL

#' @rdname precomputed
"binary_example"

#' @rdname precomputed
"continuous_example"

#' @rdname precomputed
"survival_example"

#' @rdname precomputed
"custom_example"

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.