Adapt multisiteDGP output for downstream meta-analysis and power packages

Strip the multisiteDGP attributes and class from a simulated dataset and rename the canonical columns to the conventions of a downstream analysis package. The numeric values themselves are NEVER transformed — only the column names change. Three adapters ship with the package, each targeting a soft-dependency analysis package:

as_metafor: Renames to metafor's (yi, vi, sei) convention. Use as input to metafor::rma() or metafor::escalc().
as_baggr: Renames to baggr's (tau, se) convention; optional tau_true column for diagnostic plotting.
as_multisitepower: Renames to multisitepower's (site, estimate, se, n) convention. Use for empirical-Bayes power analysis.

Usage

as_metafor(x, ...)

as_baggr(x, ..., include_truth = FALSE)

as_multisitepower(x, ...)

Arguments

x: A multisitedgp_data object from sim_multisite or sim_meta.
...: Reserved for future extensions.
include_truth: Logical. When TRUE, includes the latent true effects as a tau_true column — useful for diagnostic plots that compare baggr's posterior to the simulation truth. Default FALSE.

Value

A plain tbl_df with renamed columns. No multisiteDGP class or attributes are carried through — the result is suitable to pass directly to the downstream package's API.

Details

Soft-dependency guard. Each adapter checks that the target package is installed and aborts with a friendly install hint if not. metafor, baggr, and multisitepower are Suggests, not Imports — they are not required to use multisiteDGP itself.

Reserved column-name protection. If your simulation includes covariate columns that collide with the target package's reserved names (e.g., a covariate named yi would collide with metafor), the adapter aborts and asks you to rename the offending column first. This prevents silent overwrite.

Covariate pass-through. Any non-canonical columns in the upstream multisitedgp_data (covariates from formula / beta / data) are carried through to the adapted tibble after the renamed canonical columns.

For a full workflow walkthrough see the Adapters and downstream packages vignette.

Functions

as_metafor(): Convert to metafor's (yi, vi, sei) column convention. yi <- tau_j_hat, vi <- se2_j, sei <- se_j. Pass the result directly to metafor::rma() or metafor::escalc(). Soft-dep guard on metafor.
as_baggr(): Convert to baggr's (tau, se) column convention. tau <- tau_j_hat, se <- se_j. Use as input to baggr::baggr(). Soft-dep guard on baggr.
as_multisitepower(): Convert to multisitepower's (site, estimate, se, n) column convention. site <- site_index, estimate <- tau_j_hat, se <- se_j, n <- n_j (when present). Use as input to multisitepower::power_calc(). Soft-dep guard on multisitepower.

References

Lee, J., Che, J., Rabe-Hesketh, S., Feller, A., & Miratrix, L. (2025). Improving the estimation of site-specific effects and their distribution in multisite trials. Journal of Educational and Behavioral Statistics, 50(5), 731–764. doi:10.3102/10769986241254286 .

Examples

dat <- sim_multisite(J = 10L, seed = 1L)

# metafor: yi = tau_hat, vi = se2, sei = se.
if (requireNamespace("metafor", quietly = TRUE)) {
  md <- as_metafor(dat)
  metafor::rma(yi = yi, vi = vi, data = md)
}
#> 
#> Random-Effects Model (k = 10; tau^2 estimator: REML)
#> 
#> tau^2 (estimated amount of total heterogeneity): 0 (SE = 0.0309)
#> tau (square root of estimated tau^2 value):      0
#> I^2 (total heterogeneity / total variability):   0.00%
#> H^2 (total variability / sampling variability):  1.00
#> 
#> Test for Heterogeneity:
#> Q(df = 9) = 4.0693, p-val = 0.9068
#> 
#> Model Results:
#> 
#> estimate      se    zval    pval    ci.lb   ci.ub    
#>   0.0096  0.0836  0.1146  0.9087  -0.1543  0.1735    
#> 
#> ---
#> Signif. codes:  0 ‘***’ 0.001 ‘**’ 0.01 ‘*’ 0.05 ‘.’ 0.1 ‘ ’ 1
#> 

# baggr: tau = tau_hat, se = se. Add latent truth for diagnostic plots.
if (requireNamespace("baggr", quietly = TRUE)) {
  bg <- as_baggr(dat, include_truth = TRUE)
}