View source: R/fpr_calibration.R
| fpr_calibration | R Documentation |
Estimates the procedure-level false-positive rate (FPR) for a
forestsearch analysis at a specific (c_1, c_2)
threshold pair by running nsims null simulations. No power-law
model or threshold-independence assumption is required.
fpr_calibration(
c1,
c2,
df.analysis = NULL,
fs_params = list(),
nsims = 200L,
nsims_verify = 0L,
null_fn = NULL,
n_sample = NULL,
n_min = 60L,
outcome_type_approx = NULL,
d_eff_approx = NULL,
prop_cens = 0,
p_event = 0.5,
sigma_y = 1,
sim_seed = 42L,
n_workers = 1L,
quiet = FALSE
)
c1 |
Numeric scalar. The screening threshold on a candidate
subgroup's own effect. |
c2 |
Numeric scalar. The per-split effect threshold. |
df.analysis |
Data frame. The analyst's dataset. Used directly in
permutation mode; also used to extract N for the per-subgroup
approximation. Can be |
fs_params |
Named list. All forestsearch() arguments except
|
nsims |
Integer. Number of null replicates. Default 200.
At FPR ~ 10%, |
nsims_verify |
Integer. Number of independent verification
replicates. Uses a separate seed range from the calibration batch
to provide an honest check of the corrected FPR. Default 0 (skip
verification). Set to |
null_fn |
Function or |
n_sample |
Integer or |
n_min |
Integer. Minimum subgroup size for the per-subgroup
approximation |
outcome_type_approx |
Character. One of |
d_eff_approx |
Numeric or |
prop_cens |
Numeric. Censoring proportion for survival outcomes.
Used only when |
p_event |
Numeric. Event probability for binary outcomes.
Used only when |
sigma_y |
Numeric. Residual SD for continuous outcomes. Default 1. |
sim_seed |
Integer. Base random seed. Each replicate uses
|
n_workers |
Integer. Parallel workers for the foreach loop.
Default 1 (sequential). Set to |
quiet |
Logical. Suppress progress messages. Default |
Two null-generation modes are supported:
null_fn providedEach replicate draws a fresh null dataset
from null_fn(seed). Use this when you have a parametric data
generating mechanism (DGM) or want to mimic a specific study design.
df.analysis only (permutation mode)Each replicate
permutes the treatment column within the analyst's actual dataset.
This preserves the observed covariate and outcome distributions and
is the natural H0 reference for a real analysis. Requires the
treat.name column to be present in df.analysis.
Under the null hypothesis of no subgroup heterogeneity, the treatment
assignment is exchangeable with the observed outcomes. Permuting
treat.name within each replicate breaks any true treatment-by-
subgroup interaction while preserving the marginal distributions of all
other variables. This is a model-free H0 reference that adapts
automatically to the actual dataset structure.
The asymptotic per-subgroup P_1 at (c1, c2) is computed
via compute_detection_probability_glm() using the effective
information d_{\text{eff}} at n.min. The ratio
L_{\text{eff}} = \log(1 - \hat{\text{FPR}}) / \log(1 - P_1)
is the implied multiplicity factor specific to this threshold pair and
dataset — it replaces the universal power-law model and does not assume
threshold-independence.
An object of class "fpr_calibration" with components:
fprNumeric. Estimated procedure-level FPR.
fpr_ciNumeric vector of length 2. 95% Wilson CI.
n_foundInteger. Number of replicates where a subgroup was found.
nsimsInteger. Total replicates attempted.
n_failedInteger. Replicates that errored.
P1Numeric. Per-subgroup approximation P_1 at
(c1, c2).
d_effNumeric. Effective information used for P_1.
L_eff_impliedNumeric. Implied L_{\text{eff}} from
the simulation result: \log(1 - \text{FPR}) / \log(1 - P_1).
c1, c2Numeric. The threshold pair.
NInteger. Sample size.
modeCharacter. "permutation" or "dgm".
call_argsList. Key call arguments for reproducibility.
forestsearch,
compute_detection_probability_glm,
d_eff_binary, d_eff_survival
## Not run:
# ---- Binary example (permutation mode) ----
set.seed(1)
df <- data.frame(
id = 1:500, treat = rbinom(500, 1, 0.5),
bm1 = as.factor(rbinom(500, 1, 0.7)),
bm2 = as.factor(rbinom(500, 1, 0.5)),
age = round(rnorm(500, 55, 10)),
y = rbinom(500, 1, 0.30) # null: no treatment effect
)
fs_params <- list(
confounders.name = c("bm1", "bm2", "age"),
outcome.name = "y", event.name = "y",
treat.name = "treat", id.name = "id",
outcome_type = "binary", effect_measure = "OR",
adverse_outcome = TRUE,
pconsistency.threshold = 0.90, fs.splits = 400,
n.min = 60, maxk = 2,
use_lasso = TRUE, use_grf = TRUE,
is.RCT = TRUE, details = FALSE, quiet = TRUE,
parallel_args = list(plan = "sequential", workers = 1)
)
res <- fpr_calibration(
c1 = 1.70, c2 = 1.70,
df.analysis = df,
fs_params = fs_params,
nsims = 200,
n_min = 60, outcome_type_approx = "binary", p_event = 0.30,
sim_seed = 42, n_workers = 4
)
print(res)
## End(Not run)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.