Align precision ranks using a Gaussian copula pairing

Permute the paired precision columns (se_j, se2_j, n_j) of a Layer 2 frame so the realized rank correlation between \(z_j\) and \(\widehat{se}_j^2\) approximates a target latent Gaussian copula correlation pearson_corr. Unlike the hill-climb in align_rank_corr, the copula aligner draws a correlated latent score per site and pairs the empirical se2_j multiset by that order in one shot — fast, no iterative search.

Usage

align_copula_corr(upstream, pearson_corr = 0, dependence_fn = NULL, ...)

Arguments

upstream: A Layer 2 data frame with canonical columns site_index, z_j, tau_j, se_j, se2_j, n_j.
pearson_corr: Numeric in [-1, 1]. Target latent Gaussian-copula correlation. Default 0 (independence). Realized Spearman \(\rho_S\) is approximately \((6/\pi)\,\arcsin(\mathrm{pearson\_corr}/2)\) — close to the input value over the typical applied range. Near-boundary |pearson_corr| > 0.95 triggers a stability warning.
dependence_fn: Optional callback. See align_rank_corr for the contract.
...: Additional arguments forwarded to dependence_fn.

Value

The upstream tibble with the paired precision columns permuted, plus attributes permutation_perm (the realized assignment) and dependence_diagnostics.

Details

Mechanism. The package converts \(z_j\) to rank-normal scores, draws a correlated latent score from a bivariate Gaussian copula with Pearson correlation pearson_corr, and assigns the empirical se2_j multiset by the order of the latent score. Because the assignment uses only the order of the latent draw, the empirical SE marginal is preserved exactly — only the joint distribution moves.

Tradeoff vs hill-climb. The copula path is fast and produces a clean joint distribution that follows a Gaussian-copula form, but the realized residual Spearman correlation is only approximately equal to pearson_corr — the conversion is exact in the limit \(J \to \infty\) and approximate at finite \(J\). For tight tolerance on the realized Spearman, use align_hybrid_corr (the recommended default — copula init + hill-climb polish) or align_rank_corr directly.

Custom dependence_fn extensibility. See the same contract documented in align_rank_corr.

For the formal contrast among the three injection methods and a decision rubric, see the Precision dependence — three injection methods vignette.

RNG policy

For abs(pearson_corr) < 1, the aligner consumes exactly one rnorm() draw per site (the latent score). For pearson_corr = -1 or pearson_corr = 1, the endpoint path is deterministic and consumes no RNG.

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

# Compose Layer 1 + 2 + 3 with copula injection (small J — noisy realization).
effects <- gen_effects_gaussian(J = 12L)
margins <- gen_site_sizes(effects, J = 12L, nj_mean = 40, cv = 0.2)
aligned <- align_copula_corr(margins, pearson_corr = 0.3)
cor(aligned$z_j, aligned$se2_j, method = "spearman")
#> [1] -0.2561419

# At larger J the realized Spearman tracks the target closely.
effects100 <- gen_effects_gaussian(J = 100L)
margins100 <- gen_site_sizes(effects100, J = 100L, nj_mean = 40, cv = 0.2)
aligned100 <- align_copula_corr(margins100, pearson_corr = 0.5)
cor(aligned100$z_j, aligned100$se2_j, method = "spearman")
#> [1] 0.5129464