build_estimation_table: Build Estimation Properties Table from Simulation Results

View source: R/simulation_tables.R

build_estimation_tableR Documentation

Build Estimation Properties Table from Simulation Results

Description

Constructs a publication-quality gt table summarizing estimation properties for hazard ratios in the identified subgroup and its complement. The layout mirrors Table 5 of Leon et al. (2024), showing average estimate, empirical SD, min, max, and relative bias for each estimator.

Usage

build_estimation_table(
  results,
  dgm,
  analysis_method = "FSlg",
  n_boots = NULL,
  digits = 2,
  title = "Estimation Properties",
  subtitle = NULL,
  font_size = 12,
  cde_H = NULL,
  cde_Hc = NULL,
  subgroup_notation = c("harm", "benefit"),
  trim_threshold = 1000,
  trim_fraction = 0.01
)

Arguments

results

data.table or data.frame. Simulation results from run_simulation_analysis, optionally enriched with bootstrap bias-corrected columns (hr.H.bc, hr.Hc.bc).

dgm

DGM object. Used for true parameter values (hr_H_true, hr_Hc_true, and AHR truth via get_dgm_hr).

analysis_method

Character. Which analysis method to tabulate (e.g., "FSlg"). Default: "FSlg".

n_boots

Integer or NULL. Number of bootstraps. When non-NULL, appended to the subtitle as "(B = n_boots bootstraps)". Default: NULL.

digits

Integer. Decimal places. Default: 2.

title

Character. Table title.

subtitle

Character or NULL. Optional user-supplied subtitle text. Auto-populated statistics (method, estimable count, proportion) are always shown. When non-NULL, the custom text is displayed first with stats appended in parentheses, e.g. "My title (FSlg: 18/20 (90%) estimable)".

font_size

Numeric. Font size in pixels for table text. Default: 12. Increase to 14 or 16 for larger display.

cde_H

Numeric or NULL. Controlled direct effect (theta-ddagger(H)) for the true harm subgroup. When non-NULL, an additional b-ddagger bias column is shown. When NULL (default), auto-detected from dgm$cde_H or dgm$hazard_ratios$CDE_harm.

cde_Hc

Numeric or NULL. Controlled direct effect for the complement. Auto-detected analogously.

subgroup_notation

Character. "harm" (default) labels subgroups as H/Hc; "benefit" labels as G/Gc for benefit-search analyses (treatment switching).

trim_threshold

Numeric or NULL. When the raw mean of an estimator's values exceeds this absolute value, that row's Avg / SD / Min / Max are recomputed on the central 1 - 2 * trim_fraction of estimates, and a small footnote marker is placed on the row's Avg cell. The Estimator label is left unchanged so the Unicode notation (e.g., \hat\theta(\hat Q)) renders normally; only the Avg cell carries the trim indicator. Set NULL to disable trimming entirely. Default: 1000 (a value typical simulation results will never approach unless a small subgroup produces a degenerate effect estimate).

trim_fraction

Numeric in (0, 0.5). Fraction of estimates to trim from each tail (per row) when trimming triggers. Default: 0.01 (lower and upper 1\ used). Has no effect when trim_threshold = NULL.

Details

Uses the paper's notation conventions:

  • theta-dagger: Marginal (causal) HR truth

  • theta-ddagger: Controlled direct effect (CDE) truth

  • theta-hat(H-hat): Plugin Cox estimate in identified subgroup

  • theta-hat*(H-hat): Bootstrap bias-corrected estimate

Includes both Cox-based HR and AHR (Average Hazard Ratio from loghr_po) estimators when AHR columns are present in the results.

For each subgroup (H and Hc) the function reports:

  • Avg: Mean of the estimates across estimable simulations.

  • SD: Empirical standard deviation.

  • Min / Max: Range.

  • b-dagger: Relative bias (percent) vs marginal truth, 100 * (Avg - theta_dagger) / theta_dagger.

  • b-ddagger (conditional): Relative bias (percent) vs CDE truth, shown when CDE values are available.

When bootstrap-corrected columns (hr.H.bc, hr.Hc.bc) are present in results, an additional bias-corrected row (theta-hat*(H-hat)) is added per subgroup.

When AHR columns (ahr.H.hat, ahr.Hc.hat) are present, AHR estimation rows are appended using the DGM's true AHR values for relative bias calculation.

When CDE columns (cde.H.hat, cde.Hc.hat) are present and CDE truth values are available, CDE estimation rows (theta-ddagger(H-hat)) are appended. The b-dagger column for CDE rows reports bias relative to the CDE truth rather than the marginal HR.

Value

A gt table object, or NULL if no estimable realizations exist.

See Also

build_classification_table, format_oc_results, get_dgm_hr

Examples

## Not run: 
# Basic usage (marginal truth only)
build_estimation_table(
  results = results_alt,
  dgm = dgm_calibrated,
  analysis_method = "FSlg"
)

# With CDE truth (full Table 5 alignment)
build_estimation_table(
  results = results_alt,
  dgm = dgm_calibrated,
  cde_H = 2.25,
  cde_Hc = 0.60
)

## End(Not run)


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