ADR 0007: Fisher's z correlation pooling

  • Status: Accepted
  • Date: 2026-09-02

Context

Study-level correlations are common in behavioral, educational, and medical research. Directly pooling raw correlations is possible but their sampling distribution is bounded, asymmetric away from zero, and has a variance that depends on the underlying correlation. Fisher's r-to-z transformation is the standard first implementation in R meta and metafor and composes with the library's existing inverse-variance machinery.

The API also needs an explicit position on perfect correlations, very small samples, displayed values, and multiple correlations drawn from the same participants.

Decision

meta_correlation() accepts raw correlation and sample size n, but its first supported measure is only ZCOR:

y_i = atanh(r_i)
v_i = 1 / (n_i - 3)

All fitting and heterogeneity calculations use Fisher's z. Result display properties and plots use tanh to return the correlation scale. The result records effect_scale="fisher_z", display_scale="tanh", the transformation, variance equation, affected rows, and input sources.

Included correlations must be finite and strictly between -1 and 1. Sample sizes must be whole numbers of at least 4. The implementation does not clip perfect correlations or replace invalid sample sizes because either action would introduce an undocumented effect or variance.

The default is the library's random-effects inverse-variance policy: REML tau-squared and a normal confidence interval. Common effects, PM/DL, the two documented Hartung-Knapp options, shared prediction intervals, Q-profile heterogeneity intervals, subgroups, repeated-fit sensitivity, reports, and plots reuse their existing contracts.

Rows are assumed independent. Duplicate labels remain allowed and warned, but do not imply a dependence correction. Raw-correlation pooling (COR), dependent correlations, partial/rank correlations, and reliability corrections are deferred.

Validation

Committed fixtures generated by metafor::escalc(measure="ZCOR") and rma.uni() validate study effects, variances, common-effect and REML fits, weights, and back-transformation. Targeted and property-based tests cover domain boundaries, missing rows, sign symmetry, row-order invariance, subgroups, sensitivity refits, reports, and Matplotlib coordinates.

Consequences

  • users can supply pandas columns without calculating z values or variances;
  • model-scale and correlation-scale results remain distinguishable;
  • behavior matches a documented R workflow without importing R at runtime;
  • perfect correlations and samples smaller than four require an upstream, scientifically justified decision rather than silent repair;
  • users with dependent correlations must use a method outside the current univariate scope.