suggest_thresholds: Suggest Screening and Consistency Thresholds

View source: R/suggest_thresholds.R

suggest_thresholdsR Documentation

Suggest Screening and Consistency Thresholds

Description

Recommends (c1, c2) threshold pairs for ForestSearch based on the corrected null approximation. Uses the per-subgroup detection probability and an L_{\text{eff}} multiplicity correction to find the smallest c1 (screening threshold) such that the corrected FPR is at most fpr_target.

Usage

suggest_thresholds(
  d_eff,
  N,
  fpr_target = 0.1,
  n_min = 60,
  L_eff_C = 1,
  L_eff_alpha = 0,
  c1_range = c(1.05, 2.5),
  c1_step = 0.05,
  c2_candidates = seq(0.9, 2, by = 0.05),
  effect_scale = c("ratio", "difference")
)

Arguments

d_eff

Numeric. Effective information in the expected harm subgroup. Use d_eff_survival, d_eff_binary, d_eff_count, or d_eff_continuous.

N

Integer. Total sample size.

fpr_target

Numeric. Maximum acceptable procedure-level FPR. Default: 0.10.

n_min

Integer. Minimum subgroup size. Default: 60.

L_eff_C

Numeric. Calibration constant for L_{\text{eff}} = C (N/n_{\min})^\alpha. Default: 1.0 (conservative; see Details).

L_eff_alpha

Numeric. Calibration exponent. Default: 0.0 (no N-dependence; see Details).

c1_range

Numeric vector of length 2. Search range for c1. Default: c(1.05, 2.50).

c1_step

Numeric. Grid step for c1. Default: 0.05.

c2_candidates

Numeric vector. Candidate c2 values to evaluate for each c1. Default: seq(0.90, 2.0, by = 0.05).

effect_scale

Character. "ratio" (default) or "difference".

Details

The corrected FPR is:

\text{FPR}_{\text{corr}} = 1 - (1 - P_1)^{L_{\text{eff}}}

where P_1 = compute_detection_probability_glm(1.0, d_eff, c1, c2) and L_{\text{eff}} = C (N / n_{\min})^\alpha.

Default L_eff values (C=1, alpha=0) assume L_{\text{eff}} = 1, which gives the per-subgroup approximation with no multiplicity correction. This is appropriate when:

  • No calibration data is available

  • The analysis has few confounders and small N

For more accurate suggestions, calibrate L_{\text{eff}} from an H0 simulation using calibrate_L_eff or run_null_calibration.

Reference calibrations (from the forestsearch GLM extension analysis documents):

Binary, 4 confounders

C = 0.220, alpha = 1.298 (binary_threshold_calibration.qmd, 5000 sims)

GBSG survival, 7 confounders

C = 0.029, alpha = 0.882 (cox_vs_glm_approximation.qmd, 500 sims per N)

Value

A data.frame with columns:

c1

Screening threshold.

min_c2

Minimum consistency threshold achieving the target.

FPR_corr

Corrected FPR at this (c1, min_c2).

P1

Per-subgroup detection probability.

L_eff

Effective number of candidates at this N.

Sorted by c1 ascending. The first row is the smallest c1 that achieves the target FPR.

See Also

compute_detection_probability_glm, calibrate_L_eff, predict_fpr_corrected

Examples


# Survival: paper defaults should be recovered
d <- d_eff_survival(n_sg = 60, prop_cens = 0.45)
suggest_thresholds(d_eff = d, N = 700)

# Binary: needs higher thresholds (shown, not run -- about 10 s)
# d <- d_eff_binary(n_sg = 150, p_event = 0.30)
# suggest_thresholds(d_eff = d, N = 500,
#                    L_eff_C = 0.220, L_eff_alpha = 1.298)

# Use calibration object from run_null_calibration()
# cal <- run_null_calibration(...)
# suggest_thresholds(d_eff = d, N = 700,
#                    L_eff_C = cal$C, L_eff_alpha = cal$alpha)



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