Inverse of baseline survival function S_0

Description

Computes the inverse of the baseline survival function S_0. Given a survival probability S, returns the time t such that S_0(t) = S.

Usage

S0_inverse(
  surv_prob,
  dist = c("exp", "weibull", "lognormal", "loglogistic", "custom"),
  par
)

Arguments

Value

Numeric vector of times corresponding to the survival probabilities.

Examples

# Exponential
S0_inverse(0.5, "exp", list(lambda = 0.1))

# Weibull
S0_inverse(c(0.8, 0.5), "weibull", list(k = 1.2, lambda = 0.08))

Weibull reference survival function

Description

Computes the Weibull reference survival function S_0(t) = \exp\{-(\lambda t)^k\} for given shape and rate parameters.

Usage

S0_weibull(t, k, lambda)

Arguments

Details

This function can be used as a baseline survival model within the transformed analysis framework. It is also directly accessible to users for defining custom reference survival functions.

Value

A numeric vector of survival probabilities S_0(t).

Examples

S0_weibull(c(0, 5, 10), k = 1.2, lambda = 0.08)

Bayesian Interim and Final Analysis (Unified Transformed Time Framework)

Description

Performs Bayesian analysis using the transformed proportional hazards model. By default, observed follow-up times are assumed to be on the original time scale and are transformed internally through the reference survival function S_0. Transformed times can also be supplied directly.

Usage

conduct(
  data,
  current.n,
  nmax,
  tau,
  theta_L,
  a0,
  b0,
  pIA,
  pF,
  S0_dist = c("exp", "weibull", "lognormal", "loglogistic", "custom"),
  S0_par = list(lambda = 0.05),
  S0_fun = NULL,
  time_scale = c("raw", "transformed")
)

Arguments

Value

A named list with the following components:

Current.sample.size

Integer. The analysis sample size supplied via current.n.

Posterior.shape

Numeric. Posterior Gamma shape parameter a_0 + \sum \Delta_i.

Posterior.rate

Numeric. Posterior Gamma rate parameter b_0 + \sum W_i, where W_i = -\log S_0(X_i) when time_scale = "raw".

Posterior tail probability (Pr >= threshold)

Numeric. Posterior probability \Pr(\delta \ge \delta_{\text{goal}} \mid \text{data}) used for the Go/No-Go or efficacy decision.

Posterior mean of survival rate

Numeric. Posterior mean of the survival probability at \tau, mapped back to the original survival scale via S_0(\tau)^\delta.

95% credible interval of survival rate

Numeric vector of length 2. Lower and upper bounds of the posterior credible interval for the survival probability at \tau.

Decision

Character. Interim decision ("Go (Continue)" or "No-Go (Stop for futility)") when current.n < nmax, or final decision ("Efficacious" or "Not Efficacious") when current.n >= nmax.

Examples

dat <- data.frame(Time = c(5, 10, 15, 8, 20), Status = c(1, 0, 1, 1, 0))
conduct(dat, current.n = 5, nmax = 30, tau = 24, theta_L = 0.62,
        a0 = 0.01, b0 = 0.01, pIA = 0.5, pF = 0.05,
        S0_dist = "weibull", S0_par = list(k = 1.2, lambda = 0.08))

Convert target EFS goal to delta parameter under proportional hazards model

Description

Converts a target event-free survival (EFS) probability at a given time \tau to the corresponding \delta_{\text{goal}} parameter under the proportional hazards assumption, where S(t) = S_0(t)^{\delta}.

Usage

delta_from_theta_goal(theta_goal, tau, S0_fun, S0_par = NULL)

Arguments

Details

This function is used to translate a survival probability goal into the corresponding delta threshold under the transformed model framework.

Value

A numeric value giving the corresponding \delta_{\text{goal}}.

Examples

# Example: Convert an EFS goal of 0.62 at tau = 24
delta_from_theta_goal(
  theta_goal = 0.62,
  tau = 24,
  S0_fun = S0_weibull,
  S0_par = list(k = 1.2, lambda = 0.08)
)

Search for feasible interim analysis thresholds (Unified Framework)

Description

Performs grid search over interim sample sizes (N_w) and time offsets (X), identifying feasible posterior probability thresholds (p_IA) for early futility stopping. Uses unified transformed time framework.

Usage

find_Nw_pIA(
  tau,
  theta_L,
  theta_alt,
  alpha_target,
  beta_target,
  rate,
  X_grid,
  num_grid = 20,
  p_H0 = 0.4,
  p_H1 = 0.1,
  nsim = 10000,
  S0_dist = c("exp", "weibull", "lognormal", "loglogistic", "custom"),
  a0 = 0.01,
  b0 = 0.01,
  S0_par = list(lambda = 0.05),
  S0_fun = NULL,
  pIA_grid = seq(0.01, 0.99, by = 0.01),
  seed = 1234,
  method = "landmark",
  drop_na = TRUE
)

Arguments

Value

A data frame with one row per candidate (N_w, X) pair and the following columns:

Nw

Integer. Interim-stage enrollment target used to trigger the waiting window.

X

Numeric. Additional waiting time after enrollment of the N_w-th subject before the interim analysis.

pIA

Numeric. Smallest feasible futility threshold identified on pIA_grid for this (N_w, X) combination.

piF_H0

Numeric. Estimated probability under H_0 that the trial stops for futility at interim using the selected pIA.

piF_H1

Numeric. Estimated probability under H_1 that the trial stops for futility at interim using the selected pIA.

Rows with no feasible pIA are removed when drop_na = TRUE.

Examples

find_Nw_pIA(
  tau = 24, theta_L = 0.62, theta_alt = 0.80,
  alpha_target = 0.05, beta_target = 0.20,
  rate = 5/12, X_grid = c(1, 2),
  nsim = 500, S0_dist = "exp",
  seed = 123
)

Evaluate operating characteristics for two-stage adaptive survival designs (Unified Framework)

Description

Simulates operating characteristics (OC) using unified transformed time framework. All internal calculations use transformed times. Output times are reported in original scale.

Time Metrics (all in original time scale):

• E_time_IA_H0/H1: Expected time to interim analysis (unconditional mean, always occurs).

• E_time_FA_H0/H1: Expected time to final analysis conditional on reaching FA (i.e., mean over trials that did not stop early at IA).

• E_follow_H0: Expected total follow-up time under H0 (in original time scale).

Usage

oc_two_stage(
  N,
  Nw,
  X,
  pIA,
  pF,
  rate,
  tau,
  theta_L,
  theta_alt,
  a0,
  b0,
  nsim = 2000,
  S0_dist = c("exp", "weibull", "lognormal", "loglogistic", "custom"),
  S0_par = list(lambda = 0.05),
  S0_fun = NULL,
  S0_inv_fun = NULL,
  seed = NULL,
  method = "landmark"
)

Arguments

Value

A named list with estimated operating characteristics:

alpha

Numeric. Estimated Type I error under H_0.

power

Numeric. Estimated power under H_1.

ESP_H0

Numeric. Early stopping probability at interim under H_0.

ESP_H1

Numeric. Early stopping probability at interim under H_1.

ESS_H0

Numeric. Expected total number of enrolled subjects under H_0, accounting for interim stopping.

E_event_H0

Numeric. Expected number of observed events under H_0.

E_event_H1

Numeric. Expected number of observed events under H_1.

E_follow_H0

Numeric. Expected total observed follow-up under H_0, on the original time scale.

max_n_total_H0

Numeric. Maximum realized sample size under H_0.

mean_n_between

Numeric. Mean number of subjects enrolled between the N_w-th enrollment and the interim analysis under H_0.

median_n_between

Numeric. Median number of subjects enrolled between the N_w-th enrollment and the interim analysis under H_0.

mean_fu_between

Numeric. Mean observed follow-up, on the original time scale, among subjects enrolled between the N_w-th enrollment and the interim analysis under H_0.

median_fu_between

Numeric. Median observed follow-up, on the original time scale, among subjects enrolled between the N_w-th enrollment and the interim analysis under H_0.

E_time_IA_H0

Numeric. Expected calendar time to the interim analysis under H_0.

E_time_FA_H0

Numeric or NA. Expected calendar time to the final analysis under H_0, conditional on reaching final analysis.

E_time_IA_H1

Numeric. Expected calendar time to the interim analysis under H_1.

E_time_FA_H1

Numeric or NA. Expected calendar time to the final analysis under H_1, conditional on reaching final analysis.

Examples

oc_two_stage(
  N = 40, Nw = 20, X = 2, pIA = 0.5, pF = 0.05,
  rate = 5/12, tau = 24, theta_L = 0.62, theta_alt = 0.80,
  a0 = 0.01, b0 = 0.01, nsim = 500,
  S0_dist = "exp", seed = 123
)

Run Two-Stage Bayesian Single-Arm Survival Trial Simulation

Description

Simulates a two-stage Bayesian adaptive single-arm survival trial. Performs an interim analysis after the first-stage sample (N_w) and decides whether to continue to the final analysis (N_{max}) based on a Bayesian posterior decision rule.

Usage

run_two_stage_trial(
  seed = NULL,
  tau,
  theta_L,
  theta_true,
  a0 = 0.01,
  b0 = 0.01,
  rate,
  Nw,
  Nmax,
  X,
  pIA,
  pF,
  dist = c("exp", "weibull", "lognormal", "loglogistic"),
  dist_par = list(lambda = 0.05, k = 1.2),
  model = "exp",
  method = "landmark",
  verbose = TRUE
)

Arguments

Details

The function simulates accrual and event times for all N_{max} patients, performs an interim analysis using the first N_w patients, and, if the posterior probability is below pIA, continues to final analysis. At the final stage, all patients (including interim ones) are followed up to \tau and analyzed again using the same Bayesian decision rule.

The internal analysis relies on the conduct() function for posterior inference.

Value

A named list describing one simulated trial trajectory:

data_interim

Data frame for the interim analysis cohort. Columns are Time (observed raw follow-up), Status (event indicator), and Time_transformed (reference transformed time for the same records).

data_final

Data frame for the final analysis cohort, with the same columns as data_interim, or NULL if the trial stopped at interim.

result_interim

Named list returned by conduct() for the interim analysis.

result_final

Named list returned by conduct() for the final analysis, or NULL if the trial stopped at interim.

accrual_times

Numeric vector of calendar enrollment times for all simulated subjects.

event_times

Numeric vector of true event times generated under the chosen data-generating distribution.

method

Character. Administrative censoring method actually used in the simulation ("landmark" or "hr").

Examples

run_two_stage_trial(
  seed = 123,
  tau = 12,
  theta_L = 0.4,
  theta_true = 0.6,
  a0 = 0.01, b0 = 0.01,
  rate = 0.5,
  Nw = 20, Nmax = 40,
  X = 3,
  pIA = 0.2, pF = 0.05,
  dist = "weibull",
  dist_par = list(k = 1.2, lambda = 0.08),
  method = "landmark",
  verbose = FALSE
)

Compute transformed statistics for survival data

Description

Computes the sufficient statistics (d, U) used in the transformed survival model framework, where:

• d = \sum \Delta_i is the total number of observed events, and

• U = \sum -\log(S_0(X_i)) is the cumulative transformed time using the reference survival function S_0(t).

Usage

stats_transformed(X, Delta, S0_fun, S0_par)

Arguments

Details

This function allows users to derive model-specific posterior parameters for transformed analyses, given observed follow-up times and event indicators.

Value

A named list with components:

d

Integer. Total number of observed events d = \sum \Delta_i.

U

Numeric. Total transformed follow-up U = \sum -\log\{S_0(X_i)\}. This is the exposure term that enters the Gamma posterior update for \delta.

Examples

# Example with Weibull baseline
times <- c(5, 8, 12)
events <- c(1, 0, 1)
stats_transformed(times, events, S0_fun = S0_weibull, S0_par = list(k = 1.2, lambda = 0.08))

Optimize two-stage adaptive survival design

Description

Searches for optimal two-stage adaptive survival designs based on simulated operating characteristics and user-defined optimality criteria.

Usage

two_stage_optimize_design(
  NwX_pIA_results,
  rate,
  tau,
  theta_L,
  theta_alt,
  a0,
  b0,
  alpha_target,
  beta_target,
  nsim = 2000,
  S0_dist = c("exp", "weibull", "lognormal", "loglogistic", "custom"),
  S0_par = list(lambda = 0.05),
  S0_fun = NULL,
  S0_inv_fun = NULL,
  tol = 0.01,
  max_iter = 25,
  pF_lo = 0.01,
  pF_hi = 0.99,
  ncores = max(1, parallel::detectCores() - 1),
  seed = 1234,
  optimize = c("followup", "ESS", "minimax"),
  method = "landmark",
  verbose = TRUE
)

Arguments

Details

The function evaluates candidate combinations of interim sample size (N_w), offset time (X), and total sample size (N) using Monte Carlo simulation, and identifies the design that satisfies Type I / II error constraints while minimizing a specified optimization criterion.

Each candidate design is simulated using oc_two_stage(). For each combination of N_w, X, and N, the function performs a binary search over the final posterior threshold pF to satisfy:

\text{power} \ge 1 - \beta_{\text{target}}, \quad \alpha \le \alpha_{\text{target}}.

The design with the smallest selected optimization metric under H0 is reported as optimal.

Seed consistency with find_Nw_pIA(): For each (N_w, X) combination, the seed passed to oc_two_stage() is derived as seed + Nw * 997L + round(X * 1000) * 13L, matching the sub-seed formula used in find_Nw_pIA(). This ensures that the early stopping probability (ESP_H0) reported here is comparable to the piF_H0 from find_Nw_pIA() when the same seed is used. To reproduce the OC of the best design independently, call oc_two_stage(..., seed = best$seed_used).

Value

A list with two components:

all

Data frame of all evaluated candidate designs. Each row corresponds to one feasible combination of (N_w, X, p_{IA}, N, p_F) together with its simulated operating characteristics. Columns include design parameters (Nw, X, pIA, N, pF), reproducibility metadata (seed_used), error-rate summaries (alpha, power, ESP_H0, ESP_H1), resource summaries (ESS_H0, E_event_H0, E_event_H1, E_follow_H0, max_n_total_H0), interim-gap summaries (mean_n_between, median_n_between, mean_fu_between, median_fu_between), calendar-time summaries (E_time_IA_H0, E_time_FA_H0, E_time_IA_H1, E_time_FA_H1), and a logical feasibility flag feasible.

best

One-row data frame giving the optimal feasible design under the requested optimize criterion. This row has the same columns as all. Pass best$seed_used back to oc_two_stage() to reproduce the reported operating characteristics exactly. Returns NULL if no feasible design is found.

Examples

res_pIA <- find_Nw_pIA(
  tau = 24, theta_L = 0.62, theta_alt = 0.80,
  alpha_target = 0.05, beta_target = 0.20,
  rate = 5/12, X_grid = 1,
  num_grid = 3, nsim = 100,
  pIA_grid = seq(0.1, 0.9, by = 0.2),
  S0_dist = "exp", seed = 123
)

opt <- two_stage_optimize_design(
  NwX_pIA_results = res_pIA,
  rate = 5/12, tau = 24,
  theta_L = 0.62, theta_alt = 0.80,
  a0 = 0.01, b0 = 0.01,
  alpha_target = 0.05, beta_target = 0.20,
  nsim = 100, S0_dist = "exp",
  optimize = "ESS",
  ncores = 1, seed = 123, verbose = FALSE
)
opt$best