PyMetaAnalysis 0.1.0__py3-none-any.whl

meta_analyze/continuous_api.py

@@ -0,0 +1,353 @@
+"""High-level API for two-group continuous outcome meta-analysis."""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from typing import overload
+
+import numpy as np
+import pandas as pd
+
+from .api import _normalize_ci_method, _normalize_model, _validate_analysis_controls
+from .config import MethodConfig, MethodOptionValue
+from .data import ColumnOrArray, MissingPolicy
+from .effect_sizes.continuous import (
+    calculate_continuous_effects,
+    normalize_continuous_studies,
+)
+from .estimators import fit_inverse_variance
+from .heterogeneity import classical_heterogeneity, tau2_inconsistency
+from .provenance import (
+    TransformationRecord,
+    add_input_field,
+    build_analysis_provenance,
+)
+from .results import (
+    FitDiagnostics,
+    HeterogeneityResult,
+    MetaAnalysisResult,
+    SubgroupMetaAnalysisResult,
+)
+from .subgroups import fit_subgroup_analysis
+
+
+def _fit_meta_continuous_single(
+    data: pd.DataFrame | None = None,
+    *,
+    mean_treat: ColumnOrArray,
+    sd_treat: ColumnOrArray,
+    n_treat: ColumnOrArray,
+    mean_control: ColumnOrArray,
+    sd_control: ColumnOrArray,
+    n_control: ColumnOrArray,
+    study: ColumnOrArray | None = None,
+    measure: str = "MD",
+    model: str = "random",
+    tau2_method: str = "REML",
+    ci_method: str = "normal",
+    confidence_level: float = 0.95,
+    smd_variance: str = "LS",
+    missing: MissingPolicy = "raise",
+    atol: float = 1e-10,
+    max_iter: int = 1000,
+) -> MetaAnalysisResult:
+    """Pool mean differences or Hedges' g from two independent groups.
+
+    ``measure="MD"`` uses the unpooled sampling variance
+    ``sd_treat**2 / n_treat + sd_control**2 / n_control``. ``measure="SMD"``
+    uses a pooled SD, the exact Hedges correction, and the ``LS`` sampling
+    variance convention used by ``metafor::escalc(measure="SMD")``.
+    """
+
+    confidence_level, atol, max_iter = _validate_analysis_controls(
+        confidence_level=confidence_level,
+        atol=atol,
+        max_iter=max_iter,
+    )
+    normalized_model = _normalize_model(model)
+    normalized_ci = _normalize_ci_method(ci_method)
+    normalized_tau2 = tau2_method.upper().replace("-", "_")
+
+    studies = normalize_continuous_studies(
+        data=data,
+        mean_treat=mean_treat,
+        sd_treat=sd_treat,
+        n_treat=n_treat,
+        mean_control=mean_control,
+        sd_control=sd_control,
+        n_control=n_control,
+        study=study,
+        missing=missing,
+    )
+    effects = calculate_continuous_effects(
+        studies,
+        measure=measure,
+        smd_variance=smd_variance,
+    )
+    included = studies.included
+    included_effect = effects.included_effect
+    included_variance = effects.included_variance
+
+    fit = fit_inverse_variance(
+        included_effect,
+        included_variance,
+        model=normalized_model,
+        tau2_method=normalized_tau2,
+        ci_method=normalized_ci,
+        confidence_level=confidence_level,
+        atol=atol,
+        max_iter=max_iter,
+    )
+    q, q_df, q_pvalue, i2, h2 = classical_heterogeneity(
+        included_effect, included_variance
+    )
+    tau2_value = 0.0 if fit.tau2 is None else fit.tau2.value
+    i2_method = "q_based"
+    if normalized_model == "random":
+        i2, h2 = tau2_inconsistency(included_variance, tau2_value)
+        i2_method = "tau2_typical_variance"
+    heterogeneity = HeterogeneityResult(q, q_df, q_pvalue, i2, h2, i2_method)
+
+    row_count = len(included)
+    raw_weights = np.full(row_count, np.nan, dtype=np.float64)
+    normalized_weights = np.full(row_count, np.nan, dtype=np.float64)
+    raw_weights[included] = fit.weights
+    normalized_weights[included] = fit.normalized_weights
+    study_results = pd.DataFrame(
+        {
+            "row_id": studies.row_id,
+            "study": studies.study,
+            "mean_treat": studies.mean_treat,
+            "sd_treat": studies.sd_treat,
+            "n_treat": studies.n_treat,
+            "mean_control": studies.mean_control,
+            "sd_control": studies.sd_control,
+            "n_control": studies.n_control,
+            "effect": effects.effect,
+            "effect_display": effects.effect,
+            "variance": effects.variance,
+            "standard_error": np.sqrt(effects.variance),
+            "pooled_sd": effects.pooled_sd,
+            "cohen_d": effects.cohen_d,
+            "smd_correction_factor": effects.correction_factor,
+            "included": included,
+            "exclusion_reason": pd.Series(
+                studies.exclusion_reason, dtype=object, copy=True
+            ),
+            "weight": raw_weights,
+            "normalized_weight": normalized_weights,
+        }
+    )
+
+    warnings = list(fit.warnings)
+    excluded_count = int(np.count_nonzero(~included))
+    if excluded_count:
+        warnings.append(
+            f"Excluded {excluded_count} study row(s) under missing={missing!r}."
+        )
+
+    options: tuple[tuple[str, MethodOptionValue], ...]
+    if effects.measure == "SMD":
+        options = (
+            ("effect_estimator", "hedges_g_exact"),
+            ("standardizer", "pooled_sd"),
+            ("smd_variance", "LS"),
+        )
+    else:
+        options = (("sampling_variance", "unpooled"),)
+    method = MethodConfig(
+        model=normalized_model,
+        pooling_method="inverse_variance",
+        tau2_method=None if normalized_model == "common" else normalized_tau2,
+        ci_method=normalized_ci,
+        confidence_level=confidence_level,
+        prediction_interval_method="HTS" if normalized_model == "random" else None,
+        missing=missing,
+        atol=atol,
+        max_iter=max_iter,
+        options=options,
+    )
+    diagnostics = FitDiagnostics(
+        converged=True if fit.tau2 is None else fit.tau2.converged,
+        iterations=0 if fit.tau2 is None else fit.tau2.iterations,
+        tau2_at_boundary=None if fit.tau2 is None else fit.tau2.boundary,
+    )
+    provenance = build_analysis_provenance(
+        analysis_type="continuous",
+        data=data,
+        inputs=(
+            ("mean_treat", mean_treat),
+            ("sd_treat", sd_treat),
+            ("n_treat", n_treat),
+            ("mean_control", mean_control),
+            ("sd_control", sd_control),
+            ("n_control", n_control),
+        ),
+        study=study,
+        included=included,
+        transformations=(
+            TransformationRecord(
+                name="continuous_effect_size",
+                parameters=(("measure", effects.measure), *options),
+                affected_rows=tuple(int(row) for row in np.flatnonzero(included)),
+            ),
+        ),
+    )
+    return MetaAnalysisResult(
+        estimate=fit.estimate,
+        standard_error=fit.standard_error,
+        ci_low=fit.ci_low,
+        ci_high=fit.ci_high,
+        prediction_interval=fit.prediction_interval,
+        tau2=tau2_value,
+        heterogeneity=heterogeneity,
+        k=len(included_effect),
+        model=normalized_model,
+        measure=effects.measure,
+        effect_scale=effects.effect_scale,
+        display_scale=effects.display_scale,
+        method=method,
+        diagnostics=diagnostics,
+        provenance=provenance,
+        warnings=tuple(warnings),
+        _study_results=study_results,
+        _source_data=data,
+    )
+
+
+@overload
+def meta_continuous(
+    data: pd.DataFrame | None = None,
+    *,
+    mean_treat: ColumnOrArray,
+    sd_treat: ColumnOrArray,
+    n_treat: ColumnOrArray,
+    mean_control: ColumnOrArray,
+    sd_control: ColumnOrArray,
+    n_control: ColumnOrArray,
+    study: ColumnOrArray | None = None,
+    subgroup: None = None,
+    measure: str = "MD",
+    model: str = "random",
+    tau2_method: str = "REML",
+    ci_method: str = "normal",
+    confidence_level: float = 0.95,
+    smd_variance: str = "LS",
+    missing: MissingPolicy = "raise",
+    atol: float = 1e-10,
+    max_iter: int = 1000,
+) -> MetaAnalysisResult: ...
+
+
+@overload
+def meta_continuous(
+    data: pd.DataFrame | None = None,
+    *,
+    mean_treat: ColumnOrArray,
+    sd_treat: ColumnOrArray,
+    n_treat: ColumnOrArray,
+    mean_control: ColumnOrArray,
+    sd_control: ColumnOrArray,
+    n_control: ColumnOrArray,
+    study: ColumnOrArray | None = None,
+    subgroup: ColumnOrArray,
+    measure: str = "MD",
+    model: str = "random",
+    tau2_method: str = "REML",
+    ci_method: str = "normal",
+    confidence_level: float = 0.95,
+    smd_variance: str = "LS",
+    missing: MissingPolicy = "raise",
+    atol: float = 1e-10,
+    max_iter: int = 1000,
+) -> SubgroupMetaAnalysisResult: ...
+
+
+def meta_continuous(
+    data: pd.DataFrame | None = None,
+    *,
+    mean_treat: ColumnOrArray,
+    sd_treat: ColumnOrArray,
+    n_treat: ColumnOrArray,
+    mean_control: ColumnOrArray,
+    sd_control: ColumnOrArray,
+    n_control: ColumnOrArray,
+    study: ColumnOrArray | None = None,
+    subgroup: ColumnOrArray | None = None,
+    measure: str = "MD",
+    model: str = "random",
+    tau2_method: str = "REML",
+    ci_method: str = "normal",
+    confidence_level: float = 0.95,
+    smd_variance: str = "LS",
+    missing: MissingPolicy = "raise",
+    atol: float = 1e-10,
+    max_iter: int = 1000,
+) -> MetaAnalysisResult | SubgroupMetaAnalysisResult:
+    """Pool two-group continuous outcomes, optionally by subgroup.
+
+    Group means, sample standard deviations, and sample sizes accept DataFrame
+    column names or one-dimensional array-like values. The default is a REML
+    random-effects mean difference. ``measure="SMD"`` calculates exact-
+    corrected Hedges' g with the LS sampling-variance convention.
+    """
+
+    overall = _fit_meta_continuous_single(
+        data,
+        mean_treat=mean_treat,
+        sd_treat=sd_treat,
+        n_treat=n_treat,
+        mean_control=mean_control,
+        sd_control=sd_control,
+        n_control=n_control,
+        study=study,
+        measure=measure,
+        model=model,
+        tau2_method=tau2_method,
+        ci_method=ci_method,
+        confidence_level=confidence_level,
+        smd_variance=smd_variance,
+        missing=missing,
+        atol=atol,
+        max_iter=max_iter,
+    )
+    if subgroup is None:
+        return overall
+
+    overall = replace(
+        overall,
+        provenance=add_input_field(
+            overall.provenance,
+            role="subgroup",
+            value=subgroup,
+            data=data,
+        ),
+    )
+
+    def fit_group(positions: np.ndarray) -> MetaAnalysisResult:
+        rows = overall.study_results.iloc[positions]
+        return _fit_meta_continuous_single(
+            mean_treat=rows["mean_treat"].to_numpy(dtype=np.float64, copy=True),
+            sd_treat=rows["sd_treat"].to_numpy(dtype=np.float64, copy=True),
+            n_treat=rows["n_treat"].to_numpy(dtype=np.float64, copy=True),
+            mean_control=rows["mean_control"].to_numpy(dtype=np.float64, copy=True),
+            sd_control=rows["sd_control"].to_numpy(dtype=np.float64, copy=True),
+            n_control=rows["n_control"].to_numpy(dtype=np.float64, copy=True),
+            study=rows["study"].to_numpy(dtype=object, copy=True),
+            measure=measure,
+            model=model,
+            tau2_method=tau2_method,
+            ci_method=ci_method,
+            confidence_level=confidence_level,
+            smd_variance=smd_variance,
+            missing=missing,
+            atol=atol,
+            max_iter=max_iter,
+        )
+
+    return fit_subgroup_analysis(
+        data=data,
+        subgroup=subgroup,
+        overall=overall,
+        fit_group=fit_group,
+    )

meta_analyze/data.py

@@ -0,0 +1,181 @@
+"""Input normalization at the pandas/NumPy boundary."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal, TypeAlias
+
+import numpy as np
+import pandas as pd
+from numpy.typing import ArrayLike, NDArray
+
+from .exceptions import InvalidStudyDataError
+
+ColumnOrArray: TypeAlias = str | ArrayLike
+MissingPolicy: TypeAlias = Literal["raise", "drop"]
+
+
+@dataclass(frozen=True, slots=True)
+class NormalizedStudies:
+    """Validated study vectors plus row-level inclusion metadata."""
+
+    row_id: NDArray[np.int64]
+    study: NDArray[np.object_]
+    effect: NDArray[np.float64]
+    variance: NDArray[np.float64]
+    included: NDArray[np.bool_]
+    exclusion_reason: NDArray[np.object_]
+
+    @property
+    def included_effect(self) -> NDArray[np.float64]:
+        return self.effect[self.included]
+
+    @property
+    def included_variance(self) -> NDArray[np.float64]:
+        return self.variance[self.included]
+
+
+def _resolve_vector(
+    value: ColumnOrArray,
+    *,
+    data: pd.DataFrame | None,
+    name: str,
+) -> NDArray[Any]:
+    if isinstance(value, str):
+        if data is None:
+            raise InvalidStudyDataError(
+                f"{name}={value!r} is a column name, but no DataFrame was provided."
+            )
+        if value not in data.columns:
+            raise InvalidStudyDataError(
+                f"Column {value!r}, specified by {name}, is not present in data."
+            )
+        array = data[value].to_numpy(copy=True)
+    else:
+        if isinstance(value, (str, bytes)):
+            raise InvalidStudyDataError(
+                f"{name} must be a column name or 1D array-like."
+            )
+        array = np.asarray(value)
+
+    if array.ndim != 1:
+        raise InvalidStudyDataError(
+            f"{name} must be one-dimensional, got shape {array.shape}."
+        )
+    return array
+
+
+def _study_labels(
+    study: ColumnOrArray | None,
+    *,
+    data: pd.DataFrame | None,
+    length: int,
+) -> NDArray[np.object_]:
+    if study is None:
+        labels: NDArray[Any]
+        if data is not None:
+            labels = data.index.to_numpy(copy=True)
+        else:
+            labels = np.arange(length, dtype=np.int64)
+    else:
+        labels = _resolve_vector(study, data=data, name="study")
+
+    if len(labels) != length:
+        raise InvalidStudyDataError(
+            f"study has length {len(labels)}, but effect and variance have "
+            f"length {length}."
+        )
+    return np.asarray(labels, dtype=object)
+
+
+def normalize_studies(
+    *,
+    data: pd.DataFrame | None,
+    effect: ColumnOrArray,
+    variance: ColumnOrArray,
+    study: ColumnOrArray | None,
+    missing: MissingPolicy,
+) -> NormalizedStudies:
+    """Resolve column/array arguments and validate generic effect data."""
+
+    if data is not None and not isinstance(data, pd.DataFrame):
+        raise InvalidStudyDataError("data must be a pandas DataFrame or None.")
+    if missing not in {"raise", "drop"}:
+        raise InvalidStudyDataError("missing must be either 'raise' or 'drop'.")
+
+    raw_effect = _resolve_vector(effect, data=data, name="effect")
+    raw_variance = _resolve_vector(variance, data=data, name="variance")
+    if len(raw_effect) != len(raw_variance):
+        raise InvalidStudyDataError(
+            "effect and variance must have the same length; "
+            f"got {len(raw_effect)} and {len(raw_variance)}."
+        )
+    if data is not None and len(data) != len(raw_effect):
+        raise InvalidStudyDataError(
+            "Array-like inputs used with data must have exactly one value per "
+            "DataFrame row."
+        )
+
+    labels = _study_labels(study, data=data, length=len(raw_effect))
+
+    try:
+        effect_values = np.asarray(raw_effect, dtype=np.float64)
+        variance_values = np.asarray(raw_variance, dtype=np.float64)
+    except (TypeError, ValueError) as error:
+        raise InvalidStudyDataError(
+            "effect and variance must contain numeric values."
+        ) from error
+
+    effect_missing = pd.isna(effect_values)
+    variance_missing = pd.isna(variance_values)
+    any_missing = effect_missing | variance_missing
+    if np.any(any_missing) and missing == "raise":
+        rows = np.flatnonzero(any_missing).tolist()
+        raise InvalidStudyDataError(
+            f"Missing effect or variance values at row positions {rows}; "
+            "use missing='drop' to exclude them explicitly."
+        )
+
+    finite_effect = np.isfinite(effect_values) | effect_missing
+    finite_variance = np.isfinite(variance_values) | variance_missing
+    if not np.all(finite_effect):
+        rows = np.flatnonzero(~finite_effect).tolist()
+        raise InvalidStudyDataError(
+            f"Effect values must be finite; invalid rows: {rows}."
+        )
+    if not np.all(finite_variance):
+        rows = np.flatnonzero(~finite_variance).tolist()
+        raise InvalidStudyDataError(
+            f"Variance values must be finite; invalid rows: {rows}."
+        )
+
+    nonpositive_variance = (~variance_missing) & (variance_values <= 0.0)
+    if np.any(nonpositive_variance):
+        rows = np.flatnonzero(nonpositive_variance).tolist()
+        raise InvalidStudyDataError(
+            f"Sampling variances must be strictly positive; invalid rows: {rows}."
+        )
+
+    included = ~any_missing
+    reasons = np.full(len(effect_values), None, dtype=object)
+    for index in np.flatnonzero(any_missing):
+        if effect_missing[index] and variance_missing[index]:
+            reasons[index] = "missing effect and variance"
+        elif effect_missing[index]:
+            reasons[index] = "missing effect"
+        else:
+            reasons[index] = "missing variance"
+
+    if not np.any(included):
+        raise InvalidStudyDataError(
+            "No studies remain after applying the missing-value policy."
+        )
+
+    return NormalizedStudies(
+        row_id=np.arange(len(effect_values), dtype=np.int64),
+        study=labels,
+        effect=effect_values,
+        variance=variance_values,
+        included=included,
+        exclusion_reason=reasons,
+    )

meta_analyze/effect_sizes/__init__.py

@@ -0,0 +1,17 @@
+"""Study-level effect-size calculations."""
+
+from .binary import BinaryEffectData, BinaryStudies, calculate_binary_effects
+from .continuous import (
+    ContinuousEffectData,
+    ContinuousStudies,
+    calculate_continuous_effects,
+)
+
+__all__ = [
+    "BinaryEffectData",
+    "BinaryStudies",
+    "ContinuousEffectData",
+    "ContinuousStudies",
+    "calculate_binary_effects",
+    "calculate_continuous_effects",
+]