PyMetaAnalysis 0.1.0__py3-none-any.whl

meta_analyze/plotting/forest.py

@@ -0,0 +1,193 @@
+"""Matplotlib forest plots built from stable result objects."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+from scipy.stats import norm
+
+from ..results import MetaAnalysisResult
+from ._utils import (
+    configure_log_axis,
+    default_effect_label,
+    marker_areas,
+    to_display_scale,
+)
+
+if TYPE_CHECKING:
+    from matplotlib.axes import Axes
+else:
+    Axes = Any
+
+
+def _default_pooled_label(result: MetaAnalysisResult) -> str:
+    return "Common effect" if result.model == "common" else "Random effects"
+
+
+def forest_plot(
+    result: MetaAnalysisResult,
+    *,
+    ax: Axes | None = None,
+    effect_label: str | None = None,
+    pooled_label: str | None = None,
+    show_prediction_interval: bool = True,
+    show_weights: bool = True,
+    null_value: float | None = None,
+    log_scale: bool | None = None,
+) -> Axes:
+    """Draw a forest plot and return its Matplotlib ``Axes``.
+
+    Only included studies are plotted. Study confidence intervals use the
+    result confidence level and normal critical value. Ratio measures are
+    displayed on their exponentiated scale with a logarithmic axis by default.
+    The function never calls ``show()``.
+    """
+
+    try:
+        import matplotlib.pyplot as plt
+        from matplotlib.patches import Polygon
+    except ImportError as error:  # pragma: no cover - tested without plot extra
+        raise ImportError(
+            "Forest plots require Matplotlib; install PyMetaAnalysis[plot]."
+        ) from error
+
+    studies = result.study_results
+    included = studies.loc[studies["included"]].reset_index(drop=True)
+    if included.empty:
+        raise ValueError("Forest plot requires at least one included study.")
+
+    effect = included["effect"].to_numpy(dtype=np.float64, copy=True)
+    variance = included["variance"].to_numpy(dtype=np.float64, copy=True)
+    weights = included["normalized_weight"].to_numpy(dtype=np.float64, copy=True)
+    critical_value = float(norm.ppf(0.5 + result.method.confidence_level / 2.0))
+    margin = critical_value * np.sqrt(variance)
+    study_low = to_display_scale(effect - margin, display_scale=result.display_scale)
+    study_estimate = to_display_scale(effect, display_scale=result.display_scale)
+    study_high = to_display_scale(effect + margin, display_scale=result.display_scale)
+    pooled_low, pooled_estimate, pooled_high = to_display_scale(
+        np.asarray([result.ci_low, result.estimate, result.ci_high]),
+        display_scale=result.display_scale,
+    )
+
+    use_log_scale = result.display_scale == "exp" if log_scale is None else log_scale
+    resolved_null = (
+        (1.0 if result.display_scale == "exp" else 0.0)
+        if null_value is None
+        else float(null_value)
+    )
+    if not np.isfinite(resolved_null) or (use_log_scale and resolved_null <= 0.0):
+        raise ValueError(
+            "null_value must be finite and strictly positive on a logarithmic axis."
+        )
+
+    created_axes = ax is None
+    if ax is None:
+        height = max(4.0, 0.5 * (len(included) + 3))
+        _, ax = plt.subplots(figsize=(8.0, height))
+    if use_log_scale:
+        ax.set_xscale("log")
+        configure_log_axis(ax)
+
+    y_studies = np.arange(len(included), 0, -1, dtype=np.float64)
+    pooled_y = 0.0
+    ax.axvline(
+        resolved_null,
+        color="#777777",
+        linestyle="--",
+        linewidth=1.0,
+        zorder=0,
+    )
+    ax.hlines(
+        y_studies,
+        study_low,
+        study_high,
+        colors="#4c4c4c",
+        linewidth=1.2,
+        zorder=1,
+    )
+    ax.scatter(
+        study_estimate,
+        y_studies,
+        s=marker_areas(weights),
+        marker="s",
+        color="#2f6f9f",
+        edgecolors="white",
+        linewidths=0.6,
+        zorder=2,
+    )
+
+    if show_prediction_interval and result.prediction_interval is not None:
+        prediction_low, prediction_high = to_display_scale(
+            np.asarray(result.prediction_interval, dtype=np.float64),
+            display_scale=result.display_scale,
+        )
+        ax.hlines(
+            pooled_y,
+            prediction_low,
+            prediction_high,
+            colors="#d97706",
+            linewidth=2.0,
+            zorder=1,
+        )
+        ax.vlines(
+            [prediction_low, prediction_high],
+            pooled_y - 0.12,
+            pooled_y + 0.12,
+            colors="#d97706",
+            linewidth=1.5,
+            zorder=1,
+        )
+
+    diamond = Polygon(
+        [
+            (pooled_low, pooled_y),
+            (pooled_estimate, pooled_y + 0.25),
+            (pooled_high, pooled_y),
+            (pooled_estimate, pooled_y - 0.25),
+        ],
+        closed=True,
+        facecolor="#1f4e79",
+        edgecolor="#1f4e79",
+        zorder=3,
+    )
+    ax.add_patch(diamond)
+
+    labels = [str(label) for label in included["study"]]
+    labels.append(pooled_label or _default_pooled_label(result))
+    ax.set_yticks(np.concatenate([y_studies, [pooled_y]]), labels=labels)
+    ax.set_ylim(-0.65, len(included) + 0.75)
+    ax.set_xlabel(effect_label or default_effect_label(result))
+    ax.tick_params(axis="y", length=0)
+    ax.grid(axis="x", color="#dddddd", linewidth=0.7, alpha=0.8)
+    ax.set_axisbelow(True)
+    for side in ("top", "right", "left"):
+        ax.spines[side].set_visible(False)
+    ax.margins(x=0.08)
+
+    if show_weights:
+        transform = ax.get_yaxis_transform()
+        header_y = len(included) + 0.55
+        ax.text(
+            1.02,
+            header_y,
+            "Weight",
+            transform=transform,
+            ha="left",
+            va="center",
+            fontweight="bold",
+            clip_on=False,
+        )
+        for y_value, weight in zip(y_studies, weights, strict=True):
+            ax.text(
+                1.02,
+                y_value,
+                f"{100.0 * weight:.1f}%",
+                transform=transform,
+                ha="left",
+                va="center",
+                clip_on=False,
+            )
+    if created_axes:
+        ax.figure.subplots_adjust(left=0.25, right=0.82, bottom=0.14)
+    return ax

meta_analyze/plotting/funnel.py

@@ -0,0 +1,168 @@
+"""Matplotlib funnel plots built from stable result objects."""
+
+from __future__ import annotations
+
+import warnings
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+from scipy.stats import norm
+
+from ..results import MetaAnalysisResult
+from ._utils import configure_log_axis, default_effect_label, to_display_scale
+
+if TYPE_CHECKING:
+    from matplotlib.axes import Axes
+else:
+    Axes = Any
+
+
+def _validate_confidence_level(
+    confidence_level: float | None, *, fallback: float
+) -> float:
+    resolved = fallback if confidence_level is None else confidence_level
+    if isinstance(resolved, bool) or not isinstance(resolved, (int, float)):
+        raise ValueError("confidence_level must be a number between 0 and 1.")
+    numeric = float(resolved)
+    if not np.isfinite(numeric) or not 0.0 < numeric < 1.0:
+        raise ValueError("confidence_level must be between 0 and 1.")
+    return numeric
+
+
+def funnel_plot(
+    result: MetaAnalysisResult,
+    *,
+    ax: Axes | None = None,
+    effect_label: str | None = None,
+    confidence_level: float | None = None,
+    show_pseudo_confidence_interval: bool = True,
+    warn_on_few_studies: bool = True,
+    log_scale: bool | None = None,
+) -> Axes:
+    """Draw a standard-error funnel plot and return its Matplotlib ``Axes``.
+
+    Pseudo confidence limits are calculated on the model scale around the
+    fitted pooled estimate and do not incorporate tau-squared. Ratio measures
+    are exponentiated and drawn on a logarithmic x-axis by default. The
+    function never calls ``show()``.
+    """
+
+    try:
+        import matplotlib.pyplot as plt
+    except ImportError as error:  # pragma: no cover - tested without plot extra
+        raise ImportError(
+            "Funnel plots require Matplotlib; install PyMetaAnalysis[plot]."
+        ) from error
+
+    studies = result.study_results
+    included = studies.loc[studies["included"]].reset_index(drop=True)
+    if included.empty:
+        raise ValueError("Funnel plot requires at least one included study.")
+    if warn_on_few_studies and len(included) < 10:
+        warnings.warn(
+            "Funnel plots are difficult to interpret with fewer than 10 studies; "
+            "asymmetry indicates possible small-study effects, not necessarily "
+            "publication bias.",
+            UserWarning,
+            stacklevel=2,
+        )
+
+    level = _validate_confidence_level(
+        confidence_level, fallback=result.method.confidence_level
+    )
+    effect = included["effect"].to_numpy(dtype=np.float64, copy=True)
+    standard_error = np.sqrt(included["variance"].to_numpy(dtype=np.float64, copy=True))
+    displayed_effect = to_display_scale(effect, display_scale=result.display_scale)
+    displayed_reference = float(
+        to_display_scale(
+            np.asarray([result.estimate], dtype=np.float64),
+            display_scale=result.display_scale,
+        )[0]
+    )
+
+    use_log_scale = result.display_scale == "exp" if log_scale is None else log_scale
+    if use_log_scale and (
+        np.any(displayed_effect <= 0.0) or displayed_reference <= 0.0
+    ):
+        raise ValueError(
+            "Funnel plot effects and pooled estimate must be strictly positive "
+            "on a logarithmic axis."
+        )
+    created_axes = ax is None
+    if ax is None:
+        _, ax = plt.subplots(figsize=(6.5, 6.0))
+    if use_log_scale:
+        ax.set_xscale("log")
+        configure_log_axis(ax)
+
+    maximum_se = float(np.max(standard_error))
+    plot_maximum_se = maximum_se * 1.08
+    if show_pseudo_confidence_interval:
+        critical_value = float(norm.ppf(0.5 + level / 2.0))
+        standard_error_grid = np.linspace(0.0, plot_maximum_se, 200)
+        lower = to_display_scale(
+            result.estimate - critical_value * standard_error_grid,
+            display_scale=result.display_scale,
+        )
+        upper = to_display_scale(
+            result.estimate + critical_value * standard_error_grid,
+            display_scale=result.display_scale,
+        )
+        if use_log_scale and (np.any(lower <= 0.0) or np.any(upper <= 0.0)):
+            raise ValueError(
+                "Funnel plot confidence limits must be strictly positive on a "
+                "logarithmic axis."
+            )
+        ax.fill_betweenx(
+            standard_error_grid,
+            lower,
+            upper,
+            color="#dbeafe",
+            alpha=0.6,
+            zorder=0,
+        )
+        ax.plot(
+            lower,
+            standard_error_grid,
+            color="#6b7280",
+            linestyle="--",
+            linewidth=1.0,
+            zorder=1,
+        )
+        ax.plot(
+            upper,
+            standard_error_grid,
+            color="#6b7280",
+            linestyle="--",
+            linewidth=1.0,
+            zorder=1,
+        )
+
+    ax.axvline(
+        displayed_reference,
+        color="#4b5563",
+        linestyle="-",
+        linewidth=1.2,
+        zorder=1,
+    )
+    ax.scatter(
+        displayed_effect,
+        standard_error,
+        s=42.0,
+        marker="o",
+        color="#2f6f9f",
+        edgecolors="white",
+        linewidths=0.6,
+        zorder=2,
+    )
+    ax.set_ylim(plot_maximum_se, 0.0)
+    ax.set_xlabel(effect_label or default_effect_label(result))
+    ax.set_ylabel("Standard error")
+    ax.grid(axis="y", color="#e5e7eb", linewidth=0.7, alpha=0.8)
+    ax.set_axisbelow(True)
+    for side in ("top", "right"):
+        ax.spines[side].set_visible(False)
+    ax.margins(x=0.08)
+    if created_axes:
+        ax.figure.subplots_adjust(left=0.14, right=0.96, bottom=0.13, top=0.96)
+    return ax

meta_analyze/plotting/subgroup_forest.py

@@ -0,0 +1,284 @@
+"""Forest plots for independent study subgroup analyses."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+from numpy.typing import NDArray
+from scipy.stats import norm
+
+from ..results import MetaAnalysisResult, SubgroupMetaAnalysisResult
+from ._utils import (
+    configure_log_axis,
+    default_effect_label,
+    marker_areas,
+    to_display_scale,
+)
+
+if TYPE_CHECKING:
+    from matplotlib.axes import Axes
+else:
+    Axes = Any
+
+
+def _draw_interval(
+    ax: Axes,
+    result: MetaAnalysisResult,
+    *,
+    y: float,
+    display_scale: str,
+) -> None:
+    if result.prediction_interval is None:
+        return
+    low, high = to_display_scale(
+        np.asarray(result.prediction_interval, dtype=np.float64),
+        display_scale=display_scale,
+    )
+    ax.hlines(y, low, high, colors="#d97706", linewidth=2.0, zorder=1)
+    ax.vlines(
+        [low, high],
+        y - 0.11,
+        y + 0.11,
+        colors="#d97706",
+        linewidth=1.4,
+        zorder=1,
+    )
+
+
+def _draw_diamond(
+    ax: Axes,
+    result: MetaAnalysisResult,
+    *,
+    y: float,
+    color: str,
+    display_scale: str,
+) -> None:
+    from matplotlib.patches import Polygon
+
+    low, estimate, high = to_display_scale(
+        np.asarray([result.ci_low, result.estimate, result.ci_high]),
+        display_scale=display_scale,
+    )
+    ax.add_patch(
+        Polygon(
+            [
+                (low, y),
+                (estimate, y + 0.23),
+                (high, y),
+                (estimate, y - 0.23),
+            ],
+            closed=True,
+            facecolor=color,
+            edgecolor=color,
+            zorder=3,
+        )
+    )
+
+
+def _study_coordinates(
+    result: MetaAnalysisResult,
+) -> tuple[NDArray[np.float64], NDArray[np.float64], NDArray[np.float64]]:
+    studies = result.study_results
+    included = studies.loc[studies["included"]]
+    effect = included["effect"].to_numpy(dtype=np.float64, copy=True)
+    variance = included["variance"].to_numpy(dtype=np.float64, copy=True)
+    critical_value = float(norm.ppf(0.5 + result.method.confidence_level / 2.0))
+    margin = critical_value * np.sqrt(variance)
+    return (
+        to_display_scale(effect - margin, display_scale=result.display_scale),
+        to_display_scale(effect, display_scale=result.display_scale),
+        to_display_scale(effect + margin, display_scale=result.display_scale),
+    )
+
+
+def subgroup_forest_plot(
+    result: SubgroupMetaAnalysisResult,
+    *,
+    ax: Axes | None = None,
+    effect_label: str | None = None,
+    show_prediction_interval: bool = True,
+    show_weights: bool = True,
+    null_value: float | None = None,
+    log_scale: bool | None = None,
+) -> Axes:
+    """Draw studies, subgroup summaries, and the overall pooled result."""
+
+    try:
+        import matplotlib.pyplot as plt
+    except ImportError as error:  # pragma: no cover - tested without plot extra
+        raise ImportError(
+            "Subgroup forest plots require Matplotlib; install PyMetaAnalysis[plot]."
+        ) from error
+
+    overall = result.overall
+    use_log_scale = overall.display_scale == "exp" if log_scale is None else log_scale
+    resolved_null = (
+        (1.0 if overall.display_scale == "exp" else 0.0)
+        if null_value is None
+        else float(null_value)
+    )
+    if not np.isfinite(resolved_null) or (use_log_scale and resolved_null <= 0.0):
+        raise ValueError(
+            "null_value must be finite and strictly positive on a logarithmic axis."
+        )
+
+    included_count = sum(group.k for group in result.groups.values())
+    row_units = included_count + 2 * len(result.groups) + 1
+    created_axes = ax is None
+    if ax is None:
+        height = max(5.0, 0.42 * row_units + 1.5)
+        _, ax = plt.subplots(figsize=(9.0, height))
+    if use_log_scale:
+        ax.set_xscale("log")
+        configure_log_axis(ax)
+
+    overall_studies = overall.study_results.set_index("row_id")
+    cursor = float(row_units - 1)
+    tick_positions: list[float] = []
+    tick_labels: list[str] = []
+    tick_kinds: list[str] = []
+    study_weight_rows: list[tuple[float, float]] = []
+
+    ax.axvline(
+        resolved_null,
+        color="#777777",
+        linestyle="--",
+        linewidth=1.0,
+        zorder=0,
+    )
+
+    for label, group in result.groups.items():
+        header_y = cursor
+        tick_positions.append(header_y)
+        tick_labels.append(str(label))
+        tick_kinds.append("header")
+        cursor -= 1.0
+
+        studies = group.study_results
+        included = studies.loc[studies["included"]].reset_index(drop=True)
+        low, estimate, high = _study_coordinates(group)
+        y_studies = np.arange(
+            cursor,
+            cursor - len(included),
+            -1.0,
+            dtype=np.float64,
+        )
+        row_ids = included["row_id"].to_numpy(dtype=np.int64, copy=True)
+        weights = overall_studies.loc[row_ids, "normalized_weight"].to_numpy(
+            dtype=np.float64, copy=True
+        )
+        ax.hlines(
+            y_studies,
+            low,
+            high,
+            colors="#4c4c4c",
+            linewidth=1.2,
+            zorder=1,
+        )
+        ax.scatter(
+            estimate,
+            y_studies,
+            s=marker_areas(weights),
+            marker="s",
+            color="#2f6f9f",
+            edgecolors="white",
+            linewidths=0.6,
+            zorder=2,
+        )
+        for y_value, study, weight in zip(
+            y_studies,
+            included["study"],
+            weights,
+            strict=True,
+        ):
+            tick_positions.append(float(y_value))
+            tick_labels.append(f"  {study}")
+            tick_kinds.append("study")
+            study_weight_rows.append((float(y_value), float(weight)))
+        cursor -= float(len(included))
+
+        pooled_y = cursor
+        if show_prediction_interval:
+            _draw_interval(
+                ax,
+                group,
+                y=pooled_y,
+                display_scale=overall.display_scale,
+            )
+        _draw_diamond(
+            ax,
+            group,
+            y=pooled_y,
+            color="#4f7f5f",
+            display_scale=overall.display_scale,
+        )
+        tick_positions.append(pooled_y)
+        tick_labels.append(f"  {label} subtotal")
+        tick_kinds.append("subtotal")
+        cursor -= 1.0
+
+    overall_y = cursor
+    if show_prediction_interval:
+        _draw_interval(
+            ax,
+            overall,
+            y=overall_y,
+            display_scale=overall.display_scale,
+        )
+    _draw_diamond(
+        ax,
+        overall,
+        y=overall_y,
+        color="#1f4e79",
+        display_scale=overall.display_scale,
+    )
+    tick_positions.append(overall_y)
+    tick_labels.append("Overall")
+    tick_kinds.append("overall")
+
+    ax.set_yticks(tick_positions, labels=tick_labels)
+    for tick, kind in zip(ax.get_yticklabels(), tick_kinds, strict=True):
+        if kind in {"header", "subtotal", "overall"}:
+            tick.set_fontweight("bold")
+    ax.set_ylim(overall_y - 0.75, row_units - 0.25)
+    ax.set_xlabel(effect_label or default_effect_label(overall))
+    ax.tick_params(axis="y", length=0)
+    ax.grid(axis="x", color="#dddddd", linewidth=0.7, alpha=0.8)
+    ax.set_axisbelow(True)
+    for side in ("top", "right", "left"):
+        ax.spines[side].set_visible(False)
+    ax.margins(x=0.08)
+
+    if show_weights:
+        transform = ax.get_yaxis_transform()
+        ax.text(
+            1.02,
+            row_units - 0.5,
+            "Weight",
+            transform=transform,
+            ha="left",
+            va="center",
+            fontweight="bold",
+            clip_on=False,
+        )
+        for weight_y, weight in study_weight_rows:
+            ax.text(
+                1.02,
+                weight_y,
+                f"{100.0 * weight:.1f}%",
+                transform=transform,
+                ha="left",
+                va="center",
+                clip_on=False,
+            )
+
+    test_text = (
+        "Test for subgroup differences: "
+        f"Q({result.q_between_df})={result.q_between:.3g}, "
+        f"p={result.q_between_pvalue:.3g}"
+    )
+    ax.text(0.0, -0.09, test_text, transform=ax.transAxes, ha="left", va="top")
+    if created_axes:
+        ax.figure.subplots_adjust(left=0.29, right=0.82, bottom=0.17)
+    return ax