| Title: | Covariate Adjustment for Randomized Controlled Trials |
|---|---|
| Description: | Implements covariate-adjusted estimation and inference for marginal mean differences in two-arm randomized controlled trials with continuous outcomes. Methods include the unadjusted difference in means, common-slope analysis of covariance, interacted standardization with joint influence-function inference, and cross-fitted augmentation. The package also provides analytic power and sample-size calculations, reproducible simulation designs, and article replication workflows, including tools for verifying and analyzing an authorized local trial-data file. The adjustment methods build on Tsiatis et al. (2008) <doi:10.1002/sim.3113> and Lin (2013) <doi:10.1214/12-AOAS583>. |
| Authors: | Se Yoon Lee [aut, cre, cph] |
| Maintainer: | Se Yoon Lee <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.1.0 |
| Built: | 2026-09-25 15:14:15 UTC |
| Source: | https://github.com/cran/RCTCovAdj |
RCTCovAdj implements estimation, inference, simulation, and prospective design calculations for marginal mean differences in two-arm randomized controlled trials with continuous outcomes.
rct_adjust() computes unadjusted, common-slope, and interacted estimates.
rct_crossfit() computes cross-fitted augmented estimates.
rct_power() and rct_sample_size() connect variance to trial design.
run_paper_simulations() reproduces the article's Monte Carlo study.
analyze_licorice() implements the real-data analysis for an authorized
copy of the licorice-gargle trial records.
The package distributes neither the trial records nor results derived from them. Data access, analysis, publication, and redistribution require the permission of the relevant data rights holder.
Maintainer: Se Yoon Lee [email protected] [copyright holder]
Reproduces the observed-score analyses and the bounded two-score completion
exercise in the article. The function analyzes the 233 stored records with
observed 30-minute throat-pain scores. It then assigns every requested pair
of values to the two unavailable scores among all 235 stored records and
refits DIM (difference in means), ANCOVA-HC0 (common-slope analysis of
covariance with heteroskedasticity-consistent type 0 inference),
ANHECOVA-joint-IF (interacted standardization with joint influence-function
inference), and ANHECOVA-coefficient-HC2 (the coefficient-only type 2
diagnostic).
analyze_licorice(data, completion_values = 0:10)analyze_licorice(data, completion_values = 0:10)
data |
The verified or prepared 235-record analysis data frame. |
completion_values |
Nonempty numeric vector of distinct finite values used for each unavailable score. |
The returned normal-reference intervals are working calculations. They do not recover the participant absent from the file, identify the effect among all 236 randomized participants without additional assumptions, or adjust for the trial's interim monitoring.
An object of class "licorice_analysis" containing estimates, outcome summaries, baseline summaries, the completion grid and ranges, model diagnostics, arm-specific coefficients, and the underlying adjustment object.
# Synthetic records illustrate the analysis; these are not trial results. set.seed(42) n <- 235L d <- data.frame( participant_id = seq_len(n), tx = rep(0:1, c(117, 118)), age_bl = runif(n, 18, 80), bmi_bl = runif(n, 20, 35), gender = factor(sample(0:1, n, replace = TRUE), levels = 0:1, labels = c("0. Female", "1. Male")), asa_physical_status_bl = factor(sample(1:3, n, replace = TRUE), levels = 1:3, labels = c("1. Healthy", "2. Mild Systemic Disease", "3. Severe Systemic Disease")), mallampati_bl = factor(sample(1:3, n, replace = TRUE), levels = 1:3, labels = c("1. 1", "2. 2", "3. 3+")), pacu_30_min_throat_pain = sample(0:10, n, replace = TRUE) ) d$pacu_30_min_throat_pain[c(1, 118)] <- NA # Four completions keep this example short; the full grid uses 0:10. result <- analyze_licorice(d, completion_values = c(0, 10)) result$estimates# Synthetic records illustrate the analysis; these are not trial results. set.seed(42) n <- 235L d <- data.frame( participant_id = seq_len(n), tx = rep(0:1, c(117, 118)), age_bl = runif(n, 18, 80), bmi_bl = runif(n, 20, 35), gender = factor(sample(0:1, n, replace = TRUE), levels = 0:1, labels = c("0. Female", "1. Male")), asa_physical_status_bl = factor(sample(1:3, n, replace = TRUE), levels = 1:3, labels = c("1. Healthy", "2. Mild Systemic Disease", "3. Severe Systemic Disease")), mallampati_bl = factor(sample(1:3, n, replace = TRUE), levels = 1:3, labels = c("1. 1", "2. 2", "3. 3+")), pacu_30_min_throat_pain = sample(0:10, n, replace = TRUE) ) d$pacu_30_min_throat_pain[c(1, 118)] <- NA # Four completions keep this example short; the full grid uses 0:10. result <- analyze_licorice(d, completion_values = c(0, 10)) result$estimates
Exact variance factors and projection slopes for the four simulation laws.
paper_population_benchmarkspaper_population_benchmarks
A data frame with 4 rows and 13 variables: case labels and parameters, unadjusted variance VU, efficiency bound Vstar, interacted linear variance Vlinear, pooled analysis of covariance (ANCOVA) variance Vancova, coefficient-only heteroskedasticity-consistent type 2 (HC2) variance limit Vhc2_limit, and the optimal and pooled slopes.
Calculated analytically from simulation_cases.
Builds the article's deterministic two-sided normal-approximation calculations for simulation Cases A and C. The result contains the planning table and power curves for the analyses compared in each case.
paper_power_design( effect = 0.5, alpha = 0.05, target_powers = c(0.8, 0.9), n_grid = seq.int(20L, 1600L) )paper_power_design( effect = 0.5, alpha = 0.05, target_powers = c(0.8, 0.9), n_grid = seq.int(20L, 1600L) )
effect |
Planning marginal mean difference. |
alpha |
Two-sided type I error probability. |
target_powers |
Target powers used for sample-size calculations. |
n_grid |
Total sample sizes used to construct power curves. |
An object of class "rct_power_design" with components sample_sizes, curves, and settings.
design <- paper_power_design(n_grid = seq(50, 1200, by = 10)) design$sample_sizesdesign <- paper_power_design(n_grid = seq(50, 1200, by = 10)) design$sample_sizes
Exact two-sided normal-approximation calculations for analytic Cases A and C at a marginal mean difference of 0.5 and level 0.05.
paper_power_design_resultspaper_power_design_results
A data frame with 6 rows and 12 variables, including the variance factor, relative variance, smallest total sample sizes attaining 80 and 90 percent power, achieved powers after rounding, and power at total sample sizes 300, 500, and 800.
Calculated by paper_power_design().
Aggregate results from 4,000 replications in each of four cases and two
sample sizes. Replicate-level records are omitted from the package because
they can be regenerated with run_paper_simulations().
paper_simulation_resultspaper_simulation_results
A data frame with 56 rows and 23 variables. It contains the case, sample size, allocation probability, method, replication count, bias and its Monte Carlo standard error, empirical and estimated standard errors, coverage, normalized variance summaries, population limits, and numerical safeguard counts.
Generated by the article's simulation workflow with master seed 20260903 and L'Ecuyer-CMRG random-number streams.
Draws the observed score distribution by assigned arm alongside the three distinct mean-difference estimates, their working intervals, and the two-score completion ranges.
plot_licorice_results(x, ...)plot_licorice_results(x, ...)
x |
A result from |
... |
Unused. |
The input object, invisibly.
# Entirely fabricated aggregate values, not results from the trial. distribution <- expand.grid(score = 0:10, arm = 0:1) distribution$arm_label <- rep(c("Sugar", "Licorice"), each = 11) distribution$count <- c(8, 2, rep(0, 9), 9, 1, rep(0, 9)) distribution$n_observed <- 10 distribution$proportion <- distribution$count / 10 methods <- c("DIM", "ANCOVA-HC0", "ANHECOVA-joint-IF") x <- list( outcome_distribution = distribution, estimates = data.frame(method = methods, estimate = c(-0.10, -0.12, -0.11), lower_working = c(-0.40, -0.39, -0.37), upper_working = c(0.20, 0.15, 0.15)), completion_summary = data.frame(method = methods, min_estimate = c(-0.20, -0.22, -0.21), max_estimate = c(0.00, -0.02, -0.01)) ) figure <- tempfile(fileext = ".pdf") grDevices::pdf(figure, width = 7, height = 3.2) tryCatch(plot_licorice_results(x), finally = grDevices::dev.off()) unlink(figure)# Entirely fabricated aggregate values, not results from the trial. distribution <- expand.grid(score = 0:10, arm = 0:1) distribution$arm_label <- rep(c("Sugar", "Licorice"), each = 11) distribution$count <- c(8, 2, rep(0, 9), 9, 1, rep(0, 9)) distribution$n_observed <- 10 distribution$proportion <- distribution$count / 10 methods <- c("DIM", "ANCOVA-HC0", "ANHECOVA-joint-IF") x <- list( outcome_distribution = distribution, estimates = data.frame(method = methods, estimate = c(-0.10, -0.12, -0.11), lower_working = c(-0.40, -0.39, -0.37), upper_working = c(0.20, 0.15, 0.15)), completion_summary = data.frame(method = methods, min_estimate = c(-0.20, -0.22, -0.21), max_estimate = c(0.00, -0.02, -0.01)) ) figure <- tempfile(fileext = ".pdf") grDevices::pdf(figure, width = 7, height = 3.2) tryCatch(plot_licorice_results(x), finally = grDevices::dev.off()) unlink(figure)
Plots the two-sided normal-approximation power curves and target-power sample
sizes for Cases A and C in an object returned by paper_power_design().
plot_power_design( x = paper_power_design(), target_power = 0.8, colors = c(unadjusted = "#333333", interacted = "#0072B2", efficient = "#009E73", pooled = "#D55E00"), ... )plot_power_design( x = paper_power_design(), target_power = 0.8, colors = c(unadjusted = "#333333", interacted = "#0072B2", efficient = "#009E73", pooled = "#D55E00"), ... )
x |
An object returned by |
target_power |
Horizontal reference power. |
colors |
Named colors for the three curves in each panel. |
... |
Additional graphical parameters passed to |
The input object, invisibly.
design <- paper_power_design(n_grid = seq(50, 1200, by = 10)) figure <- tempfile(fileext = ".pdf") grDevices::pdf(figure, width = 7, height = 3.4) tryCatch(plot_power_design(design), finally = grDevices::dev.off()) unlink(figure)design <- paper_power_design(n_grid = seq(50, 1200, by = 10)) figure <- tempfile(fileext = ".pdf") grDevices::pdf(figure, width = 7, height = 3.4) tryCatch(plot_power_design(design), finally = grDevices::dev.off()) unlink(figure)
Plots archived or newly generated simulation summaries as either empirical variance relative to the semiparametric bound or confidence-interval coverage, together with the corresponding analytic benchmarks.
plot_simulation_results( results = NULL, benchmarks = NULL, metric = c("efficiency", "coverage"), sample_size = 800L, ... )plot_simulation_results( results = NULL, benchmarks = NULL, metric = c("efficiency", "coverage"), sample_size = 800L, ... )
results |
A simulation summary data frame or an object returned by
|
benchmarks |
Population benchmark data. With NULL, the packaged analytic benchmarks are used. |
metric |
Either "efficiency" or "coverage". |
sample_size |
Sample size displayed in the efficiency plot. |
... |
Unused. |
The supplied results, invisibly.
figure <- tempfile(fileext = ".pdf") grDevices::pdf(figure, width = 7.1, height = 5.2) tryCatch( plot_simulation_results( paper_simulation_results, paper_population_benchmarks, metric = "efficiency" ), finally = grDevices::dev.off() ) unlink(figure)figure <- tempfile(fileext = ".pdf") grDevices::pdf(figure, width = 7.1, height = 5.2) tryCatch( plot_simulation_results( paper_simulation_results, paper_population_benchmarks, metric = "efficiency" ), finally = grDevices::dev.off() ) unlink(figure)
Converts the source-format licorice-gargle data distributed by the optional medicaldata package into the analysis-ready structure used by the article. This function does not distribute participant records. Users must review the source data terms and obtain any permission required for their intended use.
prepare_licorice_data(data = NULL)prepare_licorice_data(data = NULL)
data |
A source-format data frame. When NULL, the function retrieves licorice_gargle from the installed medicaldata package. |
The 25-column analysis-ready data frame used by
analyze_licorice().
Ruetzler K, Fleck M, Nabecker S, et al. (2013). A randomized, double-blind comparison of licorice versus sugar-water gargle for prevention of postoperative sore throat and postextubation coughing. Anesthesia & Analgesia, 117(3), 614-621. doi:10.1213/ANE.0b013e318299a650
# Synthetic records illustrate the required source format, not trial results. set.seed(42) n <- 235L source_data <- data.frame( preOp_gender = sample(0:1, n, replace = TRUE), preOp_asa = sample(1:3, n, replace = TRUE), preOp_calcBMI = runif(n, 20, 35), preOp_age = sample(18:80, n, replace = TRUE), preOp_mallampati = sample(1:4, n, replace = TRUE), preOp_smoking = sample(1:3, n, replace = TRUE), preOp_pain = sample(0:1, n, replace = TRUE), treat = rep(0:1, c(117, 118)), intraOp_surgerySize = sample(1:3, n, replace = TRUE), extubation_cough = sample(0:3, n, replace = TRUE), pacu30min_cough = sample(0:3, n, replace = TRUE), pacu30min_throatPain = sample(0:10, n, replace = TRUE), pacu30min_swallowPain = sample(0:10, n, replace = TRUE), pacu90min_cough = sample(0:3, n, replace = TRUE), pacu90min_throatPain = sample(0:10, n, replace = TRUE), postOp4hour_cough = sample(0:3, n, replace = TRUE), postOp4hour_throatPain = sample(0:10, n, replace = TRUE), pod1am_cough = sample(0:3, n, replace = TRUE), pod1am_throatPain = sample(0:10, n, replace = TRUE) ) source_data$pacu30min_throatPain[c(1, 118)] <- NA d <- prepare_licorice_data(source_data) dim(d)# Synthetic records illustrate the required source format, not trial results. set.seed(42) n <- 235L source_data <- data.frame( preOp_gender = sample(0:1, n, replace = TRUE), preOp_asa = sample(1:3, n, replace = TRUE), preOp_calcBMI = runif(n, 20, 35), preOp_age = sample(18:80, n, replace = TRUE), preOp_mallampati = sample(1:4, n, replace = TRUE), preOp_smoking = sample(1:3, n, replace = TRUE), preOp_pain = sample(0:1, n, replace = TRUE), treat = rep(0:1, c(117, 118)), intraOp_surgerySize = sample(1:3, n, replace = TRUE), extubation_cough = sample(0:3, n, replace = TRUE), pacu30min_cough = sample(0:3, n, replace = TRUE), pacu30min_throatPain = sample(0:10, n, replace = TRUE), pacu30min_swallowPain = sample(0:10, n, replace = TRUE), pacu90min_cough = sample(0:3, n, replace = TRUE), pacu90min_throatPain = sample(0:10, n, replace = TRUE), postOp4hour_cough = sample(0:3, n, replace = TRUE), postOp4hour_throatPain = sample(0:10, n, replace = TRUE), pod1am_cough = sample(0:3, n, replace = TRUE), pod1am_throatPain = sample(0:10, n, replace = TRUE) ) source_data$pacu30min_throatPain[c(1, 118)] <- NA d <- prepare_licorice_data(source_data) dim(d)
Print a Licorice-Application Result
## S3 method for class 'licorice_analysis' print(x, ...)## S3 method for class 'licorice_analysis' print(x, ...)
x |
An object returned by |
... |
Additional arguments passed to |
The input object, invisibly.
Print a Covariate-Adjustment Result
## S3 method for class 'rct_adjustment' print(x, digits = max(3L, getOption("digits") - 3L), ...)## S3 method for class 'rct_adjustment' print(x, digits = max(3L, getOption("digits") - 3L), ...)
x |
An object returned by |
digits |
Number of significant digits to print. |
... |
Additional arguments passed to |
The input object, invisibly.
Print a Power-Design Result
## S3 method for class 'rct_power_design' print(x, ...)## S3 method for class 'rct_power_design' print(x, ...)
x |
An object returned by |
... |
Additional arguments passed to |
The input object, invisibly.
Print a Paper Simulation Result
## S3 method for class 'rct_simulation' print(x, ...)## S3 method for class 'rct_simulation' print(x, ...)
x |
An object returned by |
... |
Additional arguments passed to |
The input object, invisibly.
Estimates the treatment-minus-control marginal mean difference in a two-arm randomized controlled trial with a continuous outcome. The adjusted methods use the same empirical distribution of baseline covariates for both arms.
rct_adjust( outcome, treatment, covariates = NULL, allocation = NULL, methods = c("unadjusted", "ancova", "interacted"), conf_level = 0.95, diagnostic_hc2 = FALSE )rct_adjust( outcome, treatment, covariates = NULL, allocation = NULL, methods = c("unadjusted", "ancova", "interacted"), conf_level = 0.95, diagnostic_hc2 = FALSE )
outcome |
Complete, finite numeric continuous outcome. |
treatment |
Complete numeric or logical treatment indicator, coded 1 for treatment and 0 for control. Both arms must be represented. |
covariates |
Baseline covariates. Supply NULL, a data frame, a numeric
matrix, or a numeric vector with one row per outcome. Data-frame factors
are expanded with |
allocation |
Known probability of assignment to treatment. When NULL, the realized treatment fraction is used, and the influence calculation accounts for estimating that fraction. |
methods |
Any subset of "unadjusted", "ancova", and "interacted". |
conf_level |
Confidence level for normal-reference intervals. |
diagnostic_hc2 |
If TRUE, include the coefficient-only heteroskedasticity-consistent type 2 (HC2) diagnostic for interacted standardization. |
The common-slope method is ordinary least squares with a treatment indicator and centered baseline features. Its standard error is the heteroskedasticity-consistent type 0 coefficient sandwich. The interacted method fits a separate linear projection in each arm, standardizes both fits over all participants, and uses the joint influence function that includes empirical-standardization variation. Setting diagnostic_hc2 to TRUE adds a coefficient-only heteroskedasticity-consistent type 2 (HC2) calculation for the interacted point estimate. That calculation is provided as a diagnostic and is not generally valid for the superpopulation marginal estimand when treatment effects vary with covariates.
An object of class "rct_adjustment". Its estimates component contains point estimates, standard errors, and normal-reference confidence intervals. The influence component contains participant-level influence contributions.
set.seed(1) n <- 200 x <- rnorm(n) a <- rbinom(n, 1, 0.5) y <- 0.4 * a + x + rnorm(n) fit <- rct_adjust(y, a, data.frame(x = x), allocation = 0.5) fit confint(fit)set.seed(1) n <- 200 x <- rnorm(n) a <- rbinom(n, 1, 0.5) y <- 0.4 * a + x + rnorm(n) fit <- rct_adjust(y, a, data.frame(x = x), allocation = 0.5) fit confint(fit)
Standard methods extract the estimate table, coefficient vector,
influence-function covariance matrix, or normal-reference confidence
intervals from an object returned by rct_adjust() or rct_crossfit().
## S3 method for class 'rct_adjustment' as.data.frame(x, row.names = NULL, optional = FALSE, ...) ## S3 method for class 'rct_adjustment' coef(object, ...) ## S3 method for class 'rct_adjustment' vcov(object, ...) ## S3 method for class 'rct_adjustment' confint(object, parm, level = 0.95, ...) ## S3 method for class 'rct_adjustment' summary(object, ...)## S3 method for class 'rct_adjustment' as.data.frame(x, row.names = NULL, optional = FALSE, ...) ## S3 method for class 'rct_adjustment' coef(object, ...) ## S3 method for class 'rct_adjustment' vcov(object, ...) ## S3 method for class 'rct_adjustment' confint(object, parm, level = 0.95, ...) ## S3 method for class 'rct_adjustment' summary(object, ...)
x, object
|
An object of class "rct_adjustment". |
row.names, optional
|
Arguments passed to |
... |
Additional arguments for the corresponding generic. |
parm |
Optional method names or numeric indices. |
level |
Confidence level. |
as.data.frame and summary return the estimate table; coef returns a named vector; vcov returns the covariance matrix estimated from the stored influence contributions; confint returns a two-column matrix.
Computes a cross-fitted augmented estimator of the treatment-minus-control marginal mean difference. Outcome regressions are trained separately within each arm and evaluated only on held-out participants. Both fitted means are averaged through the same augmented score.
rct_crossfit( outcome, treatment, covariates, allocation = NULL, folds = 2L, fold_id = NULL, learner = c("linear", "quadratic"), seed = NULL, conf_level = 0.95 )rct_crossfit( outcome, treatment, covariates, allocation = NULL, folds = 2L, fold_id = NULL, learner = c("linear", "quadratic"), seed = NULL, conf_level = 0.95 )
outcome |
Complete, finite numeric continuous outcome. |
treatment |
Complete numeric or logical treatment indicator, coded 1 for treatment and 0 for control. Both arms must be represented. |
covariates |
Baseline covariates. Supply NULL, a data frame, a numeric
matrix, or a numeric vector with one row per outcome. Data-frame factors
are expanded with |
allocation |
Known probability of assignment to treatment. When NULL, the realized treatment fraction is used, and the influence calculation accounts for estimating that fraction. |
folds |
Number of folds. Ignored when fold_id is supplied. |
fold_id |
Optional integer or factor vector defining the fold of each participant. Every fold must be represented. Fold membership should be fixed without using outcomes. |
learner |
Either "linear", "quadratic", or a custom prediction function with the interface described in Details. |
seed |
Optional seed used only to randomly permute otherwise balanced fold labels. With NULL, folds follow participant order deterministically. |
conf_level |
Confidence level for normal-reference intervals. |
Built-in linear and quadratic learners use ordinary least squares. The quadratic learner adds a squared term for each model-matrix column; redundant columns are removed using baseline covariates alone. If a built-in fold-by-arm regression is rank deficient or has fewer observations than the number of coefficients plus two, it falls back to the corresponding training-arm mean.
A custom learner must be a function with arguments x_train, y_train, and x_new. It must return one finite numeric prediction for every row of x_new. Training and prediction are called once per arm within each fold.
An object of class "rct_adjustment".
d <- simulate_rct_case("A", n = 120, seed = 11) rct_crossfit( d$outcome, d$treatment, d["x"], allocation = 0.5, folds = 2, learner = "quadratic" )d <- simulate_rct_case("A", n = 120, seed = 11) rct_crossfit( d$outcome, d$treatment, d["x"], allocation = 0.5, folds = 2, learner = "quadratic" )
Computes the rejection probability of a normal-reference test for a
treatment-minus-control marginal mean difference. The "greater" and
"less" alternatives correspond to positive and negative effects,
respectively.
rct_power( n, effect, variance, alpha = 0.05, alternative = c("two.sided", "greater", "less") )rct_power( n, effect, variance, alpha = 0.05, alternative = c("two.sided", "greater", "less") )
n |
Total sample size. |
effect |
Planning marginal mean difference. |
variance |
Asymptotic variance factor on the square-root-n scale. |
alpha |
Type I error probability. |
alternative |
Test direction: |
A numeric vector of normal-approximation rejection probabilities.
rct_power(n = 300, effect = 0.5, variance = c(12.5, 8.5, 4))rct_power(n = 300, effect = 0.5, variance = c(12.5, 8.5, 4))
Inverts the exact one- or two-tail normal power expression. With round_up equal to TRUE, the result is the smallest integer total sample size attaining the requested normal-approximation power.
rct_sample_size( effect, variance, power = 0.8, alpha = 0.05, alternative = c("two.sided", "greater", "less"), round_up = TRUE )rct_sample_size( effect, variance, power = 0.8, alpha = 0.05, alternative = c("two.sided", "greater", "less"), round_up = TRUE )
effect |
Planning marginal mean difference. |
variance |
Asymptotic variance factor on the square-root-n scale. |
power |
Target power. |
alpha |
Type I error probability. |
alternative |
Test direction: |
round_up |
Return the smallest attaining integer if TRUE, or the continuous solution if FALSE. |
A numeric vector of total sample sizes.
rct_sample_size(effect = 0.5, variance = c(12.5, 8.5, 4), power = 0.8)rct_sample_size(effect = 0.5, variance = c(12.5, 8.5, 4), power = 0.8)
Computes the variance factors used in the article's one-covariate Gaussian examples. The data-generating law is
where , , and
are mutually independent. The value of
is supplied through noise_variance; the marginal effect
does not enter the variance factors.
rct_variance_factors( allocation, beta_control, beta_treatment, quadratic = 0, noise_variance = 1 )rct_variance_factors( allocation, beta_control, beta_treatment, quadratic = 0, noise_variance = 1 )
allocation |
Probability of assignment to treatment. |
beta_control |
Linear slope in the control arm. |
beta_treatment |
Linear slope in the treatment arm. |
quadratic |
Coefficient of the centered quadratic term. |
noise_variance |
Error variance, common to both arms. |
A named numeric vector containing variance factors for the unadjusted estimator, the semiparametric efficiency bound, interacted linear adjustment, pooled analysis of covariance (ANCOVA), and the coefficient-only heteroskedasticity-consistent type 2 (HC2) variance limit. The optimal and pooled slopes are returned as well.
rct_variance_factors( allocation = 0.5, beta_control = 1, beta_treatment = 1, quadratic = 0.75 )rct_variance_factors( allocation = 0.5, beta_control = 1, beta_treatment = 1, quadratic = 0.75 )
Verifies the MD5 and SHA-256 fingerprints of the exact reviewed R data file before loading it into an isolated environment. The file itself is not included in RCTCovAdj.
read_licorice_data(path)read_licorice_data(path)
path |
Path to the authorized licorice_gargle RDA file. |
The verified analysis-ready data frame.
# An unverified file is rejected before it can be loaded. path <- tempfile(fileext = ".rda") writeLines("This is not the reviewed trial-data file.", path) try(read_licorice_data(path)) unlink(path) # Set this environment variable only for a copy you are authorized to use. path <- Sys.getenv("RCTCOVADJ_LICORICE_RDA", unset = "") if (nzchar(path)) { d <- read_licorice_data(path) }# An unverified file is rejected before it can be loaded. path <- tempfile(fileext = ".rda") writeLines("This is not the reviewed trial-data file.", path) try(read_licorice_data(path)) unlink(path) # Set this environment variable only for a copy you are authorized to use. path <- Sys.getenv("RCTCOVADJ_LICORICE_RDA", unset = "") if (nzchar(path)) { d <- read_licorice_data(path) }
Runs run_paper_simulations() and writes portable comma-separated summaries,
optional replicate data, PDF and PNG figures, session information, and file
checksums to an explicitly chosen directory.
reproduce_paper_simulations( output_dir, reps = 4000L, sample_sizes = c(200L, 800L), cases = c("A", "B", "C", "D"), seed = 20260903L, keep_replicates = TRUE, progress = interactive(), figures = TRUE, overwrite = FALSE )reproduce_paper_simulations( output_dir, reps = 4000L, sample_sizes = c(200L, 800L), cases = c("A", "B", "C", "D"), seed = 20260903L, keep_replicates = TRUE, progress = interactive(), figures = TRUE, overwrite = FALSE )
output_dir |
Destination directory, supplied explicitly by the user.
There is no default. Use a path under |
reps |
Replications per case and sample-size cell. |
sample_sizes |
A subset of 200 and 800. |
cases |
A subset of "A", "B", "C", and "D". |
seed |
Master seed. |
keep_replicates |
Retain replicate-level estimates and standard errors. |
progress |
Print one message after each completed cell. |
figures |
Whether to draw efficiency and coverage figures in both PDF and PNG formats. |
overwrite |
Whether an existing package-defined output bundle may be replaced. Outputs from an earlier bundle that are not requested in the new run are removed only after the new bundle has been generated. |
A named character vector of written paths, invisibly.
out <- tempfile("rctcovadj-") reproduce_paper_simulations( out, reps = 3, sample_sizes = 200, cases = "A", figures = FALSE ) unlink(out, recursive = TRUE)out <- tempfile("rctcovadj-") reproduce_paper_simulations( out, reps = 3, sample_sizes = 200, cases = "A", figures = FALSE ) unlink(out, recursive = TRUE)
Reproduces the four continuous-outcome designs, seven estimators, independent random-number streams, and deterministic two-fold split used in the article. The default is the complete 32,000-trial experiment. Use a small value of reps for a quick workflow check.
run_paper_simulations( reps = 4000L, sample_sizes = c(200L, 800L), cases = c("A", "B", "C", "D"), seed = 20260903L, keep_replicates = FALSE, progress = interactive() )run_paper_simulations( reps = 4000L, sample_sizes = c(200L, 800L), cases = c("A", "B", "C", "D"), seed = 20260903L, keep_replicates = FALSE, progress = interactive() )
reps |
Replications per case and sample-size cell. |
sample_sizes |
A subset of 200 and 800. |
cases |
A subset of "A", "B", "C", and "D". |
seed |
Master seed. |
keep_replicates |
Retain replicate-level estimates and standard errors. |
progress |
Print one message after each completed cell. |
An object of class "rct_simulation" with aggregate summary, population benchmarks, settings, and optionally replicate-level results.
quick <- run_paper_simulations( reps = 4, sample_sizes = 200, cases = "A" ) quick$summaryquick <- run_paper_simulations( reps = 4, sample_sizes = 200, cases = "A" ) quick$summary
Generates one trial under a named Gaussian data-generating law in simulation_cases. The marginal treatment mean difference is 0.5 in every case.
simulate_rct_case(case = c("A", "B", "C", "D"), n = 200L, seed = NULL)simulate_rct_case(case = c("A", "B", "C", "D"), n = 200L, seed = NULL)
case |
One of "A", "B", "C", or "D". |
n |
Number of participants. |
seed |
Optional nonnegative integer seed. |
A data frame with columns x, treatment, and outcome. Design parameters are stored in the case_parameters attribute.
d <- simulate_rct_case("A", n = 100, seed = 42) head(d)d <- simulate_rct_case("A", n = 100, seed = 42) head(d)
Four one-covariate Gaussian data-generating laws used to study nonlinear prognostic structure, treatment-effect heterogeneity, unequal allocation, and opposing arm-specific slopes.
simulation_casessimulation_cases
A data frame with 4 rows and 6 variables:
Case identifier.
Descriptive case label.
Probability of assignment to treatment.
Control-arm linear slope.
Treatment-arm linear slope.
Coefficient of the centered quadratic term.
Generated from the analytic designs specified in the accompanying manuscript.