calibrate_lambda_grid: Single-stage lambda calibration for one borrowing method

In fdb: Frequentist Dynamic Borrowing for Hybrid-Control Survival Trials

Single-stage lambda calibration for one borrowing method

Description

For each lambda in lambda_grid, simulates nsim replicates under each drift value in drift_set (with \theta_0 = 0), records the model-based and sandwich rejection rates, and selects the largest lambda whose worst-case rejection rate over the drift set does not exceed alpha_cal. Missing statistics are excluded from descriptive rejection rates, but a candidate with incomplete results is ineligible for the affected inference type. Fitting failures generate a diagnostic warning; if both inference types have no usable results at a drift, calibration stops.

Usage

calibrate_lambda_grid(
  method = c("Li", "P1", "P2", "P3", "P4"),
  lambda_grid,
  scenario_base,
  drift_set,
  nsim = 300,
  alpha = 0.025,
  alpha_cal = alpha,
  seed = 1,
  parallel = FALSE,
  ncores = NULL,
  robust = FALSE,
  eps = SMOOTH_EPS,
  gamma_li = 1,
  gate_c = 1.64,
  gate_tau = 0.25,
  gamma_mcp = 3,
  delta_bounds = DEFAULT_DELTA_BOUNDS,
  n_grid_opt = DEFAULT_N_GRID_OPT,
  early_stop_drift = FALSE,
  stop_rule = c("point", "upper95"),
  select_rule = c("point", "upper95"),
  rho_mcp = DEFAULT_RHO_MCP
)

Arguments

method	One of "Li", "P1", "P2", "P3", "P4".
lambda_grid	Numeric vector of candidate lambda values.
scenario_base	A scenario list as accepted by run_simulation. Its theta0 and delta0 are overwritten internally.
drift_set	Numeric vector of drift values (log HR) on which to evaluate type I error.
nsim	Number of replicates per drift value.
alpha	Nominal level used for rejection decisions.
alpha_cal	Calibration threshold (worst-case rejection rate must not exceed this).
seed	RNG seed.
parallel	Logical; enable parallel evaluation across replicates.
ncores	Number of workers; NULL uses two. Checks use at most two.
robust	Use robust (Lin-Wei) Cox SEs.
eps	Smoothing parameter.
gamma_li	Adaptive lasso exponent.
gate_c, gate_tau	P2 gate parameters.
gamma_mcp	MCP shape parameter for P3.
delta_bounds	Optimization interval for delta.
n_grid_opt	Coarse-grid points for non-convex objectives.
early_stop_drift	Logical; if TRUE, drop lambda values that have already failed the calibration constraint after evaluating a subset of drift values.
stop_rule	Either "point" (use point estimate of worst-case rejection rate for early stopping) or "upper95" (use the Monte Carlo 95% upper confidence bound).
select_rule	Selection rule for the final calibrated lambda (same options as stop_rule).
rho_mcp	MCP transition fraction in (0, 1), default 0.1.

Value

A list with elements method, details (per-lambda x drift), summary (per-lambda worst-case), calibration_table (long format), and lambda_star (selected lambdas for both inference types).

Examples

# Tiny execution example; use substantially more replicates for calibration.
cal <- calibrate_lambda_grid(method = "P1",
                             lambda_grid = c(0.05, 0.2),
                             scenario_base = scenario_S1,
                             drift_set = make_drift_set_from_values(
                               c(1.0, 1.1)),
                             nsim = 2, seed = 1)
cal$lambda_star

fdb documentation built on Oct. 4, 2026, 5:07 p.m.