PyMetaAnalysis 0.2.1__tar.gz → 0.4.0__tar.gz

{pymetaanalysis-0.2.1 → pymetaanalysis-0.4.0}/CHANGELOG.md

@@ -6,6 +6,48 @@ Changes planned for the next release accumulate under `Unreleased`.
 
 ## Unreleased
 
+## 0.4.0 - 2026-07-23
+
+### Added
+
+- leave-one-out Meta-regression refits with model-level diagnostics,
+  coefficient changes, explicit unidentifiable-deletion records, and preserved
+  provenance.
+- exact Meta-regression externally standardized residuals, Cook's distances,
+  DFBETAS, transparent screening thresholds, and fixed-version R `metafor`
+  cross-software fixtures.
+- Meta-regression term VIF, moderator-level GVIF/GSIF, and weighted,
+  column-scaled condition diagnostics with variance-decomposition proportions,
+  heuristic-only flags, and R `metafor` cross-software fixtures.
+- explicit named Meta-regression linear contrasts with nonzero null values,
+  individual z/t inference, joint chi-squared/F tests, labeled coefficient
+  matrices, and R `metafor` cross-software fixtures.
+- opt-in Riley Meta-regression true-effect prediction intervals using
+  `t_(k-p-1)`, with explicit residual-df validation, preserved refit
+  configuration, and fixed-version R `metafor` boundary references.
+
+## 0.3.0 - 2026-07-22
+
+### Added
+
+- pandas-first `meta_regression()` for numeric, explicitly encoded categorical,
+  and multiple study-level moderators;
+- common- and mixed-effects weighted regression with generalized DL, PM, and
+  REML residual tau-squared estimators;
+- normal, Hartung-Knapp, and safeguarded Hartung-Knapp coefficient inference,
+  distribution-explicit moderator tests, residual heterogeneity, pseudo-R²,
+  prediction, provenance, and structured reports;
+- optional weighted bubble plots for intercept-containing Meta-regression fits
+  with exactly one numeric moderator;
+- independent R `metafor` fixtures covering numeric, categorical,
+  multivariable, zero-tau-squared, missing-row, and small-sample cases;
+- an executable Meta-regression notebook plus a multivariable performance
+  baseline and expanded property, numerical-stability, and warning tests.
+
+### Changed
+
+- report schema 1.2 adds the `meta_regression` report type.
+
 ## 0.2.1 - 2026-07-17
 
 ### Fixed

{pymetaanalysis-0.2.1 → pymetaanalysis-0.4.0}/CITATION.cff

@@ -8,8 +8,8 @@ authors:
   - family-names: Ding
     given-names: Zhaobo
     email: ding.zb@yahoo.com
-version: 0.2.1
-date-released: 2026-07-17
+version: 0.4.0
+date-released: 2026-07-23
 repository-code: https://github.com/ZhaoboDing/PyMetaAnalysis
 url: https://zhaoboding.github.io/PyMetaAnalysis/
 license: MIT

{pymetaanalysis-0.2.1 → pymetaanalysis-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyMetaAnalysis
-Version: 0.2.1
+Version: 0.4.0
 Summary: A pandas-first, auditable meta-analysis library for Python
 Project-URL: Documentation, https://zhaoboding.github.io/PyMetaAnalysis/
 Project-URL: Source, https://github.com/ZhaoboDing/PyMetaAnalysis
@@ -28,7 +28,7 @@ Requires-Dist: actionlint-py>=1.7.12.24; extra == 'dev'
 Requires-Dist: build>=1.2; extra == 'dev'
 Requires-Dist: mypy>=1.10; extra == 'dev'
 Requires-Dist: pandas-stubs>=2.0; extra == 'dev'
-Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: ruff<0.17,>=0.16; extra == 'dev'
 Requires-Dist: scipy-stubs>=1.10; extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: mkdocs>=1.6; extra == 'docs'
@@ -111,6 +111,22 @@ Omit `study=` to use the DataFrame index. Supplying `subgroup=` returns a
 dedicated result containing group fits, the overall fit, and a formal test for
 subgroup differences.
 
+Study-level moderators use the dedicated Meta-regression entry point:
+
+```python
+regression = ma.meta_regression(
+    studies,
+    effect="effect",
+    standard_error="se",
+    moderators=["mean_age", "region"],
+    categorical={"region": ["Europe", "Asia", "North America"]},
+)
+```
+
+Categorical levels are explicit and ordered; the first value is the treatment-
+coding reference. Moderator coefficients describe study-level associations,
+not individual-level or causal effects.
+
 ## Supported analyses
 
 | Input | Effects | Pooling/models |
@@ -118,6 +134,7 @@ subgroup differences.
 | Effect + sampling variance or standard error | Generic | Common/random inverse variance |
 | Two-group events + totals | OR, RR, RD | Common MH OR/RR; common/random IV |
 | Two-group means + SDs + sizes | MD, Hedges' g | Common/random inverse variance |
+| Effect + variance/SE + moderators | Generic | Common/mixed Meta-regression |
 
 Random-effects inverse-variance models support REML (default), Paule-Mandel,
 and DerSimonian-Laird tau-squared estimators. Mean confidence intervals support
@@ -160,11 +177,23 @@ Rows excluded by missing-value or sparse-data policies remain in
 `study_results` with a stable `row_id`, `included=False`, and an
 `exclusion_reason`.
 
-## Sensitivity and plots
+## Diagnostics, contrasts, and plots
 
 ```python
 leave_one_out = result.leave_one_out().to_dataframe()
 cumulative = result.cumulative(order="publication_year").to_dataframe()
+regression_deleted = regression.leave_one_out()
+regression_coefficient_changes = regression_deleted.coefficients
+regression_influence = regression.influence()
+flagged_diagnostics = regression_influence.flagged
+collinearity = regression.collinearity()
+term_vif = collinearity.term_vif
+moderator_gvif = collinearity.moderator_gvif
+condition_indices = collinearity.condition_indices
+south_vs_east = regression.contrast(
+    {"region[South]": 1.0, "region[East]": -1.0},
+    name="South - East",
+)
 
 ax = result.forest(show_prediction_interval=True)
 ax = result.funnel()
@@ -172,6 +201,20 @@ ax = result.funnel()
 
 Plotting methods return Matplotlib axes and never call `show()`. Funnel plots
 are descriptive small-study-effect diagnostics, not proof of publication bias.
+Meta-regression leave-one-out results also expose a long-form coefficient
+change table. Exact influence diagnostics add externally standardized
+residuals, Cook's distance, DFBETAS, and explicit heuristic screening
+thresholds without automatically excluding studies. Meta-regression
+collinearity diagnostics add `metafor`-compatible VIF/GVIF plus weighted,
+column-scaled condition indices and variance-decomposition proportions.
+Their documented references are review aids, not automatic variable-selection
+rules. Explicit named linear contrasts provide individual z/t inference and
+full-rank joint chi-squared/F tests without silently adjusting for multiple
+testing. An eligible
+single-numeric-moderator Meta-regression result additionally provides
+`regression.bubble()` with fitted confidence and optional prediction bands.
+Mixed-effects Meta-regression supports its documented default prediction rule
+and an explicit Riley `t_(k-p-1)` alternative.
 
 ## Documentation
 
@@ -182,6 +225,7 @@ The complete documentation is published at
 - [Getting started](https://zhaoboding.github.io/PyMetaAnalysis/getting-started/)
 - [Input data and row decisions](https://zhaoboding.github.io/PyMetaAnalysis/guides/input-data/)
 - [Generic](https://zhaoboding.github.io/PyMetaAnalysis/guides/generic-effects/), [binary](https://zhaoboding.github.io/PyMetaAnalysis/guides/binary-outcomes/), and [continuous](https://zhaoboding.github.io/PyMetaAnalysis/guides/continuous-outcomes/) guides
+- [Meta-regression](https://zhaoboding.github.io/PyMetaAnalysis/guides/meta-regression/)
 - [Choosing methods](https://zhaoboding.github.io/PyMetaAnalysis/guides/method-selection/) and [statistical formulas](https://zhaoboding.github.io/PyMetaAnalysis/methods/statistical-methods/)
 - [Sensitivity analysis](https://zhaoboding.github.io/PyMetaAnalysis/guides/sensitivity-analysis/) and [plotting](https://zhaoboding.github.io/PyMetaAnalysis/guides/plotting/)
 - [Public API](https://zhaoboding.github.io/PyMetaAnalysis/reference/api/), [result objects](https://zhaoboding.github.io/PyMetaAnalysis/reference/results/), and [report schema](https://zhaoboding.github.io/PyMetaAnalysis/reference/report-schema/)

{pymetaanalysis-0.2.1 → pymetaanalysis-0.4.0}/README.md

@@ -62,6 +62,22 @@ Omit `study=` to use the DataFrame index. Supplying `subgroup=` returns a
 dedicated result containing group fits, the overall fit, and a formal test for
 subgroup differences.
 
+Study-level moderators use the dedicated Meta-regression entry point:
+
+```python
+regression = ma.meta_regression(
+    studies,
+    effect="effect",
+    standard_error="se",
+    moderators=["mean_age", "region"],
+    categorical={"region": ["Europe", "Asia", "North America"]},
+)
+```
+
+Categorical levels are explicit and ordered; the first value is the treatment-
+coding reference. Moderator coefficients describe study-level associations,
+not individual-level or causal effects.
+
 ## Supported analyses
 
 | Input | Effects | Pooling/models |
@@ -69,6 +85,7 @@ subgroup differences.
 | Effect + sampling variance or standard error | Generic | Common/random inverse variance |
 | Two-group events + totals | OR, RR, RD | Common MH OR/RR; common/random IV |
 | Two-group means + SDs + sizes | MD, Hedges' g | Common/random inverse variance |
+| Effect + variance/SE + moderators | Generic | Common/mixed Meta-regression |
 
 Random-effects inverse-variance models support REML (default), Paule-Mandel,
 and DerSimonian-Laird tau-squared estimators. Mean confidence intervals support
@@ -111,11 +128,23 @@ Rows excluded by missing-value or sparse-data policies remain in
 `study_results` with a stable `row_id`, `included=False`, and an
 `exclusion_reason`.
 
-## Sensitivity and plots
+## Diagnostics, contrasts, and plots
 
 ```python
 leave_one_out = result.leave_one_out().to_dataframe()
 cumulative = result.cumulative(order="publication_year").to_dataframe()
+regression_deleted = regression.leave_one_out()
+regression_coefficient_changes = regression_deleted.coefficients
+regression_influence = regression.influence()
+flagged_diagnostics = regression_influence.flagged
+collinearity = regression.collinearity()
+term_vif = collinearity.term_vif
+moderator_gvif = collinearity.moderator_gvif
+condition_indices = collinearity.condition_indices
+south_vs_east = regression.contrast(
+    {"region[South]": 1.0, "region[East]": -1.0},
+    name="South - East",
+)
 
 ax = result.forest(show_prediction_interval=True)
 ax = result.funnel()
@@ -123,6 +152,20 @@ ax = result.funnel()
 
 Plotting methods return Matplotlib axes and never call `show()`. Funnel plots
 are descriptive small-study-effect diagnostics, not proof of publication bias.
+Meta-regression leave-one-out results also expose a long-form coefficient
+change table. Exact influence diagnostics add externally standardized
+residuals, Cook's distance, DFBETAS, and explicit heuristic screening
+thresholds without automatically excluding studies. Meta-regression
+collinearity diagnostics add `metafor`-compatible VIF/GVIF plus weighted,
+column-scaled condition indices and variance-decomposition proportions.
+Their documented references are review aids, not automatic variable-selection
+rules. Explicit named linear contrasts provide individual z/t inference and
+full-rank joint chi-squared/F tests without silently adjusting for multiple
+testing. An eligible
+single-numeric-moderator Meta-regression result additionally provides
+`regression.bubble()` with fitted confidence and optional prediction bands.
+Mixed-effects Meta-regression supports its documented default prediction rule
+and an explicit Riley `t_(k-p-1)` alternative.
 
 ## Documentation
 
@@ -133,6 +176,7 @@ The complete documentation is published at
 - [Getting started](https://zhaoboding.github.io/PyMetaAnalysis/getting-started/)
 - [Input data and row decisions](https://zhaoboding.github.io/PyMetaAnalysis/guides/input-data/)
 - [Generic](https://zhaoboding.github.io/PyMetaAnalysis/guides/generic-effects/), [binary](https://zhaoboding.github.io/PyMetaAnalysis/guides/binary-outcomes/), and [continuous](https://zhaoboding.github.io/PyMetaAnalysis/guides/continuous-outcomes/) guides
+- [Meta-regression](https://zhaoboding.github.io/PyMetaAnalysis/guides/meta-regression/)
 - [Choosing methods](https://zhaoboding.github.io/PyMetaAnalysis/guides/method-selection/) and [statistical formulas](https://zhaoboding.github.io/PyMetaAnalysis/methods/statistical-methods/)
 - [Sensitivity analysis](https://zhaoboding.github.io/PyMetaAnalysis/guides/sensitivity-analysis/) and [plotting](https://zhaoboding.github.io/PyMetaAnalysis/guides/plotting/)
 - [Public API](https://zhaoboding.github.io/PyMetaAnalysis/reference/api/), [result objects](https://zhaoboding.github.io/PyMetaAnalysis/reference/results/), and [report schema](https://zhaoboding.github.io/PyMetaAnalysis/reference/report-schema/)

{pymetaanalysis-0.2.1 → pymetaanalysis-0.4.0}/benchmarks/README.md

@@ -1,9 +1,10 @@
 # Core performance baseline
 
-`benchmark_core.py` measures representative generic, binary, and continuous
-random-effects fits using deterministic synthetic data. Correctness remains the
-primary performance requirement; this benchmark is intended to reveal large
-regressions, not to enforce a fragile wall-clock threshold.
+`benchmark_core.py` measures representative generic, binary, continuous, and
+multivariable Meta-regression random-effects fits using deterministic synthetic
+data. Correctness remains the primary performance requirement; this benchmark
+is intended to reveal large regressions, not to enforce a fragile wall-clock
+threshold.
 
 Run the default benchmark with:
 

{pymetaanalysis-0.2.1 → pymetaanalysis-0.4.0}/benchmarks/benchmark_core.py

@@ -34,6 +34,8 @@ def _cases(studies: int) -> dict[str, Callable[[], object]]:
 
     generic_effect = rng.normal(0.1, 0.25, size=studies)
     generic_variance = rng.uniform(0.01, 0.09, size=studies)
+    moderator = np.linspace(-1.0, 1.0, studies)
+    region = np.resize(np.array(["North", "South", "East"], dtype=object), studies)
 
     n_treat = rng.integers(60, 240, size=studies)
     n_control = rng.integers(60, 240, size=studies)
@@ -75,6 +77,14 @@ def _cases(studies: int) -> dict[str, Callable[[], object]]:
             model="random",
             tau2_method="REML",
         ),
+        "meta_regression_multivariable_reml": lambda: ma.meta_regression(
+            effect=generic_effect,
+            variance=generic_variance,
+            moderators={"moderator": moderator, "region": region},
+            categorical={"region": ["North", "South", "East"]},
+            model="mixed",
+            tau2_method="REML",
+        ),
     }
 
 
@@ -102,8 +112,10 @@ def main() -> None:
     parser.add_argument("--number", type=int, default=5)
     parser.add_argument("--output", type=Path)
     arguments = parser.parse_args()
-    if min(arguments.studies, arguments.repeat, arguments.number) < 1:
-        parser.error("studies, repeat, and number must all be positive")
+    if arguments.studies < 5:
+        parser.error("studies must be at least 5 for the multivariable benchmark")
+    if min(arguments.repeat, arguments.number) < 1:
+        parser.error("repeat and number must both be positive")
 
     payload = _metadata(arguments)
     payload["cases"] = {

pymetaanalysis-0.4.0/docs/adr/0003-meta-regression-prediction-intervals.md

@@ -0,0 +1,70 @@
+# ADR 0003: Meta-regression prediction-interval choices
+
+- Status: Accepted
+- Date: 2026-07-23
+
+## Context
+
+For a mixed-effects Meta-regression prediction at design vector `x`, the
+estimated true-effect variance combines residual heterogeneity with
+uncertainty in the fitted mean:
+
+```text
+Var_prediction = tau^2 + x' Cov(beta_hat) x
+```
+
+The critical-value distribution remains a methodological choice. Common
+software offers a default normal-or-t rule and a Riley alternative with one
+fewer residual degree of freedom. Neither approximation removes uncertainty
+from estimating tau-squared, and changing the package default would alter
+existing results.
+
+## Decision
+
+`meta_regression()` accepts
+`prediction_interval_method="default" | "riley"` for mixed-effects models.
+The canonical resolved method is stored in
+`result.method.prediction_interval_method`.
+
+The default remains `normal_or_t_k_minus_p`:
+
+- normal coefficient inference uses a standard normal prediction critical
+  value;
+- either Hartung-Knapp mode uses a t critical value with `k-p` degrees of
+  freedom.
+
+The opt-in Riley method uses a t critical value with `k-p-1` degrees of
+freedom regardless of the coefficient-inference distribution:
+
+```text
+prediction = x' beta_hat
+PI_Riley = prediction +/- t_(k-p-1) *
+           sqrt(tau^2 + x' Cov(beta_hat) x)
+```
+
+Riley intervals require `k-p >= 2`. Requesting Riley for a common-effect model
+or a mixed model without enough residual degrees of freedom raises a domain
+error. The selection is preserved by deleted-study refits and reused by
+`predict()` and `bubble()`.
+
+Both rules predict the distribution of true effects in a new study at the
+specified moderator values. They do not add an unknown sampling variance for
+a future observed effect.
+
+## Validation
+
+The committed fixed-version R `metafor` fixture records default and
+`predtype="Riley"` predictions for normal and Hartung-Knapp inference,
+multivariable moderator values, and a zero-tau-squared boundary. Unit tests
+also check the critical-value formula and invalid degrees of freedom.
+Property-based tests verify symmetry, unchanged mean-effect inference, and
+the Riley interval's greater width relative to the default rule.
+
+## Consequences
+
+- existing fits retain their numerical default;
+- the alternative is explicit, auditable, and reproducible;
+- Riley is documented as an alternative approximation rather than an
+  automatic small-sample correction;
+- future prediction-interval rules require a separate statistical decision
+  and independent reference coverage.

{pymetaanalysis-0.2.1 → pymetaanalysis-0.4.0}/docs/getting-started.md

@@ -71,7 +71,7 @@ result.ci
 result.standard_error
 result.tau2
 result.q
-result.i2       # a proportion from 0 to 1
+result.i2  # a proportion from 0 to 1
 result.h2
 result.i2_method
 ```