run_null_calibration: Run Null Calibration Simulation

View source: R/calibrate_null_correction.R

run_null_calibrationR Documentation

Run Null Calibration Simulation

Description

Runs ForestSearch under the null hypothesis at multiple sample sizes to calibrate L_{\text{eff}}, then returns a calibration object for predicting corrected FPR.

Usage

run_null_calibration(
  sim_null_fn,
  fs_args,
  d_eff_fn,
  N_values = c(200, 500, 1000),
  c1 = 1.25,
  c2 = 1,
  n_sims = 100L,
  prop_harm = 0.3,
  n_min = 60L,
  seed_base = 42L,
  verbose = TRUE
)

Arguments

sim_null_fn

Function. Generates one H0 dataset. Signature: sim_null_fn(n, seed) returning a data.frame suitable for forestsearch().

fs_args

Named list. Arguments passed to forestsearch() (excluding df.analysis, hr.threshold, hr.consistency, and seedit, which are set by the wrapper).

d_eff_fn

Function. Computes d_{\text{eff}} for a subgroup. Signature: d_eff_fn(n_sg) returning numeric. Example: function(n) d_eff_binary(n, 0.30).

N_values

Integer vector. Sample sizes to simulate. At least 2 required. Default: c(200, 500, 1000).

c1

Numeric. Screening threshold for calibration. Default: 1.25.

c2

Numeric. Consistency threshold for calibration. Default: 1.0.

n_sims

Integer. Simulations per sample size. Default: 100.

prop_harm

Numeric. Expected proportion in harm subgroup (for computing d_eff). Default: 0.30.

n_min

Integer. Minimum subgroup size. Default: 60.

seed_base

Integer. Base seed. Default: 42.

verbose

Logical. Print progress. Default: TRUE.

Details

For each N in N_values, the function:

  1. Generates n_sims datasets via sim_null_fn()

  2. Runs forestsearch() on each

  3. Computes the simulated FPR = proportion with any H found

  4. Computes P_1 via the GLM approximation

  5. Calls calibrate_L_eff() to fit the power-law model

ForestSearch is run with parallel_args = list(plan = "sequential") to avoid nested parallelism. The outer simulation loop is sequential. For faster execution, wrap in foreach %dofuture% externally.

Value

An "leff_calibration" object.

Examples


# Binary DGM under H0
sim_null <- function(n, seed) {
  set.seed(seed)
  data.frame(
    id = seq_len(n),
    treat = rbinom(n, 1, 0.5),
    bm1 = as.factor(rbinom(n, 1, 0.70)),
    bm2 = as.factor(rbinom(n, 1, 0.50)),
    age = round(rnorm(n, 55, 10)),
    ecog = as.factor(sample(0:1, n, TRUE, c(0.6, 0.4))),
    progressed = rbinom(n, 1, 0.30)
  )
}

fs_args <- list(
  confounders.name = c("bm1", "bm2", "age", "ecog"),
  outcome.name = "progressed",
  event.name = "progressed",
  treat.name = "treat",
  id.name = "id",
  outcome_type = "binary",
  effect_measure = "OR",
  adverse_outcome = TRUE,
  pconsistency.threshold = 0.90,
  fs.splits = 200,
  n.min = 60,
  maxk = 2,
  use_lasso = FALSE,
  use_grf = FALSE,
  use_twostage = TRUE,
  is.RCT = TRUE,
  details = FALSE,
  plot.sg = FALSE,
  parallel_args = list(plan = "sequential",
                       workers = 1,
                       show_message = FALSE)
)

# Illustrative size only (the function requires n_sims >= 10 and at least
# two N values); a calibration for use takes n_sims of 50 or more over the
# trial sizes of interest.
cal <- run_null_calibration(
  sim_null_fn = sim_null,
  fs_args = fs_args,
  d_eff_fn = function(n) d_eff_binary(n, 0.30),
  N_values = c(200, 500),
  n_sims = 10,
  verbose = TRUE
)
print(cal)



forestsearch documentation built on Nov. 15, 2026, 9:06 a.m.