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.

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]])

estimate¶

Pooled effect size.

Type:: float

se¶

Standard error of the pooled estimate.

Type:: float

ci_lower¶

Lower bound of the confidence interval.

Type:: float

ci_upper¶

Upper bound of the confidence interval.

Type:: float

z_value¶

Test statistic for the pooled estimate (estimate / se).

Type:: float

p_value¶

Two-sided p-value for the test of estimate = 0.

Type:: float

tau2¶

Between-study variance (0 for fixed-effects).

Type:: float

tau2_se¶

Standard error of tau2 (method-dependent; None if unavailable).

Type:: float or None

tau¶

Square root of tau2.

Type:: float

I2¶

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

Type:: float

H2¶

H-squared statistic (ratio of total to sampling variability).

Type:: float

Q¶

Cochran’s Q statistic for heterogeneity.

Type:: float

Q_df¶

Degrees of freedom for the Q test.

Type:: int

Q_p¶

p-value for the Q test (chi-squared distribution).

Type:: float

k¶

Number of studies.

Type:: int

method¶

Estimation method: ‘FE’, ‘DL’, ‘REML’, or ‘PM’.

Type:: str

conf_level¶

Confidence level used for intervals.

Type:: float

weights¶

Study weights used in the final pooling.

Type:: NDArray

yi¶

Input effect sizes.

Type:: NDArray

vi¶

Input sampling variances.

Type:: NDArray

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