Skip to contents

Supported calculations

compute_es() converts reported statistics into continuous, correlation, binary, proportion and ratio effect sizes. The user selects the measure, design and input route explicitly. The first sections cover two independent groups. Supported inputs include means/SDs, arm-mean SEs or Student-t confidence intervals, a combined-sample SD, unadjusted pooled Student t tests, two-group one-way ANOVA F tests, and exact two-sided p-values from the eligible t test. The registry lists supported routes; it does not claim complete coverage of Appendix B of Lipsey and Wilson (2001).

es_methods()[, c("measure", "input", "required", "status")]
#>    measure             input
#> 1      SMD          means_sd
#> 2      SMD         student_t
#> 3      SMD           anova_f
#> 4      SMD           p_value
#> 5      SMD          means_se
#> 6      SMD          means_ci
#> 7      SMD    means_total_sd
#> 8       MD          means_sd
#> 9       MD          means_se
#> 10      MD          means_ci
#> 11   GLASS          means_sd
#> 12   GLASS          means_se
#> 13   GLASS          means_ci
#> 14     COR       correlation
#> 15    ZCOR       correlation
#> 16    PCOR       correlation
#> 17    PCOR      regression_t
#> 18   ZPCOR       correlation
#> 19   ZPCOR      regression_t
#> 20   SPCOR       correlation
#> 21   SPCOR      regression_t
#> 22  ZSPCOR       correlation
#> 23  ZSPCOR      regression_t
#> 24      OR     binary_counts
#> 25      RR     binary_counts
#> 26      RD     binary_counts
#> 27      PR proportion_counts
#> 28     PLO proportion_counts
#> 29     PLN proportion_counts
#> 30     IRR  incidence_counts
#> 31     ROM          means_sd
#> 32     ROM          means_se
#> 33     ROM          means_ci
#> 34      HR   reported_log_se
#>                                                                                            required
#> 1                                                                          m1, sd1, n1, m2, sd2, n2
#> 2                                                                                     t, df, n1, n2
#> 3                                                                   f, df1, df, effect_sign, n1, n2
#> 4                                                                        p, df, effect_sign, n1, n2
#> 5                                                                 m1, se1, n1, m2, se2, n2, se_type
#> 6                   m1, lower1, upper1, n1, m2, lower2, upper2, n2, ci_level1, ci_level2, ci_method
#> 7                                                          m1, m2, n1, n2, sd_total, total_sd_scope
#> 8                                                                          m1, sd1, n1, m2, sd2, n2
#> 9                                                                 m1, se1, n1, m2, se2, n2, se_type
#> 10                  m1, lower1, upper1, n1, m2, lower2, upper2, n2, ci_level1, ci_level2, ci_method
#> 11                                                        m1, sd1, n1, m2, sd2, n2, reference_group
#> 12                                               m1, se1, n1, m2, se2, n2, se_type, reference_group
#> 13 m1, lower1, upper1, n1, m2, lower2, upper2, n2, ci_level1, ci_level2, ci_method, reference_group
#> 14                                                                                       r, n_total
#> 15                                                                                       r, n_total
#> 16                                                                           r, n_total, predictors
#> 17                                                                       t, df, n_total, predictors
#> 18                                                                           r, n_total, predictors
#> 19                                                                       t, df, n_total, predictors
#> 20                                                                r, n_total, predictors, r_squared
#> 21                                                            t, df, n_total, predictors, r_squared
#> 22                                                                r, n_total, predictors, r_squared
#> 23                                                            t, df, n_total, predictors, r_squared
#> 24                                            events1, non_events1, events2, non_events2, zero_cell
#> 25                                            events1, non_events1, events2, non_events2, zero_cell
#> 26                                            events1, non_events1, events2, non_events2, zero_cell
#> 27                                                                       events, n_total, zero_cell
#> 28                                                                       events, n_total, zero_cell
#> 29                                                                       events, n_total, zero_cell
#> 30                                          events1, events2, person_time1, person_time2, zero_cell
#> 31                                                                         m1, sd1, n1, m2, sd2, n2
#> 32                                                                m1, se1, n1, m2, se2, n2, se_type
#> 33                  m1, lower1, upper1, n1, m2, lower2, upper2, n2, ci_level1, ci_level2, ci_method
#> 34                                                                estimate, estimate_se, adjustment
#>         status
#> 1  implemented
#> 2  implemented
#> 3  implemented
#> 4  implemented
#> 5  implemented
#> 6  implemented
#> 7  implemented
#> 8  implemented
#> 9  implemented
#> 10 implemented
#> 11 implemented
#> 12 implemented
#> 13 implemented
#> 14 implemented
#> 15 implemented
#> 16 implemented
#> 17 implemented
#> 18 implemented
#> 19 implemented
#> 20 implemented
#> 21 implemented
#> 22 implemented
#> 23 implemented
#> 24 implemented
#> 25 implemented
#> 26 implemented
#> 27 implemented
#> 28 implemented
#> 29 implemented
#> 30 implemented
#> 31 implemented
#> 32 implemented
#> 33 implemented
#> 34 implemented

The registry distinguishes required study statistics from optional controls. It also reports the default correction, variance method, analysis scale, contrast direction, formulas and source references for each route. Defaults apply only when the corresponding arguments to compute_es() are omitted; explicit settings must be compatible with every selected row.

methods <- es_methods()
methods[methods$measure == "GLASS",
  c("input", "default_correction", "default_variance_method", "analysis_scale")]
#>       input default_correction default_variance_method
#> 11 means_sd       hedges_exact                     HET
#> 12 means_se       hedges_exact                     HET
#> 13 means_ci       hedges_exact                     HET
#>                  analysis_scale
#> 11 standardized_mean_difference
#> 12 standardized_mean_difference
#> 13 standardized_mean_difference
methods[methods$input == "means_ci", c("measure", "required", "optional")]
#>    measure
#> 6      SMD
#> 10      MD
#> 13   GLASS
#> 33     ROM
#>                                                                                            required
#> 6                   m1, lower1, upper1, n1, m2, lower2, upper2, n2, ci_level1, ci_level2, ci_method
#> 10                  m1, lower1, upper1, n1, m2, lower2, upper2, n2, ci_level1, ci_level2, ci_method
#> 13 m1, lower1, upper1, n1, m2, lower2, upper2, n2, ci_level1, ci_level2, ci_method, reference_group
#> 33                  m1, lower1, upper1, n1, m2, lower2, upper2, n2, ci_level1, ci_level2, ci_method
#>                       optional
#> 6  ci_tolerance (default 1e-8)
#> 10 ci_tolerance (default 1e-8)
#> 13 ci_tolerance (default 1e-8)
#> 33 ci_tolerance (default 1e-8)

Exact Hedges correction corrects mean bias under its stated normal theory; it does not make sampling variances or normal Wald intervals exact. Variances refer to the reported analysis scale. A displayed ratio or correlation must not be pooled with a log-scale or Fisher-z variance.

Specify design="independent_groups" and measure="SMD" (the default). The design refers to the two groups within a comparison; it does not establish independence between different effect-size rows.

Reported information Route Additional requirements
Group means and SDs means_sd Both group sample sizes; positive pooled SD
Group means and SEs means_se Explicit unadjusted-arm-mean SE definition
Group means and CIs means_ci Explicit Student-t construction, arm confidence levels and sample sizes
Means and combined-sample SD means_total_sd SD across exactly the two groups; positive recovered within-group variance
Signed pooled Student t student_t Both sample sizes and residual df
Two-group ANOVA F anova_f Both sample sizes, numerator df=1, residual df, effect direction
Exact two-sided p p_value Both sample sizes, residual df, effect direction; eligible t-test origin

Paired tests, Welch tests, covariate-adjusted tests, clustered test reconstructions and omnibus multi-group F tests are not eligible for these independent-group SMD routes. Correlation, binary, proportion and ratio routes have their own design requirements, described below. Matching degrees of freedom alone cannot establish test eligibility; verify the study’s analysis description.

Group means and SDs

es <- compute_es(
  hsmd_example_1, design="independent_groups", input="means_sd",
  m1=mT, sd1=sdT, n1=nT, m2=mC, sd2=sdC, n2=nC,
  study_id=Study
)
head(es$data[, c("study_id","yi","vi","sei","metric","status")])
#>                  study_id         yi         vi       sei   metric status
#> 1       Saw et al. (2019) -1.1547909 0.23333855 0.4830513 hedges_g     ok
#> 2 Vuthiarpa et al. (2012) -0.7994204 0.06170766 0.2484103 hedges_g     ok
#> 3    Garcia et al. (2013)  0.3405679 0.11306603 0.3362529 hedges_g     ok
#> 4   Avci & Kelleci (2016) -0.8834683 0.07317097 0.2705013 hedges_g     ok
#> 5     Clark et al. (1995) -0.3391651 0.03441596 0.1855154 hedges_g     ok
#> 6  Horowitz et al. (2007) -0.3059020 0.01534533 0.1238763 hedges_g     ok

Positive effects mean group 1 minus group 2 is positive. Lower scores being beneficial does not change the arithmetic; keep the interpretation of benefit separate. Swapping both groups reverses the effect and preserves its variance.

Column names can be unquoted or quoted. Numeric vectors must have one value per row, or be explicit scalar constants. The original data are preserved in es$original_data; es$inputs records the resolved calculation inputs, including constants supplied outside the data frame. Existing columns are never overwritten.

Reconstructing SDs from what was reported

Arm-mean SEs can be converted using SD=SE*sqrt(n). This relationship does not apply to the SE of a treatment contrast or an adjusted/cluster-based mean. The following example constructs SEs from the bundled summaries to show route equivalence; extract the actual reported quantities for a real analysis.

reported <- hsmd_example_1
reported$seT <- reported$sdT/sqrt(reported$nT)
reported$seC <- reported$sdC/sqrt(reported$nC)
from_se <- compute_es(reported, design="independent_groups", input="means_se",
  m1=mT, m2=mC, n1=nT, n2=nC, se1=seT, se2=seC,
  se_type="unadjusted_mean", study_id=Study)
stopifnot(isTRUE(all.equal(from_se$data$yi,es$data$yi)))
head(from_se$reconstruction)
#>   effect_id  se1_used  se2_used sd1_used sd2_used sd_pooled ci_error1 ci_error2
#> 1         1 3.2539837 0.5533986    10.29     1.75  7.380603        NA        NA
#> 2         2 0.8299415 0.9905208     4.91     5.86  5.405909        NA        NA
#> 3         3 2.7406526 1.9729753    11.30     8.60  9.962164        NA        NA
#> 4         4 1.8951200 1.9553695    10.38    10.71 10.546291        NA        NA
#> 5         5 1.2896780 1.4915941     9.30    12.30 11.103298        NA        NA
#> 6         6 1.0392305 0.9692308    10.80    12.60 11.931953        NA        NA
#>   note
#> 1     
#> 2     
#> 3     
#> 4     
#> 5     
#> 6

For CIs of arm means, supply their construction and confidence levels explicitly. This route supports two-sided Student-t intervals with each arm’s df equal to its sample size minus one. It does not infer the construction from sample size or accept asymmetric, transformed or bootstrap intervals as Student-t intervals. See Cochrane 6.5.2.2 for the distinction between uncertainty in arm means and in their difference.

reported$lowerT <- reported$mT-qt(.975,reported$nT-1)*reported$seT
reported$upperT <- reported$mT+qt(.975,reported$nT-1)*reported$seT
reported$lowerC <- reported$mC-qt(.95,reported$nC-1)*reported$seC
reported$upperC <- reported$mC+qt(.95,reported$nC-1)*reported$seC
from_ci <- compute_es(reported, design="independent_groups", input="means_ci",
  m1=mT,m2=mC,n1=nT,n2=nC,
  lower1=lowerT,upper1=upperT,lower2=lowerC,upper2=upperC,
  ci_level1=.95,ci_level2=.90,ci_method="student_t",study_id=Study)
stopifnot(isTRUE(all.equal(from_ci$data$yi,es$data$yi,tolerance=1e-10)))

ci_level1 and ci_level2 describe the reported arm intervals; conf_level controls the newly calculated effect interval. The mean must match the CI midpoint. For rounding, ci_tolerance is a declared fraction of the interval half-width (default 1e-8), with a small machine-roundoff allowance. A tolerance of .01 permits a midpoint discrepancy up to 1% of that half-width. Accepted nonzero discrepancies are recorded, and the reported mean is retained. The tolerance does not justify using a genuinely asymmetric interval.

A reported SD across both arms includes between-arm variation. The total-SD route subtracts between-arm sums of squares before constructing the pooled SD. It requires total_sd_scope="two_groups"; do not use an SD across additional arms or measurement occasions. Contradictory summaries are rejected. A positive residual variance indistinguishable from roundoff is reported as unavailable, without clipping to an artificial positive value.

N <- reported$nT+reported$nC
reported$totalSD <- sqrt(((reported$nT-1)*reported$sdT^2 +
  (reported$nC-1)*reported$sdC^2 + reported$nT*reported$nC/N*
  (reported$mT-reported$mC)^2)/(N-1))
from_total <- compute_es(reported,design="independent_groups",input="means_total_sd",
  m1=mT,m2=mC,n1=nT,n2=nC,sd_total=totalSD,total_sd_scope="two_groups")
stopifnot(isTRUE(all.equal(from_total$data$yi,es$data$yi,tolerance=1e-10)))

Individual arm SDs are not identified by a total SD and two means. The result therefore records only the reconstructed pooled SD for this route.

Combining disjoint subgroups within arms

Use aggregate_es_subgroups() when reports split each arm into disjoint subgroups. It includes both within-subgroup variability and differences between subgroup means. Each subgroup currently requires n > 1 and an observed SD.

subgroups <- data.frame(
  study="example", arm=c("treatment","treatment","control","control"),
  subgroup=c("A","B","A","B"),
  average=c(10,15,9,11), spread=c(2,3,2,2), count=c(12,18,15,10),
  source=c("T_A","T_B","C_A","C_B")
)
combined <- aggregate_es_subgroups(subgroups,
  study_id=study,arm_id=arm,subgroup_id=subgroup,mean=average,sd=spread,n=count,
  group1="treatment",group2="control",disjoint=TRUE,source_id=source)
combined$data
#>   effect_id study_id       yi        vi       sei     ci_lb    ci_ub        d
#> 1       es1  example 1.034285 0.0830583 0.2881984 0.4694269 1.599144 1.049215
#>           J df status message measure             design    input   correction
#> 1 0.9857707 53     ok             SMD independent_groups means_sd hedges_exact
#>   variance_method   metric                        scale outcome_id time_id
#> 1              LS hedges_g standardized_mean_difference    overall overall
combined$aggregation$arms
#>   effect_id study_id outcome_id time_id    arm_id arm_key mean       sd  n
#> 1       es1  example    overall overall treatment   es1.1 13.0 3.605551 30
#> 2       es1  example    overall overall   control   es1.2  9.8 2.198484 25
combined$aggregation$source_map
#>   source_id effect_id arm_key subgroup_id
#> 1       T_A       es1   es1.1           A
#> 2       T_B       es1   es1.1           B
#> 3       C_A       es1   es1.2           A
#> 4       C_B       es1   es1.2           B

disjoint=TRUE is a substantive declaration, not something the software can verify from summaries. It also declares independent participants across the two selected arms. Choose arms explicitly; extra arms are recorded as excluded. Provide outcome_id and time_id when needed so different measurements are not combined. Supplied source IDs and mappings retain traceability through aggregation. Repeated outcomes/time strata still require a dependence model; this helper does not compute cross-effect covariance.

Corrections and uncertainty

The pooled-SD effect is

d=\frac{m_1-m_2}{\sqrt{[(n_1-1)s_1^2+(n_2-1)s_2^2]/\nu}}, \qquad \nu=n_1+n_2-2.

The default correction="hedges_exact" uses J=\Gamma(\nu/2)/[\sqrt{\nu/2}\Gamma((\nu-1)/2)] and returns g=Jd. "hedges_approx" uses J=1-3/(4\nu-1); "none" returns Cohen’s d. The exact correction’s usual unbiasedness interpretation assumes independent normal observations with a common population variance.

The default variance_method="LS" uses v=1/n_1+1/n_2+y_i^2/[2(n_1+n_2)], where y_i is the selected d or g. The alternative "J2_LS" uses v=J^2\{1/n_1+1/n_2+d^2/[2(n_1+n_2)]\}. These are distinct approximations, recorded explicitly in the output. Do not expect agreement with a different program unless both correction and variance conventions match. The default matches the usual SMD convention in metafor::escalc().

Confidence limits are normal-approximation Wald intervals at conf_level (default .95). An exact bias correction does not make the sampling variance or interval exact. Approximation quality can be poor with very small samples.

Studies reporting different statistics

This example reconstructs equivalent test statistics from the bundled group summaries to demonstrate mixed reporting. In practice, enter the actual reported statistics and verify their design and test definitions.

mixed <- hsmd_example_1
nu <- mixed$nT + mixed$nC - 2
sp <- sqrt(((mixed$nT-1)*mixed$sdT^2 + (mixed$nC-1)*mixed$sdC^2)/nu)
mixed$t_stat <- (mixed$mT-mixed$mC)/sp/sqrt(1/mixed$nT+1/mixed$nC)
mixed$f_stat <- mixed$t_stat^2
mixed$p_exact <- 2*pt(abs(mixed$t_stat), df=nu, lower.tail=FALSE)
mixed$residual_df <- nu
mixed$sign <- ifelse(mixed$t_stat < 0, -1, 1)
mixed$reported <- rep(c("means_sd","student_t","anova_f","p_value"),4)

mixed_es <- compute_es(
  mixed, design="independent_groups", input=reported,
  m1=mT, sd1=sdT, n1=nT, m2=mC, sd2=sdC, n2=nC,
  t=t_stat, f=f_stat, df=residual_df, df1=1,
  p=p_exact, effect_sign=sign, study_id=Study
)
stopifnot(isTRUE(all.equal(mixed_es$data$yi, es$data$yi, tolerance=1e-10)))
head(mixed_es$provenance[, c("effect_id","route_id","applied","variance_method")])
#>   effect_id         route_id applied variance_method
#> 1         1  smd.means_sd.v1    TRUE              LS
#> 2         2 smd.student_t.v1    TRUE              LS
#> 3         3   smd.anova_f.v1    TRUE              LS
#> 4         4   smd.p_value.v1    TRUE              LS
#> 5         5  smd.means_sd.v1    TRUE              LS
#> 6         6 smd.student_t.v1    TRUE              LS

Only statistics required for a row’s selected route are used. Other available statistics do not override the route or trigger selection of the largest effect. The t route uses the signed test statistic; F and p routes require an explicit effect_sign. The residual df must equal n1+n2-2.

p < .05 does not identify an exact effect. Neither does a p-value printed as zero. These inputs are rejected; do not replace them with arbitrary small numbers. One-sided p-values must not be supplied as two-sided probabilities. They need a separately justified reconstruction outside this first release.

Diagnostics and traceability

incomplete <- mixed
incomplete$residual_df[2] <- NA_real_
check <- compute_es(incomplete, design="independent_groups", input=reported,
  m1=mT,sd1=sdT,n1=nT,m2=mC,sd2=sdC,n2=nC,
  t=t_stat,f=f_stat,df=residual_df,df1=1,p=p_exact,effect_sign=sign)
check$diagnostics
#>   effect_id        status      message
#> 2         2 missing_input Required: df

The default errors="collect" retains every input row. Failed rows generally have missing effect estimates and a status describing missing information, invalid input, an incompatible design, an unsupported route, or a numerical failure. With residual df <= 2, a variance_unavailable row retains the point estimate but withholds variance and intervals because the normal-theory SMD variance is not finite. errors="stop" stops the call if any row lacks a complete result. Unresolvable column expressions, invalid vector lengths, and duplicate effect IDs are call-level errors in either mode.

es$provenance records routes, sources, versions, and whether calculation succeeded. es$assumptions records the model assumptions. as.data.frame(es) returns every result row, including failed rows; it does not silently select a successful subset.

Choose MD, pooled-SD SMD, or Glass’s delta

Use MD when studies measure an outcome in the same units and a difference in those units is meaningful. Its estimate is m1-m2, with variance sd1^2/n1+sd2^2/n2; equal population variances are not required. No Hedges correction is applied. Output intervals use normal Wald quantiles, not Welch-t quantiles, so small-sample coverage is approximate.

Use SMD to express the contrast in pooled-SD units under the common-variance model. Use GLASS when a specific reference arm’s SD defines the relevant scale, for example when treatment may change outcome variability. Choose the reference arm on substantive grounds before examining the resulting effects. Neither standardized metric makes different outcome constructs interchangeable.

continuous <- data.frame(m1=12, sd1=5, n1=20, m2=10, sd2=2, n2=30)
md <- compute_es(continuous, measure="MD", design="independent_groups",
  input="means_sd", m1=m1, sd1=sd1, n1=n1, m2=m2, sd2=sd2, n2=n2)
glass <- compute_es(continuous, measure="GLASS", design="independent_groups",
  input="means_sd", m1=m1, sd1=sd1, n1=n1, m2=m2, sd2=sd2, n2=n2,
  reference_group=2)
rbind(md$data, glass$data)[,c("measure","metric","yi","vi","correction","variance_method")]
#>   measure                metric       yi        vi   correction variance_method
#> 1      MD       mean_difference 2.000000 1.3833333         none              LS
#> 2   GLASS glass_delta_corrected 0.973875 0.3797824 hedges_exact             HET

GLASS always uses m1-m2 for its numerator. reference_group=1 or 2 selects only the SD denominator. If you reverse the arm labels while retaining the same physical reference group, also reverse reference_group; then the sign changes and the variance stays the same. Changing the physical reference changes the standardized estimand.

The default Glass correction uses J(n_reference-1). Request correction="none" for uncorrected Glass’s delta. With reference sample size 2, corrected delta is unavailable; the raw delta remains in d. With reference sample size at most 3, sampling variance and confidence limits are unavailable.

The default Glass variance method, HET, follows the metafor SMD1H convention. With reference arm r and other arm o, it is (sd_o/sd_r)^2/(n_o-1) + 1/(n_r-1) + yi^2/(2*(n_r-1)). Explicit variance_method="LS" or "J2_LS" instead assumes equal population variances and uses the SMD1 conventions documented in ?compute_es. These variance estimators and the normal intervals are approximations even when bias correction is exact. See the metafor reference.

MD and GLASS also accept the means_se and means_ci routes under the same explicit reconstruction requirements described above. They do not accept the pooled-test or combined-sample-SD routes. Both individual arm SDs must be supplied or reconstructed. To use subgroup summaries, take the helper’s aggregation$contrasts as input to the chosen measure and retain its source map.

mixed <- continuous[rep(1,3),]
mixed$target <- c("MD","SMD","GLASS")
comparison <- compute_es(mixed, measure=target, design="independent_groups",
  input="means_sd", m1=m1, sd1=sd1, n1=n1, m2=m2, sd2=sd2, n2=n2,
  reference_group=2)
comparison$data[,c("measure","yi","vi","correction","variance_method")]
#>   measure       yi         vi   correction variance_method
#> 1      MD 2.000000 1.38333333         none              LS
#> 2     SMD 0.561016 0.08648072 hedges_exact              LS
#> 3   GLASS 0.973875 0.37978241 hedges_exact             HET
comparison$provenance[,c("route_id","variance_method")]
#>            route_id variance_method
#> 1    md.means_sd.v1              LS
#> 2   smd.means_sd.v1              LS
#> 3 glass.means_sd.v1             HET

These three rows illustrate alternative definitions for the same study; do not pool them together. Different measures need separate analyses. Omitted correction/variance options use measure-specific defaults; explicit options apply to every row and incompatible combinations receive diagnostics.

Correlations, partial correlations and Fisher’s z

COR uses Pearson’s r, and ZCOR uses Fisher’s z with variance 1/(n-3). Supply the number of independent observations; correlations sharing participants still need their sampling covariances for a joint analysis.

cor_data <- data.frame(study=c("A","B"), correlation=c(.3,-.2), sample=c(80,120))
z <- compute_es(cor_data, measure="ZCOR", design="independent_observations",
  input="correlation", r=correlation, n_total=sample, study_id=study)
z$data[,c("yi","vi","scale","status")]
#>   yi vi    scale      status
#> 1 NA NA fisher_z unsupported
#> 2 NA NA fisher_z unsupported
z$display  # correlation-scale estimates and limits
#>   effect_id estimate ci_lb ci_ub measure analysis_scale display_scale
#> 1         1       NA    NA    NA    ZCOR       fisher_z   correlation
#> 2         2       NA    NA    NA    ZCOR       fisher_z   correlation
#>        status message
#> 1 unavailable        
#> 2 unavailable        
#>                                                                                       note
#> 1 Back-transformed estimates/limits only; sampling variances remain on the analysis scale.
#> 2 Back-transformed estimates/limits only; sampling variances remain on the analysis scale.

For regression associations, PCOR/ZPCOR represent partial correlations and SPCOR/ZSPCOR semipartial correlations. Use design="ordinary_regression". predictors is the total number of slopes, including the focal predictor, excluding the intercept. For example, a focal predictor plus three controls means predictors=4, not 3. Enter the ordinary OLS t statistic and its residual df, or supply the reported (semi)partial r with input="correlation".

regression <- data.frame(t_value=c(2.5,-3), sample=c(100,150), slopes=c(4,3),
                         residual_df=c(95,146), full_R2=c(.35,.4))
partial <- compute_es(regression, measure="ZPCOR", design="ordinary_regression",
  input="regression_t", t=t_value, df=residual_df, n_total=sample, predictors=slopes)
semipartial <- compute_es(regression, measure="SPCOR", design="ordinary_regression",
  input="regression_t", t=t_value, df=residual_df, n_total=sample,
  predictors=slopes, r_squared=full_R2)
partial$display
#>   effect_id   estimate       ci_lb       ci_ub measure   analysis_scale
#> 1         1  0.2484520  0.05156167  0.42675073   ZPCOR fisher_z_partial
#> 2         2 -0.2409658 -0.38725385 -0.08284275   ZPCOR fisher_z_partial
#>         display_scale status message
#> 1 partial_correlation     ok        
#> 2 partial_correlation     ok        
#>                                                                                       note
#> 1 Back-transformed estimates/limits only; sampling variances remain on the analysis scale.
#> 2 Back-transformed estimates/limits only; sampling variances remain on the analysis scale.
semipartial$data[,c("yi","vi","status")]
#>           yi          vi status
#> 1  0.2067925 0.006353424     ok
#> 2 -0.1923182 0.003941565     ok

Semipartial r squared is the focal predictor’s increment in model R². Its variance requires the full model’s unadjusted R², even when r is reported directly. It must not exceed the full R². Fisher’s z is not variance stabilizing for semipartial correlations; ZSPCOR uses a delta-method variance, not 1/(n-3). Different adjustment sets can yield different estimands. Retain covariate lists in the original data and assess comparability before pooling. Robust/clustered, weighted, mixed-model and generalized-model t statistics are not eligible for these ordinary OLS reconstruction formulas.

Odds ratios, risk ratios and risk differences

The input is a 2-by-2 table of event and non-event counts. OR and RR return log ratios in data$yi; RD returns risk1 minus risk2. The display table back-transforms log ratios, but the variance remains on the log analysis scale.

binary <- data.frame(e1=c(12,0), ne1=c(38,40), e2=c(5,4), ne2=c(45,36))
odds <- compute_es(binary, measure="OR", design="independent_groups",
  input="binary_counts", events1=e1, non_events1=ne1,
  events2=e2, non_events2=ne2, zero_cell="add_half")
odds$data[,c("yi","vi","status")]
#>          yi        vi status
#> 1  1.044545 0.3318713     ok
#> 2 -2.301214 2.2743108     ok
odds$display
#>   effect_id  estimate       ci_lb    ci_ub measure analysis_scale display_scale
#> 1         1 2.8421053 0.918919834 8.790280      OR log_odds_ratio    odds_ratio
#> 2         2 0.1001372 0.005210912 1.924318      OR log_odds_ratio    odds_ratio
#>   status message
#> 1     ok        
#> 2     ok        
#>                                                                                       note
#> 1 Back-transformed estimates/limits only; sampling variances remain on the analysis scale.
#> 2 Back-transformed estimates/limits only; sampling variances remain on the analysis scale.
odds$reconstruction$note
#> [1] ""                                                               
#> [2] "Added 0.5 to all four cells because at least one cell was zero."
risk_difference <- compute_es(binary, measure="RD", design="independent_groups",
  input="binary_counts", events1=e1, non_events1=ne1,
  events2=e2, non_events2=ne2, zero_cell="none")
risk_difference$data[,c("yi","vi","status")]
#>      yi       vi status
#> 1  0.14 0.005448     ok
#> 2 -0.10 0.002250     ok

zero_cell must be chosen explicitly. none retains the counts; add_half adds 0.5 to all four cells only when at least one is zero. The example shows how to request that correction, not a recommendation to always use it. Compare sensitivity to the policy for sparse studies. Both-zero event arms do not produce an OR/RR, even with correction; OR also excludes both-all-event arms. RD uses uncorrected counts and can remain informative when one arm has no events. Rows with zero variance receive diagnostics instead of infinite weights. These routes assume independent binomial groups and do not handle matched pairs.

Single proportions

Use PR for raw proportions, PLO for logit proportions and PLN for log proportions. Counts represent independent Bernoulli observations.

proportions <- data.frame(events=c(12,0), total=c(50,30))
prop <- compute_es(proportions, measure="PLO", design="single_group",
  input="proportion_counts", events=events, n_total=total, zero_cell="add_half")
prop$data[,c("yi","vi","status")]
#>          yi        vi status
#> 1 -1.152680 0.1096491     ok
#> 2 -4.110874 2.0327869     ok
prop$display
#>   effect_id   estimate       ci_lb     ci_ub measure   analysis_scale
#> 1         1 0.24000000 0.141645657 0.3766785     PLO logit_proportion
#> 2         2 0.01612903 0.001001445 0.2114114     PLO logit_proportion
#>   display_scale status message
#> 1    proportion     ok        
#> 2    proportion     ok        
#>                                                                                       note
#> 1 Back-transformed estimates/limits only; sampling variances remain on the analysis scale.
#> 2 Back-transformed estimates/limits only; sampling variances remain on the analysis scale.

For PLO/PLN, add_half acts only at a boundary: it adds 0.5 to events and non-events, increasing the total by 1. PR requires zero_cell="none". Uncorrected zero/all-event samples can have undefined estimates or zero variance; inspect diagnostics. Intervals are normal Wald intervals on the chosen scale, not exact binomial or Wilson intervals. Raw-scale limits are not clipped; PR limits, and back-transformed PLN upper limits, can exceed probability bounds.

Incidence, response and hazard ratios

IRR compares independent Poisson event rates using person-time in comparable units. It does not account for overdispersion or within-person dependence.

rates <- data.frame(events1=12, events2=5, time1=100, time2=80)
rate_ratio <- compute_es(rates, measure="IRR", design="independent_groups",
  input="incidence_counts", events1=events1, events2=events2,
  person_time1=time1, person_time2=time2, zero_cell="none")
rate_ratio$display
#>   effect_id estimate     ci_lb    ci_ub measure analysis_scale display_scale
#> 1         1     1.92 0.6764171 5.449891     IRR log_rate_ratio    rate_ratio
#>   status message
#> 1     ok        
#>                                                                                       note
#> 1 Back-transformed estimates/limits only; sampling variances remain on the analysis scale.

With zero_cell="add_half", one zero count triggers addition of 0.5 to both counts, leaving exposure unchanged. Both-zero counts remain uninformative.

ROM is the log ratio of arithmetic means. It requires positive means on a meaningful ratio scale; adding a constant to the measurement scale changes the estimand. Eligible arm SE/CI reconstruction is also supported.

response_ratio <- compute_es(continuous, measure="ROM", design="independent_groups",
  input="means_sd", m1=m1, sd1=sd1, n1=n1, m2=m2, sd2=sd2, n2=n2)
response_ratio$display
#>   effect_id estimate    ci_lb    ci_ub measure     analysis_scale
#> 1         1      1.2 0.986284 1.460026     ROM log_response_ratio
#>    display_scale status message
#> 1 response_ratio     ok        
#>                                                                                       note
#> 1 Back-transformed estimates/limits only; sampling variances remain on the analysis scale.

HR accepts a reported log hazard ratio and its log-scale SE. It preserves the reported model result and adjustment status; it does not infer a hazard ratio from crude event counts. Record the model and adjustment variables too.

hazards <- data.frame(log_hr=log(.7), se_log_hr=.15, covariates="age, baseline severity")
hazard_ratio <- compute_es(hazards, measure="HR", design="survival",
  input="reported_log_se", estimate=log_hr, estimate_se=se_log_hr, adjustment="adjusted")
hazard_ratio$display
#>   effect_id estimate     ci_lb     ci_ub measure   analysis_scale display_scale
#> 1         1      0.7 0.5216964 0.9392437      HR log_hazard_ratio  hazard_ratio
#>   status message
#> 1     ok        
#>                                                                                       note
#> 1 Back-transformed estimates/limits only; sampling variances remain on the analysis scale.

A common hazard-ratio interpretation requires an appropriate proportional-hazards model. The raw-scale HR’s SE cannot be used as the SE of log HR.

For every family, analyze data$yi with data$vi. Never pair back-transformed display estimates with analysis-scale variances, and never pool unlike metrics merely because they share the same output columns. Formula definitions, assumptions and boundary policies are in the installed compute-es/FAMILIES.md.

Semipartial Fisher z and explicit uncertainty transformations

You can request measure="ZSPCOR" directly from a reported semipartial r or an eligible OLS t statistic. The implementation first obtains the semipartial correlation and its own full-model-R²-dependent variance. It then calculates

z_{sp}=\operatorname{atanh}(r_{sp}),\qquad v_{z_{sp}}=\frac{v_{r_{sp}}}{(1-r_{sp}^2)^2}.

It does not use 1/(n-3) or the partial-correlation Fisher variance. Semipartial r has a different sampling distribution; its Fisher transform is not variance stabilizing and does not guarantee normality or accurate small- sample coverage. Choose SPCOR or ZSPCOR deliberately, keep their analysis scales distinct, and do not transform an already Fisher-transformed estimate again. Comparable adjustment sets remain necessary on either scale.

sp_z <- compute_es(regression, measure="ZSPCOR", design="ordinary_regression",
  input="regression_t", t=t_value, df=residual_df, n_total=sample,
  predictors=slopes, r_squared=full_R2)
sp_delta <- transform_es(semipartial, "fisher_z")
stopifnot(isTRUE(all.equal(sp_z$data$yi, sp_delta$data$yi)),
          isTRUE(all.equal(sp_z$data$vi, sp_delta$data$vi)))
sp_z$provenance[,c("variance_formula","variance_basis")]
#>    variance_formula    variance_basis
#> 1 v_SPCOR/(1-r^2)^2 first_order_delta
#> 2 v_SPCOR/(1-r^2)^2 first_order_delta
sp_z$inference_notes
#>   effect_id                     code
#> 1         1 semipartial_distribution
#> 2         2 semipartial_distribution
#>                                                                                                                                                     message
#> 1 Semipartial variance depends on full-model R-squared under random-X normal theory. Fisher z is not variance stabilizing and does not guarantee normality.
#> 2 Semipartial variance depends on full-model R-squared under random-X normal theory. Fisher z is not variance stabilizing and does not guarantee normality.

transform_es() is a separate, opt-in first-order delta operation. Named options are fisher_z, inverse_fisher, log, exp, logit and inverse_logit. The result retains original_result, derivative/Jacobian provenance, diagnostics and target-scale variances. Its confidence limits are target-scale delta-Wald intervals; these generally differ from transforming the endpoints of source intervals, which compute_es()$display already does.

raw_prop <- compute_es(data.frame(x=c(12,20),n=c(50,80)), measure="PR",
  design="single_group", input="proportion_counts", events=x, n_total=n,
  zero_cell="none")
logit_prop <- transform_es(raw_prop,"logit")
logit_prop$data
#>   effect_id        yi         vi       sei     ci_lb      ci_ub
#> 1         1 -1.152680 0.10964912 0.3311331 -1.801688 -0.5036706
#> 2         2 -1.098612 0.06666667 0.2581989 -1.604673 -0.5925518
#>              scale source_scale status message
#> 1 logit_proportion   proportion     ok        
#> 2 logit_proportion   proportion     ok
stopifnot(is.null(logit_prop$sampling_covariance))

Marginal variances alone do not establish independence. When a full covariance matrix is known, provide it as V; named rows/columns are aligned to effect IDs. The following covariance is illustrative, not an estimate inferred from the proportion data. Replace it with a justified study covariance.

V_example <- diag(raw_prop$data$vi)
V_example[1,2] <- V_example[2,1] <- .2*sqrt(prod(raw_prop$data$vi))
dimnames(V_example) <- list(raw_prop$data$effect_id, raw_prop$data$effect_id)
joint <- transform_es(raw_prop,"logit",V=V_example)
joint$sampling_covariance
#>            1          2
#> 1 0.10964912 0.01709964
#> 2 0.01709964 0.06666667

Custom scalar functions require an analytic derivative and target_scale. Multivariate functions require an analytic jacobian and a full covariance matrix, propagating uncertainty as D %*% V %*% t(D). Missing off-diagonal covariances are never replaced with zero.

contrast <- transform_es(raw_prop, function(y) y[1]-y[2],
  jacobian=function(y) matrix(c(1,-1),nrow=1), V=V_example,
  target_scale="proportion_contrast", output_ids="contrast")
contrast$data
#>   effect_id    yi          vi        sei     ci_lb    ci_ub               scale
#> 1  contrast -0.01 0.004822135 0.06944159 -0.146103 0.126103 proportion_contrast
#>      source_scale status message
#> 1 multiple_inputs     ok

Delta propagation does not supply additional model assumptions for conversions such as SMD to OR. It also does not reproduce every specialized variance convention: applying it to COR’s raw variance yields 1/(n-1), whereas direct ZCOR uses 1/(n-3). A zero derivative, as for squaring r at r=0, is flagged; first-order calculus cannot justify a zero sampling variance there.

Audit diagnostics, rounding and small-sample inference

Analysis diagnostics, display diagnostics and inference cautions have different purposes. A finite log estimate can be valid while its exponentiation overflows; display$status records that failure without discarding the analysis result. display now labels both analysis and display scales. A defined MD with zero estimated variance retains its point and receives variance_unavailable.

inference_notes flags sparse counts, small sample sizes and semipartial assumptions without changing analysis status or selecting rows. The thresholds of 5 counts and 30 observations/standardizer df are screening heuristics, not validated safe/unsafe boundaries. A lack of flags does not establish coverage.

For directly reported semipartial r/R², declared decimal precision can distinguish rounding ambiguity from a mathematical contradiction:

rounded <- compute_es(data.frame(r=.32,R2=.10), measure="SPCOR",
  design="ordinary_regression", input="correlation", r=r, r_squared=R2,
  n_total=100, predictors=1, r_digits=2, r_squared_digits=2)
rounded$data[,c("yi","vi","status","message")]
#>     yi vi             status
#> 1 0.32 NA rounding_ambiguous
#>                                                                                                                                                                          message
#> 1 Compatible with declared rounding, but exact summaries are inconsistent. Point retained; refine inputs or examine a rounding sensitivity analysis before assigning a variance.

Here the rounded intervals admit consistent underlying values, but the reported points do not satisfy the one-predictor identity exactly. The point is retained with rounding_ambiguous and no invented variance. Obtain more precision or perform a justified rounding sensitivity analysis; the function does not replace r or R² silently. Digits describe nearest rounding, not truncation.

The installed INFERENCE-EVALUATION.md records the audit’s limited simulation and interval comparison. Small-sample and sparse-data coverage problems remain; adding delta propagation does not repair them. In particular, filtering studies with unavailable proportion variances can select on the observed event rate. Wilson or likelihood intervals require separate inference methods; they should not be converted into ad hoc inverse-variance weights.

Construct covariance from shared arms

For MD, OR, RR, RD, ROM and IRR, compute_es_covariance() can attach shared-arm covariance without changing the effect estimates or their marginal variances. Specify every study, arm, outcome and time identity, and explicitly declare independent arms and studies. A repeated arm ID means the same participant set and summaries. Different arm IDs must identify disjoint groups.

shared <- data.frame(study=rep(c("s1","s2","s3"),each=2),
  active=rep(c("A","B"),3), control="C", outcome="score", time="post",
  m1=c(12,13,11,12,13,14), m2=10, sd1=3, sd2=2, n1=30, n2=25)
shared_es <- compute_es(shared, measure="MD", design="independent_groups",
  input="means_sd", m1=m1, m2=m2, sd1=sd1, sd2=sd2, n1=n1, n2=n2,
  study_id=study)
shared_es <- compute_es_covariance(shared_es, study_id=study,
  arm1=active, arm2=control, outcome_id=outcome, time_id=time,
  independent_arms=TRUE, independent_studies=TRUE)
shared_es$covariance_blocks$s1
#>      1    2
#> 1 0.46 0.16
#> 2 0.16 0.46
shared_es$covariance_provenance$arms
#>   study arm arm_key contribution variance original_summary used_summary
#> 1    s1   A    arm1           12     0.30        12, 3, 30    12, 3, 30
#> 2    s1   B    arm2           13     0.30        13, 3, 30    13, 3, 30
#> 3    s1   C    arm3           10     0.16        10, 2, 25    10, 2, 25
#> 4    s2   A    arm4           11     0.30        11, 3, 30    11, 3, 30
#> 5    s2   B    arm5           12     0.30        12, 3, 30    12, 3, 30
#> 6    s2   C    arm6           10     0.16        10, 2, 25    10, 2, 25
#> 7    s3   A    arm7           13     0.30        13, 3, 30    13, 3, 30
#> 8    s3   B    arm8           14     0.30        14, 3, 30    14, 3, 30
#> 9    s3   C    arm9           10     0.16        10, 2, 25    10, 2, 25
stopifnot(isTRUE(all.equal(unname(diag(shared_es$sampling_covariance)),shared_es$data$vi)))

Here each within-study covariance is the shared control variance 2^2/25=.16. If the same arm appears on opposite sides of two contrasts, the covariance is negative. A signed contrast matrix constructs both cases. transform_es() uses an attached covariance matrix automatically; it does not replace it with a diagonal matrix.

The constructor rejects contradictory shared-arm summaries, incompatible marginal variances, repeated outcomes/times without joint inputs, and unresolved effect rows. For zero-cell corrections, the same arm must have identical adjusted summaries in every comparison. For example, adding 0.5 to all four cells only in one of two comparisons can represent their shared control differently; that configuration is rejected. No averaging, count clipping or positive-definite repair occurs.

Use an existing fitter that accepts an explicit sampling covariance matrix:

network_data <- shared_es$data
network_data$first <- shared_es$covariance_provenance$identities$arm2
network_data$second <- shared_es$covariance_provenance$identities$arm1
# The network fitter uses treatment_2 minus treatment_1.
shared_fit <- network_meta_coherent(network_data, study_id="study_id",
  treatment_1="first", treatment_2="second", effect="yi", variance="vi",
  observation_id="effect_id", reference="C", heterogeneity="none",
  sampling_covariance=shared_es$sampling_covariance, diagnostics=FALSE)
shared_fit$fit_coefficients
#>   term estimate std_error  df   se_source  z_value      p_value
#> 1  d_A        2  0.391578 Inf model_based 5.107539 3.263814e-07
#> 2  d_B        3  0.391578 Inf model_based 7.661309 1.840478e-14

This example uses common-effect network GLS with the supplied dependence. Do not send these rows through a diagonal/univariate covariance constructor. Redundant contrasts can yield a singular matrix; choose an independent contrast set for fitters requiring positive definite covariance. Partial participant overlap and joint partial/semipartial effects require further covariance methods. See the installed compute-es/COVARIANCE.md specification.

Covariance for repeated outcomes and other effect sizes

Covariance requires both an effect-size formula and a declared dependence structure. We support shared arms and multiple outcomes/times measured on the same participants. Partial participant overlap is not inferred. The complete formula reference is installed at system.file("compute-es", "COVARIANCE.md", package="mars").

Proportions and binary contrasts

For binary outcomes j,k on the same n participants, supply the number with both outcomes, a_{jk}. If p_j=a_j/n, the primitive covariance is

B_{jk}=(a_{jk}/n-p_jp_k)/n.

For PR/RD use derivative 1; for PLN/RR use 1/p; for PLO/OR use 1/[p(1-p)]. Apply these derivatives and the arm contrast signs in D, giving V=DBD^T. Joint counts must satisfy \max(0,a_j+a_k-n)\leq a_{jk}\leq\min(a_j,a_k). Every within-arm measurement pair needs an explicit row, even if dependence is zero.

bin <- data.frame(outcome=c("response","remission"),
                  e1=c(25,30), b1=c(75,70), e2=c(20,25), b2=c(80,75))
joint <- data.frame(study_id="s1", arm_id=c("T","C"),
  outcome1="response", time1="post", outcome2="remission", time2="post",
  joint_events=c(14,8))
ors <- compute_es(bin, measure="OR", design="independent_groups",
  input="binary_counts", events1=e1, non_events1=b1,
  events2=e2, non_events2=b2, zero_cell="none")
ors <- compute_es_covariance(ors, study_id="s1", arm1="T", arm2="C",
  outcome_id=outcome, time_id="post", independent_arms=TRUE,
  independent_studies=TRUE, same_participants=TRUE, dependence=joint)
ors$sampling_covariance
#>            1          2
#> 1 0.11583333 0.02650794
#> 2 0.02650794 0.10095238
stopifnot(isTRUE(all.equal(unname(diag(ors$sampling_covariance)), ors$data$vi)))

props <- compute_es(bin, measure="PR", design="single_group",
  input="proportion_counts", events=e1, n_total=100, zero_cell="none")
props <- compute_es_covariance(props, study_id="s1", arm1="T",
  outcome_id=outcome, time_id="post", independent_arms=TRUE,
  independent_studies=TRUE, same_participants=TRUE,
  dependence=joint[joint$arm_id=="T",])
stopifnot(abs(props$sampling_covariance[1,2]-(.14-.25*.30)/100)<1e-12)

Use RR/RD or PLO/PLN with the same inputs and identities. Changing a measure changes its derivatives and analysis scale. Actual continuity corrections cannot be combined with repeated-outcome joint counts, because a joint pseudo-count allocation has not been specified. Pairwise bounds and a PSD matrix do not alone prove multivariate binary feasibility; joint counts should come from coherent participant records.

Incidence ratios

For counts N_j,N_k and fixed person-time exposures, use the aggregate-count sampling covariance B_{jk}=\operatorname{Cov}(N_j,N_k), with Poisson diagonal B_{jj}=N_j. Signed derivatives 1/N_j give V=DBD^T. A binary joint-event count does not determine recurrent-event count covariance.

rates <- data.frame(outcome=c("visits","episodes"), e1=c(40,50), e2=c(20,30))
irrs <- compute_es(rates, measure="IRR", design="independent_groups",
  input="incidence_counts", events1=e1, events2=e2,
  person_time1=1000, person_time2=800, zero_cell="none")
count_dep <- data.frame(study_id="s1", arm_id=c("T","C"),
  outcome1="visits", time1="post", outcome2="episodes", time2="post",
  count_covariance=c(10,5))
irrs <- compute_es_covariance(irrs, study_id="s1", arm1="T", arm2="C",
  outcome_id=outcome, time_id="post", independent_arms=TRUE,
  independent_studies=TRUE, same_participants=TRUE, dependence=count_dep)
stopifnot(abs(irrs$sampling_covariance[1,2]-(10/(40*50)+5/(20*30)))<1e-12)

Here 10 and 5 are illustrative supplied count covariances, not values estimated from the marginal counts. Their model must support the Poisson diagonal and same-cohort interpretation. Their own estimation uncertainty is not propagated.

SMD and Glass delta

Select variance_method="JOINT_DELTA" explicitly when computing the effects. For y_i=J_i(m_{i1}-m_{i2})/\sqrt{q_i}, q_i=\sum_h w_{ih}s_h^2, use pooled weights (n_h-1)/(n_1+n_2-2) for SMD, or weight 1 on the reference arm for GLASS. The derivatives are signed J_i/\sqrt{q_i} for the means and -y_iw_{ih}/(2q_i) for each sample variance. Under multivariate normality,

\operatorname{Cov}(\bar X_j,\bar X_k)=r_{jk}s_js_k/n,\qquad \operatorname{Cov}(s_j^2,s_k^2)=2r_{jk}^2s_j^2s_k^2/(n-1),

with zero mean/variance cross covariance. Assemble these blocks in \Sigma and calculate V=D\Sigma D^T. Its diagonal is

V_{ii}=J_i^2(s_{i1}^2/n_{i1}+s_{i2}^2/n_{i2})/q_i +\frac{y_i^2}{2q_i^2}\sum_h\frac{w_{ih}^2s_h^4}{n_h-1}.

continuous <- data.frame(outcome=c("score1","score2"),
  m1=c(4,5), m2=c(2,3), s1=c(2,3), s2=c(1,2), n1=60, n2=50)
continuous_dep <- data.frame(study_id="study1", arm_id=c("T","C"),
  outcome1="score1", time1="post", outcome2="score2", time2="post",
  correlation=c(.6,.4))
for (metric in c("SMD","GLASS")) {
  standardized <- compute_es(continuous, measure=metric,
    design="independent_groups", input="means_sd", m1=m1, m2=m2,
    sd1=s1, sd2=s2, n1=n1, n2=n2, reference_group=2,
    variance_method="JOINT_DELTA")
  standardized <- compute_es_covariance(standardized, study_id="study1",
    arm1="T", arm2="C", outcome_id=outcome, time_id="post",
    independent_arms=TRUE, independent_studies=TRUE, same_participants=TRUE,
    dependence=continuous_dep)
  print(standardized$sampling_covariance)
  stopifnot(isTRUE(all.equal(unname(diag(standardized$sampling_covariance)),
                            standardized$data$vi)))
}
#>            1          2
#> 1 0.04152323 0.01957965
#> 2 0.01957965 0.03677746
#>           1          2
#> 1 0.1235873 0.04000430
#> 2 0.0400043 0.06563514

The exact Hedges correction is J(\nu)=\Gamma(\nu/2)/[\sqrt{\nu/2} \Gamma((\nu-1)/2)]; the approximate correction is 1-3/(4\nu-1), and correction="none" uses 1. Degrees of freedom are n_1+n_2-2 for SMD and n_r-1 for GLASS. The covariance remains a first-order approximation regardless of the correction choice. LS/J2_LS/HET defaults are unchanged and cannot be silently combined with this joint covariance. Shared-arm-only SMD/GLASS calls need no dependence table. Separate arm SDs (or eligible SE/CI reconstructions) are required.

Pearson and Fisher-z correlations

For r_{ab} and r_{cd} from a common sample, define

\begin{aligned} 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). \end{aligned}

COR uses K/(n-1); ZCOR uses K/[(n-3)(1-r_{ab}^2)(1-r_{cd}^2)]. These reproduce the existing marginal conventions. They require all relevant cross correlations, even when the target effects share no variables.

R <- matrix(c(1,.3,.4, .3,1,.5, .4,.5,1),3,3,
  dimnames=list(c("x","y","z"),c("x","y","z")))
cor_dat <- data.frame(v1=c("x","x"), v2=c("y","z"), r=c(.3,.4), n=100)
zs <- compute_es(cor_dat, measure="ZCOR", design="independent_observations",
  input="correlation", r=r, n_total=n)
zs <- compute_es_covariance(zs, study_id="s1", variable1=v1, variable2=v2,
  correlation_matrices=list(s1=R), common_sample=TRUE, independent_studies=TRUE)
zs$sampling_covariance
#>             1           2
#> 1 0.010309278 0.004652932
#> 2 0.004652932 0.010309278
stopifnot(isTRUE(all.equal(unname(diag(zs$sampling_covariance)),zs$data$vi)))

The matrices must be complete, named and PSD, and n must be identical within a study and at least 5. Missing correlations are not zero. transform_es() applied to a COR result uses ordinary delta propagation and retains n-1, so it is not identical to direct ZCOR covariance. These formulas do not cover partial or semipartial correlations. See Steiger (1980) for the sampling covariance of dependent correlations and Oehlert (1992) for delta-method covariance propagation.

Fit a model in mars

For this example there is one effect per independent study. Inspect diagnostics before deliberately selecting the rows and columns used in the analysis.

stopifnot(nrow(es$diagnostics)==0L, !anyDuplicated(es$data$study_id))
analysis_data <- es$data[, c("study_id","yi","vi")]
fit <- mars(analysis_data, formula=yi~1, studyID="study_id",
            variance="vi", varcov_type="univariate", structure="univariate")
summary(fit)$beta
#>     attribute   estimate        SE    z_test     p_value      lower      upper
#> 1 (Intercept) -0.3436403 0.1047541 -3.280449 0.001036421 -0.5489545 -0.1383261

sampling_covariance=NULL means covariance between effects has not been computed. It does not mean independence. Multiple outcomes, shared controls, or repeated measurements require an appropriate covariance construction and model; a diagonal matrix must not be inferred from this result automatically. Existing specialized mars functions retain their own statistical definitions. For example, HSMD uses reconstructed standardizers and different default correction/variance conventions; this release does not change those functions.

Scope and references

Supported conversions are listed in es_methods(). Paired/change-score designs, clustered test reconstructions and partially overlapping participant sets require other methods. Supported routes do not establish complete coverage of Lipsey and Wilson (2001), Appendix B.

References: Lipsey and Wilson (2001), Practical Meta-Analysis, Appendix B; Hedges (1981), distribution theory for standardized effects; Wilson’s companion calculator.

The installed compute-es resource directory provides formula definitions, assumptions and validation details. Locate it with system.file("compute-es", package="mars"); see FAMILIES.md, COVARIANCE.md, TRANSFORMATIONS.md and INFERENCE-EVALUATION.md.

Covariance after combining subgroups

Aggregation reconstructs arm summaries from disjoint subgroups. The original subgroup rows remain in original_data, and effect_data contains one comparison per effect with study, outcome and time identities. Covariance identifiers are resolved against effect_data for these results. Aggregation does not infer independence across outcomes or supply their correlations.

subgroups <- data.frame(study="s1", arm=rep(c("T", "C"), each=2),
  subgroup=rep(c("a", "b"), 2), mean=c(12, 13, 10, 11), sd=3, n=20)
aggregated <- aggregate_es_subgroups(subgroups,
  study_id=study, arm_id=arm, subgroup_id=subgroup,
  mean=mean, sd=sd, n=n, group1="T", group2="C", disjoint=TRUE,
  variance_method="JOINT_DELTA")
aggregated <- compute_es_covariance(aggregated, study_id=study_id,
  arm1="T", arm2="C", outcome_id=outcome_id, time_id=time_id,
  independent_arms=TRUE, independent_studies=TRUE)
aggregated$sampling_covariance
#>            es1
#> es1 0.05182584

For repeated outcomes/times, additionally declare same_participants=TRUE and supply every required within-arm measurement correlation in dependence. These declarations require the same complete participant set at both measurements; disjoint subgroups at one measurement do not establish this. Use JOINT_DELTA at the aggregation step for SMD covariance. Existing LS or J2_LS marginal variances are never replaced automatically.

Standardized delta calculations use SD ratios internally so a change of units does not create overflow in intermediate fourth powers. Continuous joint covariance provenance records standardized summary coordinates and their SD scales. Its jacobian and primitive_covariance use those same coordinates, so their matrix product reconstructs the final sampling covariance. This numerical scaling does not change the effect estimand or variance method.

References

Aloe, A. M., and Becker, B. J. (2012). An Effect Size for Regression Predictors in Meta-Analysis. Journal of Educational and Behavioral Statistics, 37(2), 278–297. https://doi.org/10.3102/1076998610396901.

Aloe, A. M., and Thompson, C. G. (2013). The Synthesis of Partial Effect Sizes. Journal of the Society for Social Work and Research, 4(4), 390–405. https://doi.org/10.5243/jsswr.2013.24.

Aloe, A. M. (2014). An Empirical Investigation of Partial Effect Sizes in Meta-Analysis of Correlational Data. The Journal of General Psychology, 141(1), 47–64. https://doi.org/10.1080/00221309.2013.853021.

Hedges, L. V. (1981). Distribution Theory for Glass’s Estimator of Effect Size and Related Estimators. Journal of Educational Statistics, 6(2), 107–128. https://doi.org/10.3102/10769986006002107.

Hedges, L. V., Gurevitch, J., and Curtis, P. S. (1999). The Meta-Analysis of Response Ratios in Experimental Ecology. Ecology, 80(4), 1150–1156. https://doi.org/10.1890/0012-9658(1999)080[1150:TMAORR]2.0.CO;2.

Lajeunesse, M. J. (2011). On the Meta-Analysis of Response Ratios for Studies with Correlated and Multi-Group Designs. Ecology, 92(11), 2049–2055. https://doi.org/10.1890/11-0423.1.

Lipsey, M. W., and Wilson, D. B. (2001). Practical Meta-Analysis. Sage Publications.

Wilson, D. B. (2023). Practical Meta-Analysis Effect Size Calculator. Version 2023.11.27. Campbell Collaboration. https://www.campbellcollaboration.org/calculator/.