Meta-Analysis

Fixed-effects and random-effects meta-analysis matching R’s metafor::rma().

Meta-analysis: fixed-effects and random-effects pooling of study results.

Computes inverse-variance weighted pooled estimates, between-study heterogeneity (tau2), and heterogeneity diagnostics (Q, I2, H2).

Supports four estimation methods: - FE: Fixed-effects (common-effect) - DL: DerSimonian-Laird (random-effects, method-of-moments) - REML: Restricted maximum likelihood (random-effects) - PM: Paule-Mandel (random-effects, generalized Q)

Validates against: R metafor::rma()

class pystatsbio.meta.MetaSolution(result)[source]

Bases: SolutionReprMixin

Public result of a meta-analysis — a Solution wrapping Result[MetaParams].

Exposes every fit output as a read-only property plus the uniform .backend_name / .timing / .warnings / .info metadata and a Jupyter _repr_html_ (via SolutionReprMixin).

Parameters:

result (Result[MetaParams])

property backend_name: str
property timing: dict[str, float] | None
property warnings: tuple[str, ...]
property info: dict
property estimate: float
property se: float
property ci_lower: float
property ci_upper: float
property z_value: float
property p_value: float
property tau2: float
property tau2_se: float | None
property tau: float
property I2: float
property H2: float
property Q: float
property Q_df: int
property Q_p: float
property k: int
property method: str
property conf_level: float
property weights: ndarray[tuple[Any, ...], dtype[_ScalarT]]
property yi: ndarray[tuple[Any, ...], dtype[_ScalarT]]
property vi: ndarray[tuple[Any, ...], dtype[_ScalarT]]
summary()[source]

R-style summary matching metafor::rma() output.

Returns:

Multi-line human-readable summary of the meta-analysis.

Return type:

str

class pystatsbio.meta.MetaParams(estimate, se, ci_lower, ci_upper, z_value, p_value, tau2, tau2_se, tau, I2, H2, Q, Q_df, Q_p, k, method, conf_level, weights, yi, vi)[source]

Bases: object

Computed payload of a meta-analysis.

Variables:

  • estimate (float) – Pooled effect size.

  • se (float) – Standard error of the pooled estimate.

  • ci_lower (float) – Lower bound of the confidence interval.

  • ci_upper (float) – Upper bound of the confidence interval.

  • z_value (float) – Test statistic for the pooled estimate (estimate / se).

  • p_value (float) – Two-sided p-value for the test of estimate = 0.

  • tau2 (float) – Between-study variance (0 for fixed-effects).

  • tau2_se (float or None) – Standard error of tau2 (method-dependent; None if unavailable).

  • tau (float) – Square root of tau2.

  • I2 (float) – I-squared heterogeneity statistic (percentage, 0–100).

  • H2 (float) – H-squared statistic (ratio of total to sampling variability).

  • Q (float) – Cochran’s Q statistic for heterogeneity.

  • Q_df (int) – Degrees of freedom for the Q test.

  • Q_p (float) – p-value for the Q test (chi-squared distribution).

  • k (int) – Number of studies.

  • method (str) – Estimation method: ‘FE’, ‘DL’, ‘REML’, or ‘PM’.

  • conf_level (float) – Confidence level used for intervals.

  • weights (NDArray) – Study weights used in the final pooling.

  • yi (NDArray) – Input effect sizes.

  • vi (NDArray) – Input sampling variances.

Parameters:
estimate: float
se: float
ci_lower: float
ci_upper: float
z_value: float
p_value: float
tau2: float
tau2_se: float | None
tau: float
I2: float
H2: float
Q: float
Q_df: int
Q_p: float
k: int
method: str
conf_level: float
weights: ndarray[tuple[Any, ...], dtype[_ScalarT]]
yi: ndarray[tuple[Any, ...], dtype[_ScalarT]]
vi: ndarray[tuple[Any, ...], dtype[_ScalarT]]
pystatsbio.meta.rma(yi, vi, *, method='REML', conf_level=0.95)[source]

Random-effects (or fixed-effects) meta-analysis.

Matches R’s metafor::rma(yi, vi, method=…) for the common case of pre-computed effect sizes and sampling variances.

Parameters:

  • yi (ArrayLike) – Effect sizes (e.g., log odds ratios, standardized mean differences).

  • vi (ArrayLike) – Corresponding sampling variances (NOT standard errors).

  • method (str) – Estimation method. One of: - 'FE': fixed-effects (inverse-variance weighted) - 'DL': DerSimonian-Laird (default in many older packages) - 'REML': restricted maximum likelihood (default, recommended) - 'PM': Paule-Mandel

  • conf_level (float) – Confidence level for confidence intervals. Default 0.95.

Returns:

Solution wrapping the pooled estimate, heterogeneity statistics, and study weights, with a summary method and the uniform .backend_name/.timing/.warnings/.info accessors.

Return type:

MetaSolution

Raises:

  • ValidationError – If method is not one of the valid methods, or if inputs fail validation (wrong shape, negative variances, etc.).

  • ConvergenceError – If iterative optimization (REML, PM) fails to converge.

Examples

>>> import numpy as np
>>> from pystatsbio.meta import rma
>>> yi = np.array([-0.89, -1.59, -1.35])
>>> vi = np.array([0.035, 0.019, 0.014])
>>> result = rma(yi, vi, method='DL')
>>> print(f"Pooled: {result.estimate:.3f}, tau2: {result.tau2:.4f}")
pystatsbio.meta.cochran_q(yi, vi)[source]

Cochran’s Q statistic for heterogeneity.

Q = sum(w_i * (y_i - mu_FE)^2) where w_i = 1/v_i and mu_FE is the fixed-effects pooled estimate. The p-value is from a chi-squared distribution with df = k - 1.

Parameters:

  • yi (NDArray) – Effect sizes (1-D, length k >= 2).

  • vi (NDArray) – Sampling variances (1-D, same length as yi, all positive).

Returns:

(Q statistic, degrees of freedom, p-value).

Return type:

tuple of (float, int, float)

pystatsbio.meta.i_squared(Q, k)[source]

I-squared heterogeneity statistic.

I^2 = max(0, (Q - (k-1)) / Q) * 100

Measures the percentage of total variability due to between-study heterogeneity rather than sampling error.

Parameters:

  • Q (float) – Cochran’s Q statistic.

  • k (int) – Number of studies.

Returns:

I-squared as a percentage (0 to 100).

Return type:

float

pystatsbio.meta.h_squared(Q, k)[source]

H-squared heterogeneity statistic.

H^2 = Q / (k - 1)

Ratio of total variability to sampling variability. H^2 = 1 when there is no heterogeneity.

Parameters:

  • Q (float) – Cochran’s Q statistic.

  • k (int) – Number of studies.

Returns:

H-squared (>= 0).

Return type:

float