Package {AHTauDesign}

Classify Calibration Reliability

Description

Classify calibration settings as Reliable, Unreliable, or Indeterminate using Monte Carlo confidence intervals for Type I error, coverage, and support availability.

Usage

classify_calib_reliability(
  diagnostic,
  type1_tolerance = 0.06,
  coverage_tolerance = 0.94,
  support_tolerance = 0.95,
  availability_lower_column = "p_support_lower",
  availability_upper_column = "p_support_upper"
)

Arguments

Value

A data frame containing component classifications and overall reliability status.

Count Calibration Reliability Classifications

Description

Summarize the numbers of Reliable, Unreliable, and Indeterminate calibration settings.

Usage

count_calib_reliability(status_results)

Arguments

Details

Also report Pass, Fail, and Indeterminate counts for each reliability component.

Value

A one-row data frame containing overall and component-specific classification counts.

Evaluate Candidate Calibration Support Rules

Description

Evaluate candidate Stage 1 support rules against the reliability classifications of calibration settings.

Usage

evaluate_calib_rules(status_results, rules, availability_column = "p_support")

Arguments

Details

Calculate conservative and optimistic unsafe-pass rates, the confirmed adequate-pass rate, and identify rules producing equivalent Pass/Not-Pass classifications.

Value

A list containing performance, a data frame of rule-level operating characteristics, and pass_matrix, the Pass/Not-Pass classification matrix.

Part II Reverse Design for Average Hazard

Description

Determine the required sample size for a fixed AH horizon and additional follow-up duration.

Usage

find_n_req(
  F_followup,
  tau,
  thresholds,
  trial_args = list(),
  trial_generator,
  N_lower = 100,
  N_upper = 600,
  coarse_step = 20,
  fine_step = 10,
  n_coarse,
  n_fine,
  n_validate,
  power_target = 0.8,
  search_seed,
  validation_seed,
  alpha = 0.05
)

Arguments

Details

The procedure uses coarse search, fine localization, and independent validation. Final feasibility requires Stage 1 support and isotonic-stabilized overall power meeting the target.

Value

A list containing the required sample size, search status, coarse and fine results, independent validation results, complete search trace, and settings.

Freeze a Calibrated Stage 1 Support Rule

Description

Evaluate support-based calibration diagnostics using the existing reliability and candidate-rule functions, validate an explicitly selected rule, and save its thresholds and calibration evidence for subsequent planning.

Usage

freeze_support_rule(
  diagnostic,
  rules,
  rule_id,
  rationale,
  calibration_scope,
  provenance,
  simulation_settings,
  type1_tolerance = 0.06,
  coverage_tolerance = 0.94,
  support_tolerance = 0.95
)

Arguments

Details

Reliability is recomputed with classify_calib_reliability() using p_support_lower and p_support_upper, summarized with count_calib_reliability(), and evaluated with evaluate_calib_rules() using p_support. Supplied reliability labels are not trusted. Numerical-only availability (p_numeric) is not used. Simulation denominators and interval calculations are unchanged. Each diagnostic row retains equal weight.

A candidate qualifies only when its conservative unsafe-pass rate (UPR) is defined and at most 0.05. This rate is the number of passing Unreliable plus Indeterminate settings divided by all passing settings. Among qualifying candidates, the confirmed adequate-pass rate (APR) must be maximized: passing Reliable settings divided by all Reliable settings. A candidate with no passing settings has undefined UPR and is ineligible; no Reliable settings means APR is undefined and freezing stops.

All qualifying maximizers and full Pass/Not-Pass patterns are preserved. Exact APR equality is used, as every candidate has the same Reliable-setting denominator. Interpretability or parsimony can justify an explicit choice among equivalent maximizing rules, but cannot override UPR or APR criteria. If maximizers have different patterns, freezing stops with their IDs and pattern IDs for review. No statistical tie-breaker is introduced.

The selected rule must include an absolute risk-count requirement. Rules without one (including Family A) remain in the candidate evaluation, but cannot be frozen for the current three-criterion Stage 1 interface. No absolute threshold is invented. Thresholds are always read from the selected row; the manuscript values 0.10, 10, and 0.95 are not universal defaults.

Supply frozen$thresholds as the thresholds argument to stage1_audit() and find_n_req(). Freeze the rule before applying Stage 1 or Part II and keep the thresholds fixed throughout subsequent planning. This function does not run Part II, assess power, or implement a planning report.

Value

An S3 object of class ahtau_support_rule, containing:

rule_id, rule_family, family, rationale

The explicit selection and explanation. rule_family is the selected family label; family retains the same label for compatibility with earlier frozen objects.

thresholds

A list named p_risk_min, n_risk_min, and p_support_min, compatible with Stage 1 and Part II.

selected_rule, selected_performance

The selected candidate row and its evaluated performance.

performance, pass_matrix

Unmodified output from the existing evaluator for every candidate, including classification pattern IDs and equivalent rule IDs. Pass-matrix rows follow diagnostic row order.

diagnostic, reliability_counts

The classified diagnostics and their overall and component reliability counts.

selection

Eligible and maximizing rule IDs, the selected pattern ID, and equivalent rule IDs. Pattern IDs are labels, not ranks.

reliability_criteria

Reliability tolerances, the conservative UPR limit, support-column mappings, and inference conditioning.

calibration_scope, provenance, simulation_settings

Supplied design space and reproducibility metadata, retained unchanged.

Examples

# Small illustrative diagnostics, not a manuscript calibration reproduction.
diagnostic <- data.frame(
  scenario_id = c("design_a", "design_b"), tau = c(3, 4),
  min_mean_p_risk = c(0.25, 0.04), min_mean_n_risk = c(25, 4),
  p_support = c(0.99, 0.80),
  p_support_lower = c(0.97, 0.77), p_support_upper = c(1, 0.83),
  type1_one_lower = c(0.03, 0.07), type1_one_upper = c(0.05, 0.10),
  coverage_lower = c(0.95, 0.88), coverage_upper = c(0.98, 0.92)
)
diagnostic$total_sim_n <- 1000
diagnostic$n_support_valid <- c(990, 800)
rules <- data.frame(
  rule_id = c("relative_010", "relative_015"), rule_family = c("B", "B"),
  p_risk_threshold = c(0.10, 0.15), n_risk_threshold = c(8, 8),
  p_support_threshold = c(0.95, 0.95), use_absolute_n = c(TRUE, TRUE)
)
frozen <- freeze_support_rule(
  diagnostic, rules, rule_id = "relative_015",
  rationale = "Equivalent maximizing patterns; selected for interpretability.",
  calibration_scope = list(horizons = c(3, 4), design = "illustrative"),
  provenance = list(source = "example", inference_conditioning = "support_valid"),
  simulation_settings = list(source = "constructed diagnostics, no simulation")
)
frozen$thresholds
frozen$selection$maximizing_rule_ids
# stage1_audit(raw_results, thresholds = frozen$thresholds)
# find_n_req(..., thresholds = frozen$thresholds)

Create an Average-Hazard Trial Planning Report

Description

Assemble an auditable planning record from previously computed AHTauDesign results. No simulations, average-hazard estimation, horizon optimization, or sample-size searches are performed by this function.

Usage

planning_report(
  trial_spec,
  frozen_rule,
  stage1_result,
  stage2_result = NULL,
  stage2_evaluation = NULL,
  part2_results = NULL,
  simulation_diagnostics = list()
)

Arguments

Details

The supplied frozen thresholds are used only for a consistency check against Stage 1 decisions; no classification is changed. Information support and overall power remain distinct. A passing clinical horizon is retained, and Stage 2 is reported only following support failure. Missing optional analyses are labeled as not supplied, never simulated.

The returned object retains the original computational results. Use 'print(report)' for a readable console summary, 'saveRDS(report, "report.rds")' to save all evidence, or 'writeLines(capture.output(print(report)), "report.txt")' for a text file.

Value

An object of class 'ahtau_planning_report' with the trial specification, frozen rule, supplied analyses, Stage 1/Stage 2 decision, Part II requirement table, simulation diagnostics, and time of creation.

Examples

## Not run: 
# After frozen <- freeze_support_rule(...) and
# audit <- stage1_audit(..., thresholds = frozen$thresholds):
report <- planning_report(
  trial_spec = list(scenario_id = "reference", N = 120, A = 48,
                    F = 18, tau_clin = 36, power_target = 0.80),
  frozen_rule = frozen, stage1_result = audit
)
print(report)
saveRDS(report, "report.rds")

## End(Not run)

Print an Average-Hazard Planning Report

Description

Print an Average-Hazard Planning Report

Usage

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

Arguments

Value

The report, invisibly.

Simulate Null Trials for Average-Hazard Support Calibration

Description

Simulate a prespecified set of null trial designs, analyze every candidate horizon on the same generated trial within each replicate, and summarize repeated-sampling support and inferential performance. The trial generator must represent the null hypothesis of equal average hazards (log AH ratio zero) at the candidate horizons; this scientific assumption is supplied by the caller, not checked by the function.

Usage

simulate_calibration_null(
  design_space,
  trial_generator,
  tau_grid,
  n_sim,
  seed,
  trial_args = list(),
  alpha = 0.05,
  mc_conf_level = 0.95,
  rules = NULL,
  reliability_criteria = NULL
)

Arguments

Details

AH estimates, standard errors, one-sided rejections, and observed risk sets are computed by the existing evaluate_tau_grid() function; it is not modified. For numerically valid results, the additional covered indicator is calculated from the two-sided 95 percent Wald interval ⁠theta_hat +/- qnorm(0.975) * SE_theta⁠, checking inclusion of zero.

Numerical validity requires finite theta_hat and SE_theta, with SE_theta > 0. Support validity additionally requires n_risk_C > 0 and n_risk_T > 0. The diagnostic summary uses all attempted trials for arm-specific mean risk sets and support availability; Type I error and Wald coverage are calculated only among support-valid trials. Exact binomial Monte Carlo intervals retain those same denominators. A failed AH fit is retained as an attempted analysis with unavailable inference.

Optional reliability and candidate-rule comparisons explicitly use the p_support point estimate and its Monte Carlo interval, not p_numeric. The output's diagnostic is directly compatible with freeze_support_rule(), which must be called separately with explicit candidate selection and provenance. Neither Stage 1 thresholds nor a frozen support rule are supplied by this simulation function.

Value

A list containing:

raw_results

One row per attempted scenario, replicate, and horizon. Includes ci_lower, ci_upper, covered, numeric_valid, tail_support, and support_valid in addition to Stage 1 outputs.

diagnostic

The result of summarize_calibration_support(), with counts, proportions, support-conditional inferential metrics, and exact Monte Carlo intervals.

design_space, settings

The trial design space and simulation specification, including seed, RNG kind, horizon grid, and levels.

classified_diagnostic, reliability_counts, rule_evaluation

Only when rules and reliability_criteria are provided: the existing reliability classifier, reliability counts, and candidate-rule performance/pass matrix.

See Also

summarize_calibration_support(), freeze_support_rule()

Examples

null_trial <- function(N, A, F, rate) {
  arm <- rep(c(0, 1), each = N / 2)
  entry <- stats::runif(N, 0, A)
  event_time <- stats::rexp(N, rate)
  censor_time <- A + F - entry
  data.frame(arm = arm, X = pmin(event_time, censor_time),
             status = as.numeric(event_time <= censor_time))
}
null_designs <- data.frame(
  scenario_id = c("small", "large"), N = c(40, 80),
  A = 24, F = c(12, 24), rate = 0.03
)
## Not run: 
sim <- simulate_calibration_null(
  design_space = null_designs, trial_generator = null_trial,
  tau_grid = c(12, 18), n_sim = 1000, seed = 1234
)
sim$diagnostic
# Supply trial-specific candidate rules and use freeze_support_rule()
# separately, after evaluating candidate-rule performance.

## End(Not run)

Simulate Planning Trials Across Average-Hazard Horizons

Description

Generate repeated two-arm trials using a caller-supplied trial generator and evaluate all prespecified average-hazard horizons on the same observed trial within each replicate. Return raw results for stage1_audit().

Usage

simulate_design(
  trial_generator,
  n_sim,
  tau_grid,
  trial_args = list(),
  scenario_id = "reference",
  seed,
  alpha = 0.05
)

Arguments

Details

Unlike simulate_calibration_null(), this function is for planning scenarios under the caller's working treatment-effect model; it does not calculate calibration reliability, freeze support thresholds, or select a horizon.

For each replicate, the generator runs once and its observed data are passed to the package-internal evaluate_tau_grid() for every horizon. The underlying AH estimator, test direction, and risk-set calculations are unchanged. An AH fit that cannot be estimated remains in the output with missing inference values; it is not silently excluded. Invalid trial data or generator errors stop the simulation instead of dropping a replicate.

To perform independent Stage 2 evaluation, call simulate_design() again with a different seed and freshly generated trials. The generator should not reset the random seed internally. Independence depends on the supplied data-generating process and cannot be guaranteed by different seeds alone.

Value

A data frame containing one row per attempted replicate and horizon. Columns include scenario_id, sim_id, tau, theta_hat, SE_theta, n_risk_C, n_risk_T, p_risk_C, p_risk_T, and reject. Pass this data frame directly to stage1_audit(raw_results, thresholds).

See Also

stage1_audit(), simulate_calibration_null()

Examples

example_trial <- function(N, A, F, rate_C, rate_T) {
  arm <- rep(c(0, 1), each = N / 2)
  entry <- stats::runif(N, 0, A)
  event <- stats::rexp(N, rate = ifelse(arm == 0, rate_C, rate_T))
  censor <- A + F - entry
  data.frame(arm = arm, X = pmin(event, censor),
             status = as.numeric(event <= censor))
}
raw <- simulate_design(
  trial_generator = example_trial, n_sim = 2,
  tau_grid = c(12, 24), seed = 123,
  trial_args = list(N = 60, A = 48, F = 12,
                    rate_C = -log(0.60) / 36,
                    rate_T = -log(0.72) / 36)
)
head(raw)
# audit <- stage1_audit(raw, thresholds = frozen$thresholds)

Stage 1 Information Support Audit

Description

Evaluate whether candidate AH horizons satisfy a prespecified information support rule.

Usage

stage1_audit(raw_results, thresholds)

Arguments

Value

A list containing replicate_results and scenario_summary.

Independent Evaluation of a Stage 2 Alternative

Description

Compare the clinically preferred horizon and the selected planning alternative using independent evaluation results.

Usage

stage2_evaluate(selection_result, eval_summary)

Arguments

Details

This function summarizes independently simulated results. It does not generate new simulations.

Value

A list containing:

eval_summary

Independent evaluation results for the clinical and selected horizons.

power_difference

Overall power at the selected horizon minus overall power at the clinical horizon. The difference may be positive or negative.

Stage 2 Conditional Horizon Selection

Description

Retain the clinical horizon when Stage 1 is passed. Otherwise, identify a supported alternative within the prespecified clinically acceptable window using the manuscript's utility and tie-breaking rules.

Usage

stage2_select(stage1_summary, tau_clin, clinical_window)

Arguments

Value

A list containing candidate_summary and final_decision_summary.

Summarize Support-Based Null Calibration Results

Description

Summarize repeated null-trial analyses for each design-and-horizon setting. Numerical validity requires a finite log average-hazard ratio and finite, positive analytic standard error. Support validity additionally requires at least one participant at risk in both trial arms at the horizon.

Usage

summarize_calibration_support(raw_results, conf_level = 0.95)

Arguments

Details

Risk-set means and support availability use all attempted trials. Type I error and coverage are conditional on support-valid trials. Exact two-sided binomial confidence intervals use the observed counts and denominators.

Value

A data frame containing risk-set means, numerical and support availability, conditional one-sided Type I error and coverage, their exact confidence intervals, and simulation counts for each setting.