PyMetaAnalysis 0.1.0__py3-none-any.whl

meta_analyze/estimators/inverse_variance.py

@@ -0,0 +1,169 @@
+"""Common- and random-effects inverse-variance estimation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+from numpy.typing import NDArray
+from scipy.stats import norm, t
+
+from ..exceptions import InsufficientStudiesError, UnsupportedMethodError
+from ..heterogeneity import weighted_mean
+from .tau2 import Tau2Estimate, estimate_tau2
+
+
+@dataclass(frozen=True, slots=True)
+class InverseVarianceFit:
+    """Numerical outputs from an inverse-variance model."""
+
+    estimate: float
+    standard_error: float
+    ci_low: float
+    ci_high: float
+    prediction_interval: tuple[float, float] | None
+    weights: NDArray[np.float64]
+    normalized_weights: NDArray[np.float64]
+    tau2: Tau2Estimate | None
+    warnings: tuple[str, ...]
+
+
+def _confidence_interval(
+    *,
+    effect: NDArray[np.float64],
+    weights: NDArray[np.float64],
+    estimate: float,
+    classic_variance: float,
+    ci_method: str,
+    confidence_level: float,
+) -> tuple[float, float, float, tuple[str, ...]]:
+    alpha = 1.0 - confidence_level
+    warnings: list[str] = []
+
+    if ci_method == "normal":
+        variance = classic_variance
+        critical_value = float(norm.ppf(1.0 - alpha / 2.0))
+    else:
+        df = len(effect) - 1
+        if bool(np.all(effect == effect[0])):
+            # Weighted means can differ from an identical input value by one ULP,
+            # depending on the platform's floating-point reduction. The residual
+            # variation is mathematically zero in this case, so preserve that
+            # invariant explicitly instead of squaring the rounding error.
+            scale = 0.0
+        else:
+            residual = effect - estimate
+            scale = float(np.dot(weights, residual * residual) / df)
+        hk_variance = scale / float(np.sum(weights))
+        if ci_method == "hartung_knapp_adhoc":
+            variance = max(classic_variance, hk_variance)
+        else:
+            variance = hk_variance
+            if hk_variance < classic_variance:
+                warnings.append(
+                    "Hartung-Knapp produced a variance below the classic variance; "
+                    "use ci_method='hartung_knapp_adhoc' for lower-bound protection."
+                )
+        if variance == 0.0:
+            warnings.append(
+                "Hartung-Knapp variance is zero because the included effects have "
+                "no weighted residual variation."
+            )
+        critical_value = float(t.ppf(1.0 - alpha / 2.0, df=df))
+
+    standard_error = float(np.sqrt(variance))
+    margin = critical_value * standard_error
+    return estimate - margin, estimate + margin, standard_error, tuple(warnings)
+
+
+def fit_inverse_variance(
+    effect: NDArray[np.float64],
+    variance: NDArray[np.float64],
+    *,
+    model: str,
+    tau2_method: str,
+    ci_method: str,
+    confidence_level: float,
+    atol: float,
+    max_iter: int,
+) -> InverseVarianceFit:
+    """Fit a common- or random-effects inverse-variance model."""
+
+    if model == "random" and len(effect) < 2:
+        raise InsufficientStudiesError(
+            "A random-effects model requires at least two included studies."
+        )
+    if ci_method not in {"normal", "hartung_knapp", "hartung_knapp_adhoc"}:
+        raise UnsupportedMethodError(
+            "ci_method must be 'normal', 'hartung_knapp', or 'hartung_knapp_adhoc'."
+        )
+    if model == "common" and ci_method != "normal":
+        raise UnsupportedMethodError(
+            "Hartung-Knapp intervals are only supported for random-effects models."
+        )
+
+    tau2: Tau2Estimate | None
+    if model == "common":
+        tau2 = None
+        tau2_value = 0.0
+    else:
+        tau2 = estimate_tau2(
+            effect,
+            variance,
+            method=tau2_method,
+            atol=atol,
+            max_iter=max_iter,
+        )
+        tau2_value = tau2.value
+
+    denominator = variance + tau2_value
+    weights = 1.0 / denominator
+    variance_scale = float(np.min(denominator))
+    relative_weights = variance_scale / denominator
+    relative_weight_sum = float(np.sum(relative_weights))
+    normalized_weights = relative_weights / relative_weight_sum
+    estimate = weighted_mean(effect, relative_weights)
+    classic_variance = variance_scale / relative_weight_sum
+    ci_low, ci_high, standard_error, interval_warnings = _confidence_interval(
+        effect=effect,
+        weights=normalized_weights,
+        estimate=estimate,
+        classic_variance=classic_variance,
+        ci_method=ci_method,
+        confidence_level=confidence_level,
+    )
+
+    warnings = list(interval_warnings)
+    prediction_interval: tuple[float, float] | None = None
+    if model == "random":
+        if len(effect) >= 3:
+            prediction_df = len(effect) - 2
+            critical_value = float(
+                t.ppf(0.5 + confidence_level / 2.0, df=prediction_df)
+            )
+            # HTS uses the classic variance of the pooled mean. This remains
+            # independent of any Hartung-Knapp method used for the mean CI.
+            prediction_se = float(np.sqrt(tau2_value + classic_variance))
+            margin = critical_value * prediction_se
+            prediction_interval = (estimate - margin, estimate + margin)
+            if len(effect) < 5:
+                warnings.append(
+                    "Prediction intervals are especially uncertain with fewer "
+                    "than five included studies."
+                )
+        else:
+            warnings.append(
+                "A prediction interval requires at least three included studies."
+            )
+
+    return InverseVarianceFit(
+        estimate=estimate,
+        standard_error=standard_error,
+        ci_low=ci_low,
+        ci_high=ci_high,
+        prediction_interval=prediction_interval,
+        weights=weights,
+        normalized_weights=normalized_weights,
+        tau2=tau2,
+        warnings=tuple(warnings),
+    )

meta_analyze/estimators/mantel_haenszel.py

@@ -0,0 +1,101 @@
+"""Mantel-Haenszel common-effect estimators for binary outcomes.
+
+The pooled estimates and Greenland-Robins variance equations follow the
+publicly documented Review Manager 5 statistical algorithms.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+from numpy.typing import NDArray
+from scipy.stats import norm
+
+from ..exceptions import InvalidStudyDataError, UnsupportedMethodError
+
+
+@dataclass(frozen=True, slots=True)
+class MantelHaenszelFit:
+    """Numerical outputs from a Mantel-Haenszel common-effect model."""
+
+    estimate: float
+    standard_error: float
+    ci_low: float
+    ci_high: float
+    weights: NDArray[np.float64]
+    normalized_weights: NDArray[np.float64]
+
+
+def fit_mantel_haenszel(
+    a: NDArray[np.float64],
+    b: NDArray[np.float64],
+    c: NDArray[np.float64],
+    d: NDArray[np.float64],
+    *,
+    measure: str,
+    confidence_level: float,
+) -> MantelHaenszelFit:
+    """Fit a Mantel-Haenszel common-effect log OR or log RR."""
+
+    normalized_measure = measure.upper()
+    if normalized_measure not in {"OR", "RR"}:
+        raise UnsupportedMethodError(
+            "Mantel-Haenszel currently supports measure='OR' or measure='RR'."
+        )
+
+    total = a + b + c + d
+    n1 = a + b
+    n2 = c + d
+    if normalized_measure == "OR":
+        r = float(np.sum(a * d / total))
+        s = float(np.sum(b * c / total))
+        if r <= 0.0 or s <= 0.0:
+            raise InvalidStudyDataError(
+                "The exact Mantel-Haenszel OR is undefined because its pooled "
+                "cross-product is zero; set a positive mh_continuity_correction."
+            )
+
+        e = float(np.sum((a + d) * a * d / total**2))
+        f = float(np.sum((a + d) * b * c / total**2))
+        g = float(np.sum((b + c) * a * d / total**2))
+        h = float(np.sum((b + c) * b * c / total**2))
+        pooled = r / s
+        pooled_variance = 0.5 * (e / r**2 + (f + g) / (r * s) + h / s**2)
+        weights = b * c / total
+    else:
+        r = float(np.sum(a * n2 / total))
+        s = float(np.sum(c * n1 / total))
+        if r <= 0.0 or s <= 0.0:
+            raise InvalidStudyDataError(
+                "The exact Mantel-Haenszel RR is undefined because the pooled "
+                "event total is zero; set a positive mh_continuity_correction."
+            )
+
+        p = float(np.sum((n1 * n2 * (a + c) - a * c * total) / total**2))
+        pooled = r / s
+        pooled_variance = p / (r * s)
+        weights = c * n1 / total
+
+    if not np.isfinite(pooled_variance) or pooled_variance <= 0.0:
+        raise InvalidStudyDataError(
+            "Mantel-Haenszel produced a non-positive sampling variance."
+        )
+    weight_sum = float(np.sum(weights))
+    if weight_sum <= 0.0:
+        raise InvalidStudyDataError(
+            "Mantel-Haenszel study weights have a non-positive sum."
+        )
+
+    estimate = float(np.log(pooled))
+    standard_error = float(np.sqrt(pooled_variance))
+    critical_value = float(norm.ppf(0.5 + float(confidence_level) / 2.0))
+    margin = critical_value * standard_error
+    return MantelHaenszelFit(
+        estimate=estimate,
+        standard_error=standard_error,
+        ci_low=estimate - margin,
+        ci_high=estimate + margin,
+        weights=weights,
+        normalized_weights=weights / weight_sum,
+    )

meta_analyze/estimators/tau2.py

@@ -0,0 +1,182 @@
+"""Between-study variance estimators."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+import numpy as np
+from numpy.typing import NDArray
+from scipy.optimize import brentq
+
+from ..exceptions import ConvergenceError, UnsupportedMethodError
+from ..heterogeneity import generalized_q, weighted_mean
+
+
+@dataclass(frozen=True, slots=True)
+class Tau2Estimate:
+    """A between-study variance estimate and convergence metadata."""
+
+    value: float
+    method: str
+    converged: bool
+    iterations: int
+    boundary: bool
+
+
+def _find_upper_bound(
+    function: Callable[[float], float],
+    *,
+    initial: float,
+    max_expansions: int,
+) -> tuple[float, int]:
+    upper = max(float(initial), np.finfo(np.float64).tiny)
+    for expansion in range(max_expansions + 1):
+        value = function(upper)
+        if np.isfinite(value) and value <= 0.0:
+            return upper, expansion
+        upper *= 4.0
+        if not np.isfinite(upper):
+            break
+    raise ConvergenceError("Could not bracket a finite tau-squared solution.")
+
+
+def _dersimonian_laird(
+    effect: NDArray[np.float64], variance: NDArray[np.float64]
+) -> Tau2Estimate:
+    weights = 1.0 / variance
+    estimate = weighted_mean(effect, weights)
+    residual = effect - estimate
+    q = float(np.dot(weights, residual * residual))
+    df = len(effect) - 1
+    weight_sum = float(np.sum(weights))
+    c = weight_sum - float(np.dot(weights, weights)) / weight_sum
+    value = max(0.0, (q - df) / c)
+    return Tau2Estimate(
+        value=value,
+        method="DL",
+        converged=True,
+        iterations=0,
+        boundary=value == 0.0,
+    )
+
+
+def _paule_mandel(
+    effect: NDArray[np.float64],
+    variance: NDArray[np.float64],
+    *,
+    atol: float,
+    max_iter: int,
+) -> Tau2Estimate:
+    df = len(effect) - 1
+
+    def equation(tau2: float) -> float:
+        return generalized_q(effect, variance, tau2) - df
+
+    at_zero = equation(0.0)
+    if at_zero <= 0.0:
+        return Tau2Estimate(0.0, "PM", True, 0, True)
+
+    initial = max(float(np.var(effect, ddof=1)), float(np.max(variance)))
+    upper, expansions = _find_upper_bound(
+        equation, initial=initial, max_expansions=max_iter
+    )
+    try:
+        root, result = brentq(
+            equation,
+            0.0,
+            upper,
+            xtol=atol,
+            rtol=max(atol, 4.0 * np.finfo(np.float64).eps),
+            maxiter=max_iter,
+            full_output=True,
+            disp=False,
+        )
+    except (RuntimeError, ValueError) as error:
+        raise ConvergenceError("Paule-Mandel tau-squared estimation failed.") from error
+    if not result.converged:
+        raise ConvergenceError("Paule-Mandel tau-squared estimation did not converge.")
+    return Tau2Estimate(
+        value=max(0.0, float(root)),
+        method="PM",
+        converged=True,
+        iterations=expansions + result.iterations,
+        boundary=root <= atol,
+    )
+
+
+def _reml_score(
+    effect: NDArray[np.float64], variance: NDArray[np.float64], tau2: float
+) -> float:
+    weights = 1.0 / (variance + tau2)
+    estimate = weighted_mean(effect, weights)
+    residual = effect - estimate
+    weighted_square_residual = float(np.dot(weights * weights, residual * residual))
+    trace_p = float(np.sum(weights) - np.dot(weights, weights) / np.sum(weights))
+    return 0.5 * (weighted_square_residual - trace_p)
+
+
+def _restricted_maximum_likelihood(
+    effect: NDArray[np.float64],
+    variance: NDArray[np.float64],
+    *,
+    atol: float,
+    max_iter: int,
+) -> Tau2Estimate:
+    def score(tau2: float) -> float:
+        return _reml_score(effect, variance, tau2)
+
+    at_zero = score(0.0)
+    if at_zero <= 0.0:
+        return Tau2Estimate(0.0, "REML", True, 0, True)
+
+    initial = max(float(np.var(effect, ddof=1)), float(np.max(variance)))
+    upper, expansions = _find_upper_bound(
+        score, initial=initial, max_expansions=max_iter
+    )
+    try:
+        root, result = brentq(
+            score,
+            0.0,
+            upper,
+            xtol=atol,
+            rtol=max(atol, 4.0 * np.finfo(np.float64).eps),
+            maxiter=max_iter,
+            full_output=True,
+            disp=False,
+        )
+    except (RuntimeError, ValueError) as error:
+        raise ConvergenceError("REML tau-squared estimation failed.") from error
+    if not result.converged:
+        raise ConvergenceError("REML tau-squared estimation did not converge.")
+    return Tau2Estimate(
+        value=max(0.0, float(root)),
+        method="REML",
+        converged=True,
+        iterations=expansions + result.iterations,
+        boundary=root <= atol,
+    )
+
+
+def estimate_tau2(
+    effect: NDArray[np.float64],
+    variance: NDArray[np.float64],
+    *,
+    method: str,
+    atol: float = 1e-10,
+    max_iter: int = 1000,
+) -> Tau2Estimate:
+    """Estimate between-study variance using DL, PM, or REML."""
+
+    normalized_method = method.upper().replace("-", "_")
+    if normalized_method == "DL":
+        return _dersimonian_laird(effect, variance)
+    if normalized_method == "PM":
+        return _paule_mandel(effect, variance, atol=atol, max_iter=max_iter)
+    if normalized_method == "REML":
+        return _restricted_maximum_likelihood(
+            effect, variance, atol=atol, max_iter=max_iter
+        )
+    raise UnsupportedMethodError(
+        f"Unsupported tau2_method={method!r}; expected 'DL', 'PM', or 'REML'."
+    )

meta_analyze/exceptions.py

@@ -0,0 +1,21 @@
+"""Domain-specific exceptions raised by :mod:`meta_analyze`."""
+
+
+class MetaAnalysisError(Exception):
+    """Base class for all library-specific errors."""
+
+
+class InvalidStudyDataError(MetaAnalysisError, ValueError):
+    """Raised when study data cannot be interpreted safely."""
+
+
+class InsufficientStudiesError(MetaAnalysisError, ValueError):
+    """Raised when a requested method needs more included studies."""
+
+
+class ConvergenceError(MetaAnalysisError, RuntimeError):
+    """Raised when an iterative estimator fails to converge."""
+
+
+class UnsupportedMethodError(MetaAnalysisError, ValueError):
+    """Raised when a model or estimator name is unsupported."""

meta_analyze/heterogeneity.py

@@ -0,0 +1,99 @@
+"""Heterogeneity statistics for univariate meta-analysis."""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import NDArray
+from scipy.stats import chi2
+
+
+def weighted_mean(effect: NDArray[np.float64], weights: NDArray[np.float64]) -> float:
+    """Return a weighted mean without overflowing the raw weight sum."""
+
+    largest = float(np.max(weights))
+    if not np.isfinite(largest) or largest <= 0.0:
+        raise ValueError("Weights must contain a finite, strictly positive value.")
+    scaled = weights / largest
+    scaled_sum = float(np.sum(scaled))
+    if not np.isfinite(scaled_sum) or scaled_sum <= 0.0:
+        raise ValueError("Weights must have a finite, strictly positive sum.")
+    if bool(np.all(effect == effect[0])):
+        return float(effect[0])
+    return float(np.dot(scaled, effect) / scaled_sum)
+
+
+def generalized_q(
+    effect: NDArray[np.float64], variance: NDArray[np.float64], tau2: float
+) -> float:
+    """Return the weighted residual Q statistic at a given tau-squared."""
+
+    weights = 1.0 / (variance + tau2)
+    estimate = weighted_mean(effect, weights)
+    residual = effect - estimate
+    return float(np.dot(weights, residual * residual))
+
+
+def classical_heterogeneity(
+    effect: NDArray[np.float64], variance: NDArray[np.float64]
+) -> tuple[float, int, float, float, float]:
+    """Return Q, degrees of freedom, p-value, I-squared, and H-squared."""
+
+    k = len(effect)
+    if k == 1:
+        return 0.0, 0, float("nan"), float("nan"), float("nan")
+
+    weights = 1.0 / variance
+    estimate = weighted_mean(effect, weights)
+    return heterogeneity_at_estimate(effect, variance, estimate)
+
+
+def heterogeneity_at_estimate(
+    effect: NDArray[np.float64],
+    variance: NDArray[np.float64],
+    estimate: float,
+) -> tuple[float, int, float, float, float]:
+    """Return heterogeneity statistics around an explicitly pooled estimate."""
+
+    k = len(effect)
+    if k == 1:
+        return 0.0, 0, float("nan"), float("nan"), float("nan")
+
+    weights = 1.0 / variance
+    residual = effect - estimate
+    q = float(np.dot(weights, residual * residual))
+    df = k - 1
+    pvalue = float(chi2.sf(q, df))
+    i2 = 0.0 if q <= 0.0 else max(0.0, (q - df) / q)
+    h2 = q / df
+    return q, df, pvalue, i2, h2
+
+
+def tau2_inconsistency(
+    variance: NDArray[np.float64], tau2: float
+) -> tuple[float, float]:
+    """Return tau-squared-based I-squared and H-squared.
+
+    The typical within-study variance is ``(k - 1) / C``, where ``C`` is
+    calculated from common-effect inverse-variance weights.  Scaled weights
+    keep the calculation stable when sampling variances are very small.
+    """
+
+    k = len(variance)
+    if k == 1:
+        return float("nan"), float("nan")
+    if tau2 == 0.0:
+        return 0.0, 1.0
+
+    variance_scale = float(np.min(variance))
+    relative_weights = variance_scale / variance
+    weight_sum = float(np.sum(relative_weights))
+    c_scaled = (
+        weight_sum - float(np.dot(relative_weights, relative_weights)) / weight_sum
+    )
+    if not np.isfinite(c_scaled) or c_scaled <= 0.0:
+        return float("nan"), float("nan")
+
+    typical_variance = (k - 1) * variance_scale / c_scaled
+    i2 = 1.0 / (1.0 + typical_variance / tau2)
+    h2 = 1.0 + tau2 / typical_variance
+    return float(i2), float(h2)

meta_analyze/plotting/__init__.py

@@ -0,0 +1,7 @@
+"""Optional plotting helpers for fitted meta-analysis results."""
+
+from .forest import forest_plot
+from .funnel import funnel_plot
+from .subgroup_forest import subgroup_forest_plot
+
+__all__ = ["forest_plot", "funnel_plot", "subgroup_forest_plot"]

meta_analyze/plotting/_utils.py

@@ -0,0 +1,67 @@
+"""Shared display-scale helpers for optional plotting backends."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+from numpy.typing import NDArray
+
+if TYPE_CHECKING:
+    from matplotlib.axes import Axes
+
+    from ..results import MetaAnalysisResult
+else:
+    Axes = Any
+
+
+def to_display_scale(
+    values: NDArray[np.float64], *, display_scale: str
+) -> NDArray[np.float64]:
+    """Transform model-scale values to a result's display scale."""
+
+    if display_scale == "identity":
+        displayed = values.copy()
+    elif display_scale == "exp":
+        with np.errstate(over="ignore"):
+            displayed = np.exp(values)
+    else:
+        raise ValueError(f"Unknown display scale {display_scale!r}.")
+    if not np.all(np.isfinite(displayed)):
+        raise ValueError(
+            "Plot values are non-finite after display-scale transformation."
+        )
+    return displayed
+
+
+def default_effect_label(result: MetaAnalysisResult) -> str:
+    """Return a readable x-axis label for a fitted measure."""
+
+    labels = {
+        "OR": "Odds ratio",
+        "RR": "Risk ratio",
+        "RD": "Risk difference",
+        "MD": "Mean difference",
+        "SMD": "Standardized mean difference",
+        "GENERIC": "Effect",
+    }
+    return labels.get(result.measure, result.measure)
+
+
+def configure_log_axis(ax: Axes) -> None:
+    """Use readable ratio ticks on a logarithmic x-axis."""
+
+    from matplotlib.ticker import FuncFormatter, LogLocator, NullFormatter
+
+    ax.xaxis.set_major_locator(LogLocator(base=10.0, subs=(1.0, 2.0, 5.0)))
+    ax.xaxis.set_major_formatter(FuncFormatter(lambda value, _: f"{value:g}"))
+    ax.xaxis.set_minor_formatter(NullFormatter())
+
+
+def marker_areas(weights: NDArray[np.float64]) -> NDArray[np.float64]:
+    """Scale positive relative weights to readable forest-plot marker areas."""
+
+    largest = float(np.max(weights))
+    if not np.isfinite(largest) or largest <= 0.0:
+        raise ValueError("Forest plot weights must be finite and strictly positive.")
+    return 24.0 + 176.0 * weights / largest