--- title: "Reproducing the Paper's Numerical Results" author: "Se Yoon Lee" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Reproducing the Paper's Numerical Results} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r setup, include=FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>", fig.width = 7, fig.height = 4.6, fig.align = "center" ) ``` ```{r load-package} library(RCTCovAdj) ``` ## Reproducibility map The paper contains three numerical components. Here RCT denotes randomized controlled trial. 1. four Monte Carlo experiments with analytic variance benchmarks; 2. an analysis of postoperative throat-pain scores from a licorice-gargle RCT; 3. deterministic power and total-sample-size calculations under two planning laws. In method labels, DIM denotes the unadjusted difference in means, ANCOVA denotes common-slope analysis of covariance, and ANHECOVA-IF denotes interacted analysis of heterogeneous covariance with joint influence-function inference. CF denotes cross-fitting. HC0 and HC2 denote the heteroskedasticity-consistent type 0 coefficient sandwich and type 2 leverage correction, respectively. `RCTCovAdj` separates original inputs, executable code, and derived results. The simulation laws and the aggregate simulation and study-design results are installed with the package. Neither the licorice-gargle trial records nor results derived from them are distributed. A user with the required permission and an authorized local copy can verify that file before running the real-data analysis. ## Simulation laws In every case, \[ X\sim N(0,1),\quad A\sim\operatorname{Bernoulli}(\pi),\quad \varepsilon\sim N(0,1), \] independently, and \[ Y=0.5A+\{b_0+(b_1-b_0)A\}X+c(X^2-1)+\varepsilon. \] The marginal mean difference is $0.5$. The installed case table records the four parameter combinations and the scientific role of each design. ```{r case-table} data("simulation_cases", package = "RCTCovAdj") simulation_cases ``` The designs isolate nonlinear additive prognosis, heterogeneous slopes under balanced allocation, the same slopes under unequal allocation, and opposing slopes whose optimally weighted prognostic signal cancels. For these laws, the analytic variance factors are \[ \begin{aligned} V_U&=\frac{1+b_1^2+2c^2}{\pi} +\frac{1+b_0^2+2c^2}{1-\pi},\\ V^*&=(b_1-b_0)^2+\frac{1}{\pi}+\frac{1}{1-\pi},\\ V_{\mathrm{ANH}}&=V_U- \frac{\{(1-\pi)b_1+\pi b_0\}^2}{\pi(1-\pi)},\\ V_{\mathrm{ANC}}&=V_{\mathrm{ANH}}+ \frac{(2\pi-1)^2(b_1-b_0)^2}{\pi(1-\pi)}. \end{aligned} \] Here $V_U$ is the variance factor for DIM, $V^*$ is the semiparametric efficiency bound, $V_{\mathrm{ANH}}$ is the factor for interacted linear adjustment, and $V_{\mathrm{ANC}}$ is the factor for common-slope ANCOVA. The Oracle method uses the true treatment-specific conditional means and therefore has variance factor $V^*$. The cross-fitted quadratic method has the same first-order factor in these four laws because its feature span contains the conditional means. `rct_variance_factors()` evaluates the displayed expressions and also reports the coefficient-only HC2 variance limit. ```{r analytic-benchmarks} with( simulation_cases[simulation_cases$case == "A", ], rct_variance_factors( allocation = pi, beta_control = b0, beta_treatment = b1, quadratic = quad, noise_variance = 1 ) ) ``` ## A short executable check `simulate_rct_case()` generates one trial from a named law. Setting the seed makes the example reproducible. ```{r one-dataset} trial_a <- simulate_rct_case(case = "A", n = 200L, seed = 123L) str(trial_a) rct_adjust( outcome = trial_a$outcome, treatment = trial_a$treatment, covariates = trial_a["x"], allocation = 0.5, methods = c("unadjusted", "ancova", "interacted") ) ``` The quadratic term is absent from the analysis of covariance (ANCOVA) and interacted fits, so their linear span cannot attain the semiparametric bound in Case A. A cross-fitted quadratic learner includes the missing prognostic direction. ```{r one-dataset-crossfit} rct_crossfit( outcome = trial_a$outcome, treatment = trial_a$treatment, covariates = trial_a["x"], allocation = 0.5, learner = "quadratic", folds = 2L, seed = 456L ) ``` ## Full Monte Carlo experiment The paper used sample sizes 200 and 800, 4,000 independent replications in each case--sample-size cell, and master seed 20260903. Distinct L'Ecuyer combined multiple-recursive random-number streams make the cells reproducible without sharing streams. The full experiment creates 32,000 trial datasets and is deliberately excluded from vignette evaluation. ```{r full-simulation, eval=FALSE} full_output_dir <- tempfile("rctcovadj-full-") full_files <- reproduce_paper_simulations( output_dir = full_output_dir, reps = 4000L, sample_sizes = c(200L, 800L), seed = 20260903L ) unlink(full_output_dir, recursive = TRUE) ``` This example removes its temporary output directory after the run. To retain the files, choose an explicit permanent destination and omit the cleanup call. For a fast installation check, reduce the number of replications. Such a run checks code paths and file structure; it is too small for scientific Monte Carlo conclusions. ```{r quick-simulation, eval=FALSE} quick <- run_paper_simulations( reps = 32L, sample_sizes = 200L, seed = 20260903L ) ``` Complete aggregate summaries from the 4,000-replication run are included for direct inspection. Replicate-level output is created when the full experiment is rerun with `keep_replicates = TRUE`. ```{r archived-results} data("paper_population_benchmarks", package = "RCTCovAdj") data("paper_simulation_results", package = "RCTCovAdj") head(paper_population_benchmarks) head(paper_simulation_results) ``` The simulation figures can be rebuilt from the installed aggregate summaries without rerunning the Monte Carlo experiment. In the efficiency figure, $S_B^2$ is the empirical variance of the estimates across replications, so the vertical axis is $nS_B^2/V^*$. Filled circles and vertical bars show the $n=800$ empirical ratios and their 95% Monte Carlo intervals; open diamonds show the corresponding first-order ratios. The short axis label ANH-IF denotes ANHECOVA-IF, and Oracle denotes adjustment with the true conditional means. ```{r simulation-figure, fig.width=7.1, fig.height=5.2, dev.args=list(pointsize=13.5), fig.alt="Four panels show empirical root-n variance relative to the semiparametric efficiency bound for six estimators in Cases A through D. Filled circles have vertical 95 percent Monte Carlo intervals, and open diamonds show first-order theory.", fig.cap="Empirical variance relative to the semiparametric bound at n=800. Bars are 95% Monte Carlo intervals for the empirical ratios; open diamonds are the first-order ratios."} plot_simulation_results( results = paper_simulation_results, benchmarks = paper_population_benchmarks, metric = "efficiency" ) ``` The empirical points fluctuate around the analytic limits. Equality is not expected in a finite Monte Carlo run. Comparisons should use the stored Monte Carlo standard errors, especially when two methods have similar variance. ## Postoperative throat-pain analysis The package distributes no trial record, aggregate table, estimate, or figure derived from the licorice-gargle data. The source portal states that permission from the data contributor or corresponding author is required before the data are used in a new publication. Installing `RCTCovAdj` grants no right to analyze, publish, or redistribute the records or derived output. After obtaining the required permission, an authorized source file can be verified and analyzed as follows: ```{r restricted-trial-analysis, eval=FALSE} source_data <- read_licorice_data(file.choose()) trial_results <- analyze_licorice(source_data) trial_results$estimates plot_licorice_results(trial_results) ``` `read_licorice_data()` rejects a file whose fingerprint or structure does not match the documented source. This guard prevents an unrelated object with the same file name from silently entering the analysis. Permission to obtain and use the data and its derived output remains the user's responsibility. The optional `medicaldata` package supplies a source-format copy through a separate distribution. Its availability does not establish permission for a proposed use. A user whose permission covers that copy may construct the reviewed analysis object and run the same calculation: ```{r medicaldata-trial-analysis, eval=FALSE} source_data <- prepare_licorice_data() trial_results <- analyze_licorice(source_data) ``` This preparation route does not grant permission to analyze, publish, or redistribute the participant records or derived output. The returned object contains the aggregate estimates, working standard errors, bounded-score completion analysis, diagnostics, and model coefficients generated from the authorized local file. These outputs remain local unless the user's permission allows their publication or redistribution. ## Power and sample-size application The design application is deterministic. It uses analytic variance factors, a marginal planning effect of 0.5, and a two-sided level-0.05 normal-reference test. No Monte Carlo result enters the calculation. ```{r design-results} data("paper_power_design_results", package = "RCTCovAdj") paper_power_design_results ``` The same table and power curves can be regenerated from the package functions. ```{r rebuild-design, fig.alt="Two-panel normal-approximation power curves under balanced nonlinear Case A and unequal-allocation Case C, comparing unadjusted, interacted, and efficient quadratic or pooled ANCOVA analyses; symbols mark 80 percent power.", fig.cap="Normal-approximation power under planning Cases A and C. Symbols mark the smallest integer total sample sizes attaining 80% power for each analysis."} recomputed_design <- paper_power_design() recomputed_design$sample_sizes plot_power_design(recomputed_design) ``` Integer sample sizes are rounded upward after the continuous normal approximation is inverted. They are total randomized sample sizes before any inflation for attrition. Reproduction of the arithmetic does not validate the planning law for a new trial; its variance inputs still require scientific justification. ## Standalone replication scripts The package installs three command-line scripts for rebuilding the simulation, power, and authorized-data analyses. Their installed location can be found without relying on a machine-specific path. ```{r replication-scripts} replication_dir <- system.file("replication", package = "RCTCovAdj") list.files(replication_dir, pattern = "[.]R$") ``` Each script requires an explicit output directory, and the licorice analysis also requires the path to an authorized source file. The `README.md` in the same directory documents the command-line arguments. Every workflow also writes session information and SHA-256 and MD5 checksums. For example, a short simulation check can be launched from a terminal with ``` Rscript --vanilla run_simulations.R --quick --output=/path/to/results ``` after changing to the installed replication directory. The full simulation omits `--quick` and uses the article's 4,000 replications per cell. ## Recommended audit sequence A compact audit proceeds in the following order: 1. inspect `simulation_cases` and recompute the population variance factors; 2. compare the installed aggregate summaries in `paper_simulation_results` with those analytic benchmarks; 3. rerun a small simulation to check the local software environment; 4. run the 4,000-replication experiment only when the full archive must be rebuilt; 5. after obtaining permission, verify and analyze the authorized local trial file and inspect the generated aggregate output; and 6. rebuild the deterministic power and sample-size results separately from the Monte Carlo study. This sequence distinguishes exact population calculations, stochastic Monte Carlo evidence, restricted source data, and deterministic study-design calculations. That distinction is necessary for a reproducibility audit because the four objects have different sources of uncertainty. ## References Lee, S. Y. (2026). *Semiparametric Efficiency Theory for Covariate Adjustment in Randomized Controlled Trials*. Manuscript. Ruetzler, K., Fleck, M., Nabecker, S., Pinter, K., Landskron, G., Lassnigg, A., You, J., and Sessler, D. I. (2013). A randomized, double-blind comparison of licorice versus sugar-water gargle for prevention of postoperative sore throat and postextubation coughing. *Anesthesia & Analgesia*, 117, 614--621. . Nowacki, A. S. (2017). *Licorice Gargle Dataset*. TSHS Resources Portal. .