AHTauDesign 1.0

Prospective Trial Planning for Average Hazard Estimands

AHTauDesign is an R package for simulation-based prospective planning of average hazard (AH) estimands in two-arm time-to-event clinical trials.

The package implements a calibrate–freeze–audit–decide–reverse-design workflow, linking a clinically preferred AH horizon to the trial design expected to support it.

A key principle is that information support and statistical power are distinct. A clinical horizon may be adequately supported without achieving a prespecified power target.

Main Features

• Calibration and freeze: Evaluate information-support rules under repeated null simulations and freeze a selected rule before prospective planning.
• Stage 1 audit: Evaluate whether the reference trial design supports the clinically preferred AH horizon.
• Conditional Stage 2 selection: After Stage 1 failure, identify supported alternatives within a prespecified clinically acceptable window.
• Independent evaluation: Compare the clinical and selected horizons using fresh simulations, including the signed power_difference.
• Part II reverse design: Determine sample-size requirements for a fixed horizon and target power using coarse search, fine localization, and independent validation.
• Planning reports: Assemble support, power, horizon decisions, and validation records into an auditable planning report.

A passing clinical horizon is retained without optimization. Selecting an alternative horizon changes the estimand and does not automatically imply a clinical recommendation.

Installation

To install the development version from a local package directory:

# Run from the AHTauDesign package root
devtools::install(".")

After version 1.0 is published on CRAN, it can be installed using:

install.packages("AHTauDesign")

Quick Start

The following synthetic example illustrates the public simulation interface and Stage 1 audit.

library(AHTauDesign)

trial_generator <- function(N, A, F, rate_C, rate_T) {
  arm <- rep(c(0, 1), each = N / 2)
  entry <- runif(N, 0, A)
  event_time <- rexp(
    N, rate = ifelse(arm == 0, rate_C, rate_T)
  )
  censor_time <- A + F - entry

  data.frame(
    arm = arm,
    X = pmin(event_time, censor_time),
    status = as.numeric(event_time <= censor_time)
  )
}

# Load the frozen rule from the bundled synthetic example.
# These thresholds are for illustration only.
example_file <- system.file(
  "extdata", "getting-started-results.rds",
  package = "AHTauDesign",
  mustWork = TRUE
)
frozen <- readRDS(example_file)$reference$frozen_rule

# Simulate a reference design
raw <- simulate_design(
  trial_generator = trial_generator,
  n_sim = 100,
  tau_grid = c(24, 36),
  trial_args = list(
    N = 160,
    A = 48,
    F = 36,
    rate_C = -log(0.60) / 36,
    rate_T = 0.55 * (-log(0.60) / 36)
  ),
  scenario_id = "reference",
  seed = 202611
)

# Apply the frozen support rule
audit <- stage1_audit(
  raw,
  thresholds = frozen$thresholds
)

audit$scenario_summary

The simulation count in this quick example is intentionally small. Reliable planning assessments require an appropriate number of simulations and setting-specific calibration or validation.

Complete Planning Workflow

The package provides the following principal functions:

• simulate_calibration_null()
• freeze_support_rule()
• simulate_design()
• stage1_audit()
• stage2_select()
• stage2_evaluate()
• find_n_req()
• planning_report()

For a complete worked example covering calibration, horizon auditing, conditional selection, independent evaluation, and reverse design, see:

vignette("getting-started", package = "AHTauDesign")

Scope and Interpretation

AHTauDesign is intended for prospective, simulation-based planning. Horizon selection should take place before observed treatment outcomes are used for analysis.

The numerical support thresholds used in the accompanying manuscript are specific to its calibration setting and should not be treated as universal cutoffs.

Changing the AH horizon changes the treatment-effect estimand. Additional follow-up and increased sample size are distinct design resources and should be considered separately from changing the clinical question.

License

GPL-3.