
Construct sampling covariance for dependent effect sizes
compute_es_covariance.RdAttaches a named sampling covariance matrix to compute_es() results using
explicit participant, measurement and variable identities. Supports MD, ROM,
OR, RR, RD, IRR, PR, PLO, PLN, SMD, GLASS, COR and ZCOR. One measure per call.
Usage
compute_es_covariance(
x,
study_id,
arm1 = NULL,
arm2 = NULL,
outcome_id = NULL,
time_id = NULL,
independent_arms = FALSE,
independent_studies = FALSE,
dependence = NULL,
same_participants = FALSE,
variable1 = NULL,
variable2 = NULL,
correlation_matrices = NULL,
common_sample = FALSE
)Arguments
- x
An untransformed
mars_esresult with all rows having statusok.- study_id, arm1, arm2, outcome_id, time_id
Column names in
original_data, quoted or unquoted, scalar labels, or row-aligned vectors. For arm methods, study, outcome, time and arm1 are required; arm2 is also required for contrasts. Proportions use arm1 only. An arm identifies a participant set, and an outcome/time pair identifies a measurement within that set. COR/ZCOR require study_id and variable1/variable2 instead. For results fromaggregate_es_subgroups(), identifiers are resolved against effect_data (one comparison per effect), not subgroup original_data. Its study_id, outcome_id and time_id columns describe the aggregated strata.- independent_arms
Explicit TRUE for arm methods: distinct arm IDs in a study identify disjoint independent participant sets.
- independent_studies
Explicit TRUE: distinct studies are independent.
- dependence
Optional data frame with columns
study_id,arm_id,outcome1,time1,outcome2,time2. Supply exactly one row per pair of distinct measurements within each arm, in either order. Additional numeric column:correlationfor continuous outcomes;joint_events(number with both binary outcomes) for binomial outcomes;count_covariance(sampling covariance of the two aggregate event counts) for IRR. Zero dependence must be explicit. Unknown, duplicate and unused pairs are rejected. Measurements with binary pseudo-count corrections cannot use joint-event reconstruction.- same_participants
Explicit TRUE for multiple outcomes/times within an arm: the same complete participant set supplies both measurements. Binary and continuous sample sizes must agree. Partial overlap is unsupported.
- variable1, variable2
Variable identities for COR/ZCOR, resolved like study_id. Distinct variables are required within each reported correlation.
- correlation_matrices
Named list (one matrix per study) of complete, named, symmetric, positive-semidefinite Pearson correlation matrices for COR/ZCOR. Reported correlations must match the corresponding matrix entries.
- common_sample
Explicit TRUE for COR/ZCOR: every correlation in each study uses the same complete sample. Sample sizes must agree and be >= 5.
Value
The original result with sampling_covariance, covariance_blocks
and covariance_provenance. Estimates and marginal variances are preserved.
Provenance includes identities, formulas, supplied dependence, and (for
joint arm methods) the primitive covariance and Jacobian used to form V.
Continuous joint calculations use standardized summary fluctuations to
avoid overflow/underflow. primitive_coordinates and primitive_sd_scales
record these coordinates; the reported Jacobian uses the same coordinates,
so its product with primitive_covariance reconstructs V.
Details
See the installed compute-es/COVARIANCE.md for full formulas, definitions,
worked examples, assumptions and limitations. The following are plug-in
formulas; nonlinear transformations use first-order approximations.
Shared arms at one outcome/time retain the original method: $$V=A\,\mathrm{diag}(q)\,A^T,$$ with signed contrast matrix \(A\) and arm contribution variances MD: \(s^2/n\); ROM: \(s^2/(nm^2)\); OR: \(1/a+1/b\); RR: \(1/a-1/n\); RD: \(p(1-p)/n\); IRR: \(1/a\). Here \(a\) and \(b\) count events and non-events, \(n=a+b\), and \(p=a/n\).
For repeated binary outcomes \(j\) and \(k\) on \(n\) participants, let \(a_{jk}\) count joint events. Then \(B_{jk}=(a_{jk}/n-p_j p_k)/n\). Transform with derivatives 1 (PR/RD), \(1/p\) (PLN/RR), or \(1/[p(1-p)]\) (PLO/OR), and the contrast signs: \(V=D B D^T\). For IRR, \(B\) is the supplied count covariance with Poisson diagonal \(a\), and the signed log-count derivatives are \(1/a\). Fixed exposures affect point estimates but not these derivatives. Joint-event counts alone do not identify recurrent-event count covariance.
Under independent multivariate-normal observations within an arm,
$$\mathrm{Cov}(\bar X_j,\bar X_k)=r_{jk}s_js_k/n,$$
$$\mathrm{Cov}(s_j^2,s_k^2)=2r_{jk}^2s_j^2s_k^2/(n-1).$$
Mean/sample-variance cross covariances are zero under normality. For SMD/GLASS
write \(y=J\Delta/\sqrt{q}\), \(q=\sum_h w_h s_h^2\).
SMD uses \(w_h=(n_h-1)/(n_1+n_2-2)\); GLASS puts weight 1 on the
declared reference arm. Mean derivatives are signed \(J/\sqrt{q}\);
sample-variance derivatives are \(-y w_h/(2q)\). Use
variance_method="JOINT_DELTA" in compute_es for SMD/GLASS. Existing LS,
J2_LS and HET marginals are not silently rescaled or replaced.
For Pearson correlations \(r_{ab}\) and \(r_{cd}\), define $$K_{ab,cd}=r_{ac}r_{bd}+r_{ad}r_{bc} -r_{ab}(r_{ac}r_{ad}+r_{bc}r_{bd}) -r_{cd}(r_{ac}r_{bc}+r_{ad}r_{bd}) +\tfrac12 r_{ab}r_{cd}(r_{ac}^2+r_{ad}^2+r_{bc}^2+r_{bd}^2).$$ COR uses \(K/(n-1)\). ZCOR uses \(K/[(n-3)(1-r_{ab}^2)(1-r_{cd}^2)]\), matching the specialized Fisher marginal variance. Delta-transforming COR instead retains n-1.
All joint matrices must be positive semidefinite; binary joint counts also obey the feasible two-by-two table bounds. Pairwise feasibility and PSD are necessary but not sufficient for a joint Bernoulli distribution with three or more outcomes. Use joint counts from coherent participant-level data. Covariance diagonals must match the source variances. No matrix repair, automatic independence, overlap approximation or continuity correction of joint counts is performed. Redundant contrasts may produce singular V; choose a nonredundant set for fitting functions requiring invertible V.
References
Steiger, J. H. (1980). Tests for comparing elements of a correlation matrix. Psychological Bulletin, 87, 245-251. doi:10.1037/0033-2909.87.2.245 .
Oehlert, G. W. (1992). A note on the delta method. The American Statistician, 46(1), 27–29. doi:10.1080/00031305.1992.10475842 .
Examples
dat <- data.frame(a=c("T1","T2"), b="C", m1=c(12,13), m2=10,
sd1=3, sd2=2, n1=30, n2=25)
es <- compute_es(dat, measure="SMD", design="independent_groups",
input="means_sd", m1=m1, m2=m2, sd1=sd1, sd2=sd2, n1=n1, n2=n2,
variance_method="JOINT_DELTA")
es <- compute_es_covariance(es, study_id="s1", arm1=a, arm2=b,
outcome_id="score", time_id="post", independent_arms=TRUE,
independent_studies=TRUE)
es$sampling_covariance
#> 1 2
#> 1 0.07254885 0.02438631
#> 2 0.02438631 0.08028282