
Computing Effect Sizes from Reported Statistics
mars authors
Computing-Effect-Sizes.RmdSupported 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 implementedThe 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 okPositive 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
#> 6For 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 Bdisjoint=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 LSOnly 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: dfThe 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 HETGLASS 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 HETThese 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 okSemipartial 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 okzero_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.06666667Custom 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 okDelta 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-14This 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.06563514The 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.1383261sampling_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.05182584For 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/.