Skip to contents

Sample size estimation for RMST-based models via formula interface

Source: R/rmst-interface.R
rmst.ss.Rd

Routes a formula-based call to the matching RMST sample-size routine.

Usage

rmst.ss(
  formula,
  data,
  arm,
  target_power,
  L,
  strata = NULL,
  strata_type = c("additive", "multiplicative"),
  dep_cens = FALSE,
  type = c("analytical", "boot"),
  alpha = 0.05,
  n_sim = 1000L,
  parallel.cores = 1L,
  n_start = 50L,
  n_step = 25L,
  max_n = 2000L,
  patience = 5L,
  verbose = FALSE
)

Arguments

formula

A formula of the form Surv(time, status) ~ cov1 + cov2.

data

A data.frame containing the reference (pilot) data.

arm

Character string naming the treatment arm column (binary 0/1).

target_power

Numeric target power (e.g., 0.80).

L

Numeric truncation time for RMST.

strata

Character column name, one-sided formula (~col), or NULL.

strata_type

One of "additive" (default) or "multiplicative".

dep_cens

Logical; use dependent-censoring model? Default FALSE.

type

One of "analytical" or "boot".

alpha

Significance level. Default 0.05.

n_sim

Number of bootstrap replicates. Default 1000.

parallel.cores

Number of cores for parallel processing. Default 1.

n_start

Starting sample size for the search. Default 50.

n_step

Search increment. Default 25.

max_n

Maximum sample size to try. Default 2000.

patience

Number of consecutive non-improving steps before stopping. Default 5.

verbose

Logical; if TRUE, emit progress messages from the underlying calculation. Default FALSE.

Value

An object of class c("rmst_ss", "list") with elements results_data, results_plot, results_summary, model_output, and .meta.

See also

rmst.power, print.rmst_ss, summary.rmst_ss, plot.rmst_ss

Examples

data(aft_lognormal_L12_n150, package = "RMSTpowerBoost")
r <- rmst.ss(Surv(time, status) ~ age,
             data         = aft_lognormal_L12_n150,
             arm          = "arm",
             target_power = 0.80,
             L            = 12)
print(r)
#> ── RMST Sample Size Estimation ────────────────
#>   Model           : Linear IPCW (Analytical) 
#>   Formula         : Surv(time, status) ~ age 
#>   Arm             : arm 
#>   Truncation time : 12 
#>   Alpha           : 0.05 
#> 
#> Sample Size Result:
#>  Target_Power Required_N_per_Arm
#>           0.8                350
#> 
#> Treatment Effect (from reference data):
#>   Estimand : RMST Difference 
#>   Estimate : -0.5447