Skip to contents

Attaches 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_es result with all rows having status ok.

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 from aggregate_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: correlation for 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