Package 'RMSTpowerBoost'

Description

Performs power analysis for a stratified, additive RMST model using the analytic variance estimator based on the method of Zhang & Schaubel (2024).

Usage

additive.power.analytical(
  pilot_data,
  time_var,
  status_var,
  arm_var,
  strata_var,
  sample_sizes,
  linear_terms = NULL,
  L,
  alpha = 0.05,
  verbose = FALSE
)

Arguments

Details

This function computes power for the semiparametric additive RMST model $\mu_{ij} = \mu_{0j} + \beta'Z_i$, where i indexes subjects and j indexes strata.

The method uses Inverse Probability of Censoring Weighting (IPCW), with weights derived from a stratified Cox model for the censoring times. The regression coefficient $\hat{\beta}$ is estimated by centering the covariates and RMST values within each stratum and then solving the resulting estimating equations in closed form.

Power is obtained from the asymptotic sandwich variance of $\hat{\beta}$. This implementation uses the robust variance estimator $A_n^{-1} B_n (A_n^{-1})'$, where $A_n$ and $B_n$ are empirical estimates of the variance components.

Value

A list containing:

Examples

set.seed(123)
pilot_df_strat <- data.frame(
 time = rexp(150, 0.1),
 status = rbinom(150, 1, 0.8),
 arm = rep(0:1, each = 75),
 region = factor(rep(c("A", "B", "C"), each = 50)),
 age = rnorm(150, 60, 10)
)
# Introduce an additive treatment effect
pilot_df_strat$time[pilot_df_strat$arm == 1] <-
  pilot_df_strat$time[pilot_df_strat$arm == 1] + 1.5

power_results <- additive.power.analytical(
  pilot_data = pilot_df_strat,
  time_var = "time", status_var = "status", arm_var = "arm", strata_var = "region",
  sample_sizes = c(100, 150, 200),
  linear_terms = "age",
  L = 12
)
print(power_results$results_data)
print(power_results$results_plot)

Description

Calculates the required sample size for a target power using the analytic method for a stratified, additive RMST model.

Usage

additive.ss.analytical(
  pilot_data,
  time_var,
  status_var,
  arm_var,
  strata_var,
  target_power,
  linear_terms = NULL,
  L,
  alpha = 0.05,
  n_start = 50,
  n_step = 25,
  max_n_per_arm = 2000,
  verbose = FALSE
)

Arguments

Details

This function estimates the additive treatment effect and its asymptotic variance once from the pilot data, then increases the per-stratum sample size until the target power is reached or the search limit is hit. It uses the same stratum-centering framework as additive.power.analytical.

Value

A list containing:

Examples

set.seed(123)
pilot_df_strat <- data.frame(
 time = rexp(150, 0.1),
 status = rbinom(150, 1, 0.8),
 arm = rep(0:1, each = 75),
 region = factor(rep(c("A", "B", "C"), each = 50)),
 age = rnorm(150, 60, 10)
)
# Introduce an additive treatment effect
pilot_df_strat$time[pilot_df_strat$arm == 1] <-
  pilot_df_strat$time[pilot_df_strat$arm == 1] + 1.5

  # Find the required sample size per stratum for 80% power
  ss_results <- additive.ss.analytical(
    pilot_data = pilot_df_strat,
    time_var = "time", status_var = "status",
    arm_var = "arm", strata_var = "region",
    target_power = 0.50,
    L = 18, #
    n_start = 200,
    n_step = 50,
    max_n_per_arm = 1000
  )
  print(ss_results$results_data)
  print(ss_results$results_plot)

Description

Columns:

• time: observed time

• status: event indicator (1 = event, 0 = censored)

• arm: treatment arm (0 = control, 1 = treatment)

• age: baseline age

• gender: factor with two levels

Format

A data frame with 150 rows and 5 variables.

Examples

data(aft_lognormal_L12_n150)
table(aft_lognormal_L12_n150$arm)

Description

Columns: time, status, arm, age, gender.

Format

A data frame with 200 rows and 5 variables.

Examples

data(aft_weibull_L24_n200)
mean(aft_weibull_L24_n200$status == 0)

Description

Builds a binary (Bernoulli) covariate definition list.

Usage

covar_binary(name, p = 0.5)

Arguments

Value

A named list suitable as one element of the covariates argument.

See Also

covar_continuous, covar_categorical, rmst.sim

Examples

covar_binary("female", p = 0.52)

Description

Builds a multi-level categorical covariate definition list.

Usage

covar_categorical(name, probs, labels = NULL)

Arguments

Value

A named list suitable as one element of the covariates argument.

See Also

covar_continuous, covar_binary, rmst.sim

Examples

covar_categorical("stage", probs = c(0.4, 0.35, 0.25),
                  labels = c("I", "II", "III"))

Description

Builds a covariate definition list for use in rmst.sim, recipe_quick_aft, or recipe_quick_ph.

Usage

covar_continuous(name, dist = "normal", ...)

Arguments

Value

A named list suitable as one element of the covariates argument.

See Also

covar_binary, covar_categorical, rmst.sim

Examples

covar_continuous("age", dist = "normal", mean = 50, sd = 10)
covar_continuous("bmi", dist = "lognormal", meanlog = 3.2, sdlog = 0.2)

Description

Performs power analysis for an RMST model when the censoring mechanism depends on observed covariates.

Usage

DC.power.analytical(
  pilot_data,
  time_var,
  status_var,
  arm_var,
  sample_sizes,
  linear_terms = NULL,
  L,
  alpha = 0.05,
  verbose = FALSE
)

Arguments

Details

This function assumes a single censoring process whose hazard depends on covariates (but not on treatment by default). It fits a Cox model for censoring

$\Pr(\text{censoring by } t \mid X) = 1 - G(t \mid X)$

using Surv(time, status==0) ~ linear\_terms, then forms inverse-probability-of-censoring weights (IPCW) $w_i = 1/\hat G(Y_i\mid X_i)$ evaluated at $Y_i=\min(T_i,L)$. The RMST regression $E[Y_i \mid A_i,X_i]$ is then fit by weighted least squares, and power is derived from a sandwich variance that ignores uncertainty from estimating $\hat G$.

Note: This implementation models a single censoring process and does not handle competing risks.

Value

A list with:

Description

Iteratively finds required per-arm sample size for a target power, using the same IPCW-based analytic variance as DC.power.analytical.

Usage

DC.ss.analytical(
  pilot_data,
  time_var,
  status_var,
  arm_var,
  target_power,
  linear_terms = NULL,
  L,
  alpha = 0.05,
  n_start = 50,
  n_step = 25,
  max_n_per_arm = 2000,
  verbose = FALSE
)

Arguments

Details

Uses a single censoring Cox model Surv(time, status==0) ~ linear_terms to form IPCW and fits a weighted RMST regression. Treatment is excluded from the censoring model by default. Competing risks are not modeled. Variance ignores uncertainty in $\hat G$.

Note: This implementation models a single censoring process and does not handle competing risks.

Value

A list with:

Description

Given one element returned by load_recipe_sets() (a list with data and a rich meta list), this builds tidy tables describing the data-generating process: model family, baseline parameters, linear predictor coefficients (intercept / treatment / covariates), treatment assignment, and censoring.

Usage

describe_generation(set)

Arguments

Value

A list of data frames:

• header: n, L (analysis horizon; stored as attr "tau"), model, event_rate, achieved_censoring.

• baseline: flattened baseline parameters.

• effects: coefficients for intercept/treatment and covariates (and formula terms if used).

• treatment: assignment mechanism and knobs.

• censoring: censoring mode/target/admin time.

• covariates: each generated covariate with its distribution and parameters.

• files: paths to on-disk files (csv/rds/rdata) when available.

Examples

covs <- list(covar_continuous("x", mean = 0, sd = 1))
rec <- recipe_quick_aft(
  n = 20, model = "aft_lognormal",
  baseline = list(mu = 2.7, sigma = 0.6),
  treat_effect = -0.2, covariates = covs,
  target_censoring = 0.2, seed = 123
)
out <- file.path(tempdir(), "rmst_describe_generation")
generate_recipe_sets(rec, out_dir = out, formats = "rds", n_reps = 1)
sets <- load_recipe_sets(file.path(out, "manifest.rds"))
spec <- describe_generation(sets[[1]])
spec$header
spec$baseline
spec$effects
spec$treatment
spec$censoring
spec$covariates
spec$files

Description

Performs a power analysis for given sample sizes using a flexible, semiparametric additive model for the RMST based on pseudo-observations.

Usage

GAM.power.boot(
  pilot_data,
  time_var,
  status_var,
  arm_var,
  strata_var = NULL,
  sample_sizes,
  linear_terms = NULL,
  smooth_terms = NULL,
  L,
  n_sim = 1000,
  alpha = 0.05,
  parallel.cores = 1,
  verbose = FALSE
)

Arguments

Details

This function estimates power by bootstrap resampling the pilot data, computing RMST pseudo-observations, fitting a semiparametric additive model, and recording whether the treatment effect is significant. If strata_var is supplied, resampling is carried out within strata. The model formula can include linear terms, non-linear smooth terms (s()), and interactions.

Power is estimated as the proportion of simulations with a treatment-effect p-value below alpha. This pseudo-observation approach models RMST directly without using the IPCW estimating equations used elsewhere in the package.

Value

A list containing:

Note

status_var should be 1 for an event, 0 for censored. arm_var should be 1 for treatment, 0 for control.

Examples

pilot_df <- data.frame(
  time = rexp(100, 0.08),
  status = rbinom(100, 1, 0.7),
  arm = rep(0:1, each = 50),
  age = rnorm(100, 60, 10)
)
# Add a treatment effect
pilot_df$time[pilot_df$arm == 1] <- pilot_df$time[pilot_df$arm == 1] * 1.3

power_results <- GAM.power.boot(
  pilot_data = pilot_df,
  time_var = "time",
  status_var = "status",
  arm_var = "arm",
  sample_sizes = c(100, 150),
  linear_terms = "age",
  L = 15,
  n_sim = 100, # Use more sims in practice, e.g., 1000
  parallel.cores = 2
)
print(power_results$results_data)
print(power_results$results_plot)

Description

Performs an iterative sample size search to achieve a target power using a flexible, semiparametric additive model for the RMST.

Usage

GAM.ss.boot(
  pilot_data,
  time_var,
  status_var,
  arm_var,
  strata_var = NULL,
  target_power,
  linear_terms = NULL,
  smooth_terms = NULL,
  L,
  n_sim = 1000,
  alpha = 0.05,
  parallel.cores = 1,
  patience = 5,
  n_start = 50,
  n_step = 25,
  max_n_per_arm = 2000,
  verbose = FALSE
)

Arguments

Details

This function increases the sample size step by step until the estimated power reaches target_power or a stopping rule is met. At each step it runs the same bootstrap procedure described in GAM.power.boot.

Value

A list containing:

Note

This function's methodology is bootstrap-based.

Examples

pilot_df_effect <- data.frame(
  time = c(stats::rexp(50, 0.1), stats::rexp(50, 0.04)), # Effect
  status = stats::rbinom(100, 1, 0.9),
  arm = rep(0:1, each = 50)
)

ss_results <- GAM.ss.boot(
  pilot_data = pilot_df_effect,
  time_var = "time",
  status_var = "status",
  arm_var = "arm",
  target_power = 0.80,
  L = 15,
  n_sim = 100,      # Low n_sim for example
  n_start = 100,
  n_step = 50,
  patience = 2,
  parallel.cores = 2
)
print(ss_results$results_data)
print(ss_results$results_plot)

Description

Generate covariate matrix/data frame from a recipe

Usage

gen_covariates(n, covariates)

Arguments

Value

data.frame of covariates

Examples

defs <- list(
  list(name="x", type="continuous", dist="normal", params=list(mean=0, sd=1)),
  list(name="z", type="categorical", dist="categorical",
       params=list(prob=c(0.3,0.7), labels=c("A","B")))
)
X <- gen_covariates(10, list(defs = defs))

Description

Builds a grid of scenarios from a base recipe and a named list of variations, simulates one or more replicates per scenario, and writes the datasets to files in a target folder as .txt (tab), .csv, .rds, and/or .RData. A manifest is written as manifest.rds. The recipe specification does not include an analysis horizon; specify L later in downstream analysis functions.

Usage

generate_recipe_sets(
  base_recipe,
  vary = list(),
  out_dir,
  formats = c("txt", "csv", "rds", "rdata"),
  n_reps = 1L,
  seed_base = NULL,
  filename_template = "sc{scenario_id}_r{rep}"
)

Arguments

Value

Invisibly returns the manifest data.frame and writes manifest.rds.

Examples

covs <- list(list(name="x", type="continuous", dist="normal", params=list(mean=0, sd=1)))
rec <- recipe_quick_aft(60, "aft_lognormal",
         baseline=list(mu=2.7, sigma=0.6), treat_effect=-0.2,
         covariates=covs, target_censoring=0.2)
out <- file.path(tempdir(), "rmst_checks")
dir.create(out, showWarnings = FALSE, recursive = TRUE)
man <- generate_recipe_sets(rec, vary=list(n=c(60,80)), out_dir=out,
         formats=c("csv","rds"), n_reps=1, seed_base=123)

Description

Performs power analysis using a direct formula based on the asymptotic variance estimator for the linear RMST model.

Usage

linear.power.analytical(
  pilot_data,
  time_var,
  status_var,
  arm_var,
  sample_sizes,
  linear_terms = NULL,
  L,
  alpha = 0.05,
  verbose = FALSE
)

Arguments

Details

This function implements the analytic power calculation for the direct linear regression model of the Restricted Mean Survival Time (RMST) proposed by Tian et al. (2014). The core of the method is a weighted linear model of the form

$E[Y_i \mid A_i, \mathbf{Z}_i] = \alpha + \tau A_i + \mathbf{Z}_i^\top \boldsymbol{\gamma}$

where $Y_i = \min(T_i, L)$ is the event time truncated at $L$, $A_i$ is the treatment indicator, and $\tau$ is the treatment effect of interest.

To handle right-censoring, the method uses Inverse Probability of Censoring Weighting (IPCW). The weight for an uncensored individual i is the inverse of the probability of remaining uncensored until their event time, $w_i = \delta_i / \hat{G}(Y_i)$, where $\hat{G}(t) = P(C > t)$ is the Kaplan-Meier estimate of the censoring distribution.

Power is calculated analytically based on the asymptotic properties of the coefficient estimators. The variance of the treatment effect estimator, $\hat{\tau}$, is derived from a robust sandwich variance estimator of the form $A^{-1}B(A^{-1})'$. In this implementation, A is the scaled information matrix $(X'WX)/n$, and B is the empirical second moment of the influence functions, $(\sum \epsilon_i \epsilon_i')/n$, where $\epsilon_i$ is the influence curve for observation i. The resulting variance is used to calculate the standard error for a given sample size, which in turn is used in the power formula.

Value

A list containing:

Examples

pilot_df <- data.frame(
  time = rexp(100, 0.1),
  status = rbinom(100, 1, 0.7),
  arm = rep(0:1, each = 50),
  age = rnorm(100, 55, 10)
)
power_results <- linear.power.analytical(
  pilot_data = pilot_df,
  time_var = "time",
  status_var = "status",
  arm_var = "arm",
  linear_terms = "age",
  sample_sizes = c(100, 200, 300),
  L = 10
)
print(power_results$results_data)
print(power_results$results_plot)

Description

Performs a power analysis for given sample sizes based on the direct linear regression model for RMST, using a bootstrap simulation approach.

Usage

linear.power.boot(
  pilot_data,
  time_var,
  status_var,
  arm_var,
  sample_sizes,
  linear_terms = NULL,
  L,
  n_sim = 1000,
  alpha = 0.05,
  verbose = FALSE
)

Arguments

Details

This function estimates power by generating a number of bootstrap samples (n_sim) from the provided pilot data by resampling with replacement. For each bootstrap sample, it performs the following steps:

1. Estimates the censoring distribution using the Kaplan-Meier method (survival::survfit).

2. Calculates Inverse Probability of Censoring Weights (IPCW) for each observation.

3. Fits a weighted linear model (stats::lm) to the RMST of the uncensored subjects.

4. Extracts the p-value for the treatment arm_var coefficient.

The final power for a given sample size is the proportion of the n_sim simulations where this p-value is less than the significance level alpha. This simulation-based approach can be useful when analytic approximations are less reliable, but it can be computationally intensive.

Value

A list containing:

Note

status_var should be 1 for an event, 0 for censored. arm_var should be 1 for treatment, 0 for control.

Examples

pilot_df <- data.frame(
  time = rexp(100, 0.1),
  status = rbinom(100, 1, 0.7),
  arm = rep(0:1, each = 50),
  age = rnorm(100, 60, 8)
)
# Introduce a treatment effect for a more interesting example
pilot_df$time[pilot_df$arm == 1] <- pilot_df$time[pilot_df$arm == 1] * 1.5

power_results <- linear.power.boot(
  pilot_data = pilot_df,
  time_var = "time",
  status_var = "status",
  arm_var = "arm",
  linear_terms = "age",
  sample_sizes = c(100, 150, 200),
  L = 10,
  n_sim = 200 # Use more simulations in practice (e.g., 1000)
)
print(power_results$results_data)
print(power_results$results_plot)

Description

Calculates the required sample size for a target power using an analytic formula based on the methods of Tian et al. (2014).

Usage

linear.ss.analytical(
  pilot_data,
  time_var,
  status_var,
  arm_var,
  target_power,
  linear_terms = NULL,
  L,
  alpha = 0.05,
  n_start = 50,
  n_step = 25,
  max_n_per_arm = 2000,
  verbose = FALSE
)

Arguments

Details

This function performs an iterative search to find the sample size needed to achieve a specified target_power. It uses the same underlying theory as linear.power.analytical. First, it estimates the treatment effect size and its asymptotic variance from the pilot data. Then, it iteratively calculates the power for increasing sample sizes using the analytic formula until the target power is achieved.

Value

A list containing:

Examples

pilot_df <- data.frame(
  time = c(rexp(50, 0.1), rexp(50, 0.07)), # Introduce an effect
  status = rbinom(100, 1, 0.8),
  arm = rep(0:1, each = 50),
  age = rnorm(100, 55, 10)
)
ss_results <- linear.ss.analytical(
  pilot_data = pilot_df,
  time_var = "time",
  status_var = "status",
  arm_var = "arm",
  target_power = 0.80,
  L = 10
)
print(ss_results$results_data)
print(ss_results$results_plot)

Description

Performs an iterative sample size search to achieve a target power based on the direct linear regression model for RMST, using bootstrap simulation.

Usage

linear.ss.boot(
  pilot_data,
  time_var,
  status_var,
  arm_var,
  target_power,
  linear_terms = NULL,
  L,
  n_sim = 1000,
  alpha = 0.05,
  patience = 5,
  n_start = 50,
  n_step = 25,
  max_n_per_arm = 2000,
  verbose = FALSE
)

Arguments

Details

This function iteratively searches for the required sample size to achieve a specified target_power. At each step of the search, it runs a full bootstrap simulation (n_sim iterations), as described in linear.power.boot, to estimate the power for the current sample size. The search stops when the target power is achieved or other stopping criteria (e.g., patience) are met. Due to the nested simulation structure, this function can be very time-consuming.

Value

A list containing:

Note

status_var should be 1 for an event, 0 for censored. arm_var should be 1 for treatment, 0 for control.

Examples

pilot_df_effect <- data.frame(
  time = c(rexp(50, 0.1), rexp(50, 0.05)), # Effect present
  status = rbinom(100, 1, 0.8),
  arm = rep(0:1, each = 50)
)
ss_results <- linear.ss.boot(
  pilot_data = pilot_df_effect,
  time_var = "time",
  status_var = "status",
  arm_var = "arm",
  target_power = 0.80,
  L = 10,
  n_sim = 200, # Low n_sim for example
  patience = 2,
  n_start = 100,
  n_step = 50,
  max_n_per_arm = 500
)
print(ss_results$results_data)
print(ss_results$results_plot)

Description

Reads a manifest.rds created by generate_recipe_sets(), loads one dataset per row (preferring rds to rdata to csv to txt), restores attribute "achieved_censoring", and returns a named list of list(data = <data.frame>, meta = <list>).

Usage

load_recipe_sets(manifest_path)

Arguments

Value

A named list where each element is list(data=..., meta=...).

Examples

covs <- list(covar_continuous("x", mean = 0, sd = 1))
rec <- recipe_quick_aft(
  n = 20, model = "aft_lognormal",
  baseline = list(mu = 2.7, sigma = 0.6),
  treat_effect = -0.2, covariates = covs,
  target_censoring = 0.2, seed = 123
)
out <- file.path(tempdir(), "rmst_load_recipe_sets")
generate_recipe_sets(rec, out_dir = out, formats = "rds", n_reps = 1)
sets <- load_recipe_sets(file.path(out, "manifest.rds"))
names(sets)
str(sets[[1]]$meta)

Description

Performs power analysis for a multiplicative, stratified RMST model using an analytic method based on the work of Wang et al. (2019).

Usage

MS.power.analytical(
  pilot_data,
  time_var,
  status_var,
  arm_var,
  strata_var,
  sample_sizes,
  linear_terms = NULL,
  L,
  alpha = 0.05,
  verbose = FALSE
)

Arguments

Details

This function is based on the method for evaluating center (stratum) effects using a multiplicative model for RMST: $\mu_{ij} = \mu_{0j} \exp\{\beta'Z_i\}$. The method uses IPCW with a stratified Cox model for the censoring distribution.

Formal estimation of $\beta$ requires an iterative solver for the estimating equation given in Equation (8) of Wang et al. (2019). Because this is computationally intensive, this implementation uses a log-linear working model fitted by weighted least squares to pseudo-observations (lm(log(Y_rmst) ~ ...)) as a tractable approximation. The approximation is consistent when the log-linear mean structure is well-specified but may differ from the formal estimator under strong misspecification.

The power calculation relies on the asymptotic variance of the log-RMST ratio estimator, $\hat{\tau}$. The variance is derived from the robust variance-covariance matrix of the lm fit, which serves as a proxy for the formal sandwich estimator $A^{-1}B(A^{-1})'$ described in Theorem 1 of Wang et al. (2019).

Value

A list containing:

Examples

set.seed(123)
pilot_df_strat <- data.frame(
 time = rexp(120, 0.15),
 status = rbinom(120, 1, 0.6),
 arm = rep(0:1, each = 60),
 region = factor(rep(c("A", "B", "C"), each = 40))
)
pilot_df_strat$time[pilot_df_strat$arm == 1] <- pilot_df_strat$time[pilot_df_strat$arm == 1] * 1.5

power_results <- MS.power.analytical(
 pilot_data = pilot_df_strat,
 time_var = "time", status_var = "status", arm_var = "arm", strata_var = "region",
 sample_sizes = c(50, 75, 100),
 L = 10, alpha = 0.05
)
print(power_results$results_data)

Description

Performs power analysis based on a multiplicative model for RMST for stratified trials, using a bootstrap simulation approach.

Usage

MS.power.boot(
  pilot_data,
  time_var,
  status_var,
  arm_var,
  strata_var,
  sample_sizes,
  linear_terms = NULL,
  L,
  n_sim = 1000,
  alpha = 0.05,
  parallel.cores = 1,
  verbose = FALSE
)

Arguments

Details

This function estimates power through bootstrap simulation, resampling within each stratum defined by strata_var. In each of the n_sim iterations:

1. Jackknife pseudo-observations for the RMST are calculated.

2. A log-linear model (stats::lm) is fitted to the log(pseudo_obs). This models the multiplicative relationship on the original RMST scale, i.e., $\mu_{ij} = \mu_{0j} \exp\{\beta'Z_i\}$. The model formula includes stratum-specific intercepts and interactions with the treatment arm.

3. The p-value for the treatment effect is extracted from the model summary.

Power is determined as the proportion of simulations where the p-value is less than alpha.

Value

A list containing:

Note

status_var should be 1/0. arm_var should be 1/0. strata_var is a mandatory argument.

Examples

pilot_df_strat <- data.frame(
 time = rexp(120, 0.15),
 status = rbinom(120, 1, 0.6),
 arm = rep(0:1, each = 60),
 region = factor(rep(c("A", "B", "C"), each = 40))
)
pilot_df_strat$time[pilot_df_strat$arm == 1] <- pilot_df_strat$time[pilot_df_strat$arm == 1] * 1.4

power_results <- MS.power.boot(
 pilot_data = pilot_df_strat,
 time_var = "time", status_var = "status", arm_var = "arm", strata_var = "region",
 sample_sizes = c(50, 75),
 L = 10,
 n_sim = 100 # Low n_sim for example
)
print(power_results$results_data)

Description

Calculates the required sample size for a target power using the analytic (approximate) method from Wang et al. (2019).

Usage

MS.ss.analytical(
  pilot_data,
  time_var,
  status_var,
  arm_var,
  strata_var,
  target_power,
  linear_terms = NULL,
  L,
  alpha = 0.05,
  n_start = 50,
  n_step = 25,
  max_n_per_arm = 2000,
  verbose = FALSE
)

Arguments

Details

This function estimates the log-RMST ratio and its asymptotic variance once from the pilot data, then increases the per-stratum sample size until the target power is reached or the search limit is hit. It uses the same log-linear approximation as MS.power.analytical.

Value

A list containing:

Examples

set.seed(456)
pilot_df_strat_effect <- data.frame(
 time = c(rexp(60, 0.15), rexp(60, 0.08)), # Effect
 status = rbinom(120, 1, 0.7),
 arm = rep(0:1, each = 60),
 region = factor(rep(c("A", "B"), each = 60))
)

ss_results <- MS.ss.analytical(
 pilot_data = pilot_df_strat_effect,
 time_var = "time", status_var = "status", arm_var = "arm", strata_var = "region",
 target_power = 0.80, L = 10,
 n_start = 100, n_step = 50
)
print(ss_results$results_data)

Description

Performs sample size estimation based on a multiplicative model for RMST for stratified trials, using iterative bootstrap simulations.

Usage

MS.ss.boot(
  pilot_data,
  time_var,
  status_var,
  arm_var,
  strata_var,
  target_power,
  linear_terms = NULL,
  L,
  n_sim = 1000,
  alpha = 0.05,
  parallel.cores = 1,
  patience = 5,
  n_start = 50,
  n_step = 25,
  max_n_per_arm = 2000,
  verbose = FALSE
)

Arguments

Details

This function iteratively searches for the sample size required to achieve a target_power. At each step of the search, it runs a full bootstrap simulation (as described in MS.power.boot) to estimate the power for the current sample size. The search proceeds until the target power is met or other stopping criteria are satisfied. This process can be very computationally intensive.

Value

A list containing:

Note

status_var should be 1/0. arm_var should be 1/0. strata_var is a mandatory argument.

Examples

pilot_df_strat_effect <- data.frame(
 time = c(rexp(60, 0.15), rexp(60, 0.08)), # Effect
 status = rbinom(120, 1, 0.7),
 arm = rep(0:1, each = 60),
 region = factor(rep(c("A", "B", "C"), each = 40))
)
ss_results <- MS.ss.boot(
 pilot_data = pilot_df_strat_effect,
 time_var = "time", status_var = "status", arm_var = "arm", strata_var = "region",
 target_power = 0.80, L = 10,
 n_sim = 100, # Low n_sim for example
 n_start = 100,
 n_step = 50, patience = 2
)
print(ss_results$results_data)

Description

Columns: time, status, arm, age, gender.

Format

A data frame with 250 rows and 5 variables.

Examples

data(ph_pwexp_L18_n250)
summary(ph_pwexp_L18_n250$time)

Description

Columns: time, status, arm, age, gender.

Format

A data frame with 300 rows and 5 variables.

Examples

data(ph_weibull_L24_n300)
prop.table(table(ph_weibull_L24_n300$status))

Description

Prints the model metadata and power table returned by rmst.power().

Returns a summary object for printing and further inspection.

Prints and returns the stored ggplot2 object.

Usage

## S3 method for class 'rmst_power'
print(x, ...)

## S3 method for class 'rmst_power'
summary(object, ...)

## S3 method for class 'rmst_power'
plot(x, ...)

Arguments

Value

The input object x, invisibly.

An object of class "summary.rmst_power".

A ggplot2 object, invisibly.

Description

Prints the model metadata and sample-size table returned by rmst.ss().

Returns a summary object for printing and further inspection.

Prints and returns the stored ggplot2 object.

Usage

## S3 method for class 'rmst_ss'
print(x, ...)

## S3 method for class 'rmst_ss'
summary(object, ...)

## S3 method for class 'rmst_ss'
plot(x, ...)

Arguments

Value

The input object x, invisibly.

An object of class "summary.rmst_ss".

A ggplot2 object, invisibly.

Description

Reads datasets already written in out_dir and reconstructs a manifest.rds with rich metadata (model, baseline, effects, etc.).

Usage

rebuild_manifest(
  base_recipe,
  vary,
  out_dir,
  filename_template = "sc{scenario_id}_r{rep}"
)

Arguments

Value

The rebuilt manifest (also writes manifest.rds in out_dir).

Description

Expand a recipe over a grid of values (list-only)

Usage

recipe_grid(base, vary)

Arguments

Value

A list of recipe lists.

Examples

r <- recipe_quick_aft(60, "aft_lognormal", baseline=list(mu=2.7, sigma=0.6),
       treat_effect=-0.2, covariates=list(list(name="x", type="continuous", dist="normal",
       params=list(mean=0, sd=1))))
recipe_grid(r, list(n=c(60,80), "event_time.effects.treatment"=c(-0.2,-0.4)))

Description

Quick AFT recipe builder for list-based simulation recipes

Usage

recipe_quick_aft(
  n,
  model = c("aft_lognormal", "aft_weibull"),
  baseline,
  treat_effect,
  covariates,
  target_censoring = 0.25,
  allocation = "1:1",
  seed = NULL
)

Arguments

Value

A recipe list suitable for simulate_from_recipe.

Examples

covs <- list(list(name="x", type="continuous", dist="normal", params=list(mean=0, sd=1)))
r <- recipe_quick_aft(120, "aft_lognormal",
       baseline=list(mu=2.3, sigma=0.5), treat_effect=-0.2,
       covariates=covs, target_censoring=0.25, allocation="1:1")
set.seed(1)
dat <- simulate_from_recipe(r)

Description

Convenience wrapper that builds a recipe list for proportional-hazard (PH) models, parallel to recipe_quick_aft for AFT models. The returned recipe is validated and ready for simulate_from_recipe.

Usage

recipe_quick_ph(
  n,
  model = c("ph_exponential", "ph_weibull", "ph_gompertz", "cox_pwexp"),
  baseline,
  treat_effect,
  covariates = list(),
  target_censoring = 0.25,
  allocation = "1:1",
  seed = NULL
)

Arguments

Value

A recipe list suitable for simulate_from_recipe.

See Also

recipe_quick_aft, rmst.sim, simulate_from_recipe

Examples

r <- recipe_quick_ph(100, "ph_weibull",
       baseline = list(shape = 1.5, scale = 10),
       treat_effect = -0.5,
       covariates = list(covar_continuous("age")),
       target_censoring = 0.30)
set.seed(1)
dat <- simulate_from_recipe(r)

Description

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

Usage

rmst.power(
  formula,
  data,
  arm,
  sample_sizes,
  L,
  strata = NULL,
  strata_type = c("additive", "multiplicative"),
  dep_cens = FALSE,
  type = c("analytical", "boot"),
  alpha = 0.05,
  n_sim = 1000L,
  parallel.cores = 1L,
  verbose = FALSE
)

Arguments

Value

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

See Also

rmst.ss, print.rmst_power, summary.rmst_power, plot.rmst_power

Examples

data(aft_lognormal_L12_n150, package = "RMSTpowerBoost")
r <- rmst.power(Surv(time, status) ~ age,
                data = aft_lognormal_L12_n150,
                arm  = "arm",
                sample_sizes = c(50, 100, 150),
                L    = 12)
print(r)
s <- summary(r)
plot(r)

Description

A unified, single-call wrapper for generating survival data suitable for use as reference/pilot data in rmst.power and rmst.ss. Supports all seven built-in event-time models (AFT and PH families).

Usage

rmst.sim(
  n,
  model = "aft_lognormal",
  baseline,
  treat_effect = 0,
  covariates = list(),
  target_censoring = 0.25,
  allocation = "1:1",
  L = NULL,
  seed = NULL
)

Arguments

Details

Internally routes to recipe_quick_aft for AFT models and recipe_quick_ph for PH models, then calls simulate_from_recipe.

Value

A data.frame of class c("rmst_simdata", "data.frame") with columns time, status, arm (when treatment is present), and one column per covariate. Attributes:

recipe

The validated recipe list used for generation.

L

The truncation time if supplied, else NULL.

achieved_censoring

Actual censoring fraction achieved.

See Also

rmst.power, rmst.ss, recipe_quick_ph, recipe_quick_aft, covar_continuous

Examples

df <- rmst.sim(
  n            = 150,
  model        = "aft_lognormal",
  baseline     = list(mu = 2.2, sigma = 0.5),
  treat_effect = -0.3,
  covariates   = list(covar_continuous("age"), covar_binary("female")),
  L            = 12,
  seed         = 42
)
print(df)
s <- summary(df)

Description

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

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)

Description

Launches the Shiny application bundled with the package. App-specific dependencies are installed only when they are needed.

Usage

run_app(install_missing = TRUE, repos = getOption("repos"))

Arguments

Value

Invisible return value from shiny::runApp().

Examples

RMSTpowerBoost::run_app()

Description

Simulate a dataset from a validated recipe (list-only)

Usage

simulate_from_recipe(recipe, seed = NULL)

Arguments

Value

A data.frame with columns time, status, arm (if treatment present), plus covariates. Attribute "achieved_censoring" is attached.

Examples

covs <- list(list(name="x", type="continuous", dist="normal", params=list(mean=0, sd=1)))
rec <- recipe_quick_aft(120, "aft_lognormal",
        baseline=list(mu=2.2, sigma=0.5), treat_effect=-0.2,
        covariates=covs, target_censoring=0.25)
set.seed(11)
dat <- simulate_from_recipe(rec)

Description

Checks/normalizes the simulation recipe and fills reasonable defaults. This function does not use or require an analysis horizon; specify L later in downstream analysis functions.

Usage

validate_recipe(recipe)

Arguments

Value

A validated recipe list.

Examples

r <- recipe_quick_aft(
  n = 100,
  model = "aft_lognormal",
  baseline = list(mu = 2.2, sigma = 0.5),
  treat_effect = -0.2,
  covariates = list(list(name="x", type="continuous", dist="normal",
                         params=list(mean=0, sd=1))),
  target_censoring = 0.25, allocation = "1:1"
)
r2 <- validate_recipe(r)