PyMetaAnalysis 0.2.0__tar.gz → 0.3.0__tar.gz

{pymetaanalysis-0.2.0 → pymetaanalysis-0.3.0}/CHANGELOG.md

@@ -6,6 +6,35 @@ Changes planned for the next release accumulate under `Unreleased`.
 
 ## Unreleased
 
+## 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
+
+- README documentation and repository links use absolute URLs so they resolve
+  correctly when the project description is rendered on PyPI.
+
 ## 0.2.0 - 2026-07-16
 
 ### Added

{pymetaanalysis-0.2.0 → pymetaanalysis-0.3.0}/CITATION.cff

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

{pymetaanalysis-0.2.0 → pymetaanalysis-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyMetaAnalysis
-Version: 0.2.0
+Version: 0.3.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
@@ -51,7 +51,7 @@ Description-Content-Type: text/markdown
 
 [![CI](https://github.com/ZhaoboDing/PyMetaAnalysis/actions/workflows/ci.yml/badge.svg)](https://github.com/ZhaoboDing/PyMetaAnalysis/actions/workflows/ci.yml)
 [![Documentation](https://github.com/ZhaoboDing/PyMetaAnalysis/actions/workflows/pages.yml/badge.svg)](https://zhaoboding.github.io/PyMetaAnalysis/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/ZhaoboDing/PyMetaAnalysis/blob/main/LICENSE)
 
 PyMetaAnalysis is an early-stage, pandas-first Python library for conventional
 study-level meta-analysis. It accepts DataFrames, NumPy arrays, and ordinary
@@ -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
@@ -172,24 +189,28 @@ 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.
+An eligible single-numeric-moderator Meta-regression result additionally
+provides `regression.bubble()` with fitted confidence and optional prediction
+bands.
 
 ## Documentation
 
 The complete documentation is published at
 [zhaoboding.github.io/PyMetaAnalysis](https://zhaoboding.github.io/PyMetaAnalysis/).
 
-- [Installation](docs/installation.md)
-- [Getting started](docs/getting-started.md)
-- [Input data and row decisions](docs/guides/input-data.md)
-- [Generic](docs/guides/generic-effects.md), [binary](docs/guides/binary-outcomes.md), and [continuous](docs/guides/continuous-outcomes.md) guides
-- [Choosing methods](docs/guides/method-selection.md) and [statistical formulas](docs/methods/statistical-methods.md)
-- [Sensitivity analysis](docs/guides/sensitivity-analysis.md) and [plotting](docs/guides/plotting.md)
-- [Public API](docs/reference/api.md), [result objects](docs/reference/results.md), and [report schema](docs/reference/report-schema.md)
-- [Validation strategy](docs/validation.md) and [scope/limitations](docs/limitations.md)
-- [Citation guidance](docs/citation.md)
-- [R `meta`/`metafor` mapping](docs/guides/r-interoperability.md)
-
-An executable [end-to-end notebook](examples/quickstart.ipynb) uses synthetic
+- [Installation](https://zhaoboding.github.io/PyMetaAnalysis/installation/)
+- [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/)
+- [Validation strategy](https://zhaoboding.github.io/PyMetaAnalysis/validation/) and [scope/limitations](https://zhaoboding.github.io/PyMetaAnalysis/limitations/)
+- [Citation guidance](https://zhaoboding.github.io/PyMetaAnalysis/citation/)
+- [R `meta`/`metafor` mapping](https://zhaoboding.github.io/PyMetaAnalysis/guides/r-interoperability/)
+
+An executable [end-to-end notebook](https://github.com/ZhaoboDing/PyMetaAnalysis/blob/main/examples/quickstart.ipynb) uses synthetic
 data to demonstrate analysis, provenance, reporting, sensitivity, and plotting.
 
 Build the complete site locally with:
@@ -207,16 +228,22 @@ edge cases, and committed R `metafor` reference fixtures. CI covers Python
 distribution builds.
 
 This is independent cross-software validation, not a formal external
-statistical audit. See [validation](docs/validation.md) for exact coverage.
+statistical audit. See
+[validation](https://zhaoboding.github.io/PyMetaAnalysis/validation/) for exact
+coverage.
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) and the full
-[development guide](docs/development.md). Statistical changes require formula
+See
+[CONTRIBUTING.md](https://github.com/ZhaoboDing/PyMetaAnalysis/blob/main/CONTRIBUTING.md)
+and the full
+[development guide](https://zhaoboding.github.io/PyMetaAnalysis/development/).
+Statistical changes require formula
 documentation, boundary tests, and an independent comparison where available.
 
-Security-sensitive reports should follow [SECURITY.md](SECURITY.md).
+Security-sensitive reports should follow
+[SECURITY.md](https://github.com/ZhaoboDing/PyMetaAnalysis/blob/main/SECURITY.md).
 
 ## License
 
-[MIT](LICENSE)
+[MIT](https://github.com/ZhaoboDing/PyMetaAnalysis/blob/main/LICENSE)

{pymetaanalysis-0.2.0 → pymetaanalysis-0.3.0}/README.md

@@ -2,7 +2,7 @@
 
 [![CI](https://github.com/ZhaoboDing/PyMetaAnalysis/actions/workflows/ci.yml/badge.svg)](https://github.com/ZhaoboDing/PyMetaAnalysis/actions/workflows/ci.yml)
 [![Documentation](https://github.com/ZhaoboDing/PyMetaAnalysis/actions/workflows/pages.yml/badge.svg)](https://zhaoboding.github.io/PyMetaAnalysis/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/ZhaoboDing/PyMetaAnalysis/blob/main/LICENSE)
 
 PyMetaAnalysis is an early-stage, pandas-first Python library for conventional
 study-level meta-analysis. It accepts DataFrames, NumPy arrays, and ordinary
@@ -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
@@ -123,24 +140,28 @@ 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.
+An eligible single-numeric-moderator Meta-regression result additionally
+provides `regression.bubble()` with fitted confidence and optional prediction
+bands.
 
 ## Documentation
 
 The complete documentation is published at
 [zhaoboding.github.io/PyMetaAnalysis](https://zhaoboding.github.io/PyMetaAnalysis/).
 
-- [Installation](docs/installation.md)
-- [Getting started](docs/getting-started.md)
-- [Input data and row decisions](docs/guides/input-data.md)
-- [Generic](docs/guides/generic-effects.md), [binary](docs/guides/binary-outcomes.md), and [continuous](docs/guides/continuous-outcomes.md) guides
-- [Choosing methods](docs/guides/method-selection.md) and [statistical formulas](docs/methods/statistical-methods.md)
-- [Sensitivity analysis](docs/guides/sensitivity-analysis.md) and [plotting](docs/guides/plotting.md)
-- [Public API](docs/reference/api.md), [result objects](docs/reference/results.md), and [report schema](docs/reference/report-schema.md)
-- [Validation strategy](docs/validation.md) and [scope/limitations](docs/limitations.md)
-- [Citation guidance](docs/citation.md)
-- [R `meta`/`metafor` mapping](docs/guides/r-interoperability.md)
-
-An executable [end-to-end notebook](examples/quickstart.ipynb) uses synthetic
+- [Installation](https://zhaoboding.github.io/PyMetaAnalysis/installation/)
+- [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/)
+- [Validation strategy](https://zhaoboding.github.io/PyMetaAnalysis/validation/) and [scope/limitations](https://zhaoboding.github.io/PyMetaAnalysis/limitations/)
+- [Citation guidance](https://zhaoboding.github.io/PyMetaAnalysis/citation/)
+- [R `meta`/`metafor` mapping](https://zhaoboding.github.io/PyMetaAnalysis/guides/r-interoperability/)
+
+An executable [end-to-end notebook](https://github.com/ZhaoboDing/PyMetaAnalysis/blob/main/examples/quickstart.ipynb) uses synthetic
 data to demonstrate analysis, provenance, reporting, sensitivity, and plotting.
 
 Build the complete site locally with:
@@ -158,16 +179,22 @@ edge cases, and committed R `metafor` reference fixtures. CI covers Python
 distribution builds.
 
 This is independent cross-software validation, not a formal external
-statistical audit. See [validation](docs/validation.md) for exact coverage.
+statistical audit. See
+[validation](https://zhaoboding.github.io/PyMetaAnalysis/validation/) for exact
+coverage.
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) and the full
-[development guide](docs/development.md). Statistical changes require formula
+See
+[CONTRIBUTING.md](https://github.com/ZhaoboDing/PyMetaAnalysis/blob/main/CONTRIBUTING.md)
+and the full
+[development guide](https://zhaoboding.github.io/PyMetaAnalysis/development/).
+Statistical changes require formula
 documentation, boundary tests, and an independent comparison where available.
 
-Security-sensitive reports should follow [SECURITY.md](SECURITY.md).
+Security-sensitive reports should follow
+[SECURITY.md](https://github.com/ZhaoboDing/PyMetaAnalysis/blob/main/SECURITY.md).
 
 ## License
 
-[MIT](LICENSE)
+[MIT](https://github.com/ZhaoboDing/PyMetaAnalysis/blob/main/LICENSE)

{pymetaanalysis-0.2.0 → pymetaanalysis-0.3.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.0 → pymetaanalysis-0.3.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.3.0/docs/guides/meta-regression.md

@@ -0,0 +1,220 @@
+# Meta-regression
+
+Meta-regression relates study effect estimates to one or more study-level
+moderators. It is a natural extension of subgroup analysis, but it does not
+turn aggregate study data into individual-level evidence.
+
+!!! warning "Interpretation boundary"
+
+    A Meta-regression coefficient is a study-level association. It may reflect
+    ecological bias, confounding, measurement differences, or post-hoc model
+    selection and must not be interpreted as an individual-level causal effect.
+    Fits with fewer than ten studies carry an explicit warning.
+
+## Fit a numeric moderator
+
+Provide a generic effect plus exactly one of its sampling variance or standard
+error:
+
+```python
+import pandas as pd
+import meta_analyze as ma
+
+studies = pd.DataFrame(
+    {
+        "citation": ["A", "B", "C", "D", "E", "F"],
+        "effect": [0.12, 0.25, 0.41, 0.38, 0.62, 0.76],
+        "se": [0.18, 0.20, 0.17, 0.23, 0.19, 0.21],
+        "mean_age": [42.0, 48.0, 51.0, 55.0, 60.0, 64.0],
+    }
+)
+
+result = ma.meta_regression(
+    studies,
+    effect="effect",
+    standard_error="se",
+    moderators=["mean_age"],
+    study="citation",
+    model="mixed",
+    tau2_method="REML",
+)
+
+print(result.summary())
+print(result.coefficients)
+```
+
+Numeric moderators are used exactly as supplied. PyMetaAnalysis does not
+center, scale, transform, or impute them automatically.
+
+## Encode categorical moderators explicitly
+
+Every categorical moderator requires an ordered, complete list of levels. The
+first level is the treatment-coding reference:
+
+```python
+result = ma.meta_regression(
+    studies,
+    effect="effect",
+    standard_error="se",
+    moderators=["mean_age", "region"],
+    categorical={
+        "region": ["Europe", "Asia", "North America"],
+    },
+)
+```
+
+This produces terms such as `region[Asia]` and `region[North America]`, each
+relative to `Europe`. The reference never depends on row order. Undeclared
+levels, levels absent after exclusions, and string moderators omitted from
+`categorical=` are errors rather than implicit recoding decisions.
+
+Formula parsing, automatic interactions, splines, and polynomial terms are not
+implemented. Construct those columns explicitly before fitting when they are
+scientifically prespecified.
+
+## Array-like input
+
+Use a mapping when moderators are arrays rather than DataFrame column names:
+
+```python
+result = ma.meta_regression(
+    effect=[0.10, 0.32, 0.45, 0.71],
+    variance=[0.04, 0.05, 0.06, 0.08],
+    moderators={"dose": [0.0, 1.0, 2.0, 3.0]},
+    model="common",
+)
+```
+
+A sequence such as `moderators=["mean_age", "region"]` is only meaningful
+with a DataFrame. A mapping may mix DataFrame column selectors and array-like
+values, provided every input has one value per row.
+
+## Models and inference
+
+`model="mixed"` is the default. It estimates residual tau-squared after the
+moderators using REML, PM, or DL. `model="common"` fixes residual tau-squared
+at zero and supports normal inference only.
+
+| Setting | Coefficient tests and intervals | Joint moderator test |
+| --- | --- | --- |
+| `normal` | z / normal | chi-squared |
+| `hartung_knapp` | t with `k-p` df | F with `k-p` denominator df |
+| `hartung_knapp_adhoc` | safeguarded t with `k-p` df | safeguarded F |
+
+The unmodified Hartung-Knapp result warns when its covariance is below the
+classic covariance. The `adhoc` choice explicitly applies a lower-bound scale
+of one. Common-effect models reject both Hartung-Knapp choices.
+
+The design matrix must be full rank and leave positive residual degrees of
+freedom (`k > p`). PyMetaAnalysis does not silently drop collinear terms or use
+a pseudo-inverse.
+
+## Inspect the result
+
+Meta-regression has no single pooled effect, so `MetaRegressionResult` does not
+provide a scalar `estimate` or `ci`. Inspect its coefficient table instead:
+
+```python
+result.coefficients
+result.coefficient_covariance
+result.global_test
+result.test_moderator("region")
+result.heterogeneity
+result.tau2
+result.tau2_null
+result.pseudo_r2
+result.diagnostics
+```
+
+`global_test` tests all non-intercept terms. `test_moderator(name)` tests every
+encoded term belonging to that original moderator, so a multi-level category
+receives one joint test rather than separate interpretation through dummy-term
+p-values.
+
+`study_results` retains every input row and contains fitted values, residuals,
+precision weights, normalized precision weights, and leverage. A regression
+precision weight is not a universal percentage contribution to every
+coefficient.
+
+## Predict at moderator values
+
+Prediction replays the fitted numeric and categorical encoding:
+
+```python
+predictions = result.predict(
+    pd.DataFrame(
+        {
+            "mean_age": [50.0, 65.0],
+            "region": ["Europe", "Asia"],
+        }
+    )
+)
+```
+
+Every model returns the fitted mean and its confidence interval. Mixed-effects
+models also return `pi_low` and `pi_high` for the distribution of true effects
+in a new study with those moderators. The interval does not include an
+additional, unknown sampling variance for a future observed estimate. Unknown
+categories and missing prediction inputs are rejected.
+
+## Plot a single numeric moderator
+
+After installing the `plot` extra, an intercept-containing model with exactly
+one numeric moderator can be displayed as a weighted bubble plot:
+
+```python
+ax = result.bubble(
+    moderator_label="Mean age (years)",
+    effect_label="Treatment effect",
+    show_confidence_interval=True,
+    show_prediction_interval=True,
+)
+```
+
+Bubble area is proportional to normalized fitted precision weight. The fitted
+line and interval bands reuse `result.predict()`, including the selected normal
+or Hartung-Knapp covariance and critical value. A prediction band is available
+only for mixed-effects models.
+
+PyMetaAnalysis rejects bubble plots for categorical, multiple-moderator, or
+no-intercept fits. Drawing a marginal or partial-effect line for those models
+requires explicit choices for the other moderator values, and the library does
+not silently choose them.
+
+## Residual heterogeneity and pseudo-R²
+
+The result reports residual `QE`, I-squared, H-squared, and tau-squared. For an
+intercept-containing mixed model, PyMetaAnalysis also refits the same included
+rows without moderators and reports:
+
+```text
+pseudo-R² = max(0, 1 - tau²_model / tau²_null)
+```
+
+The raw value is retained as `pseudo_r2_raw`. If the null-model tau-squared is
+zero, pseudo-R² is undefined; if moderators increase estimated tau-squared,
+the public value is truncated to zero and the negative raw value is retained
+with a warning. Pseudo-R² is not the proportion of outcome variance explained
+in ordinary individual-level regression.
+
+## Missing values, provenance, and reports
+
+`missing="raise"` identifies every missing effect, uncertainty, study label,
+or moderator field by row. `missing="drop"` excludes the entire row from every
+model calculation while retaining it in `study_results` with all applicable
+reasons.
+
+```python
+result.provenance
+result.method_details()
+result.report().to_json()
+```
+
+Provenance records moderator input roles and categorical treatment coding.
+Reports include coefficients, their covariance, residual heterogeneity,
+moderator tests, encoding, diagnostics, row decisions, and the study-level
+interpretation warning.
+
+See [statistical methods](../methods/statistical-methods.md#meta-regression) for
+the equations and [scope and limitations](../limitations.md) before using the
+model for consequential work.

{pymetaanalysis-0.2.0 → pymetaanalysis-0.3.0}/docs/guides/plotting.md

@@ -1,6 +1,7 @@
 # Plotting
 
-Forest, subgroup forest, and funnel plots use optional Matplotlib support.
+Forest, subgroup forest, funnel, and Meta-regression bubble plots use optional
+Matplotlib support.
 Install it with:
 
 ```console
@@ -96,6 +97,36 @@ selection, design differences, chance, or publication processes. It is not by
 itself evidence of publication bias. PyMetaAnalysis currently provides the
 plot but not formal asymmetry tests.
 
+## Meta-regression bubble plots
+
+An intercept-containing Meta-regression with exactly one numeric moderator
+provides:
+
+```python
+ax = regression.bubble(
+    moderator_label="Dose",
+    effect_label="Effect",
+    show_confidence_interval=True,
+    show_prediction_interval=False,
+)
+```
+
+Study marker area is proportional to normalized precision weight. The line,
+mean confidence band, and optional mixed-effects true-effect prediction band
+are obtained from the fitted model's `predict()` method.
+
+| Parameter | Meaning |
+| --- | --- |
+| `ax` | Existing axes; a new one is created when omitted |
+| `moderator_label` | X-axis label; defaults to the moderator name |
+| `effect_label` | Y-axis label; defaults to `"Effect"` |
+| `show_confidence_interval` | Draw the fitted mean confidence band |
+| `show_prediction_interval` | Draw a mixed-effects true-effect prediction band |
+
+Categorical, multivariable, and no-intercept fits are rejected because a
+marginal plot would require values or averaging rules for other terms. The
+function does not infer those scientific choices.
+
 ## Save or display
 
 The caller controls rendering:

{pymetaanalysis-0.2.0 → pymetaanalysis-0.3.0}/docs/guides/provenance-reporting.md

@@ -100,7 +100,7 @@ The payload contains:
 - provenance and warnings;
 - row-level study results.
 
-Report schema 1.1 records the resolved heterogeneity definition as
+Report schema 1.2 records the resolved heterogeneity definition as
 `heterogeneity.i2_method`.
 
 The complete key-level contract, including the separately versioned

{pymetaanalysis-0.2.0 → pymetaanalysis-0.3.0}/docs/index.md

@@ -18,8 +18,9 @@ effects, exclusions, weights, method choices, and diagnostics.
 | Effect estimates and sampling variances | `meta_analysis()` | Generic inverse variance |
 | Events and totals for two groups | `meta_binary()` | OR, RR, RD |
 | Means, SDs, and sample sizes for two groups | `meta_continuous()` | MD, Hedges' g |
+| Effect estimates, uncertainty, and study-level moderators | `meta_regression()` | Generic Meta-regression |
 
-All three functions accept an optional `subgroup=` column or array. Supplying
+The three pooling functions accept an optional `subgroup=` column or array. Supplying
 it returns a dedicated subgroup result containing each group, the overall
 analysis, and a formal test for subgroup differences.
 
@@ -52,6 +53,7 @@ shows how to inspect its output. Continue with the guide matching your input:
 - [generic effects and variances](guides/generic-effects.md);
 - [binary outcomes](guides/binary-outcomes.md);
 - [continuous outcomes](guides/continuous-outcomes.md).
+- [study-level Meta-regression](guides/meta-regression.md).
 
 Read [input data and row decisions](guides/input-data.md) before building a
 pipeline around exclusions or mixed DataFrame/array inputs.
@@ -82,10 +84,11 @@ lists unsupported methods explicitly.
 
 ## Project status
 
-PyMetaAnalysis 0.2.0 adds direct generic standard-error input to the initial
-public analysis scope. It has not undergone a formal external statistical
-audit. Pin the package version for consequential work and independently check
-important analyses. See the repository
+PyMetaAnalysis 0.2.1 fixes documentation and repository links in the PyPI
+project description. Version 0.2.0 added direct generic standard-error input
+to the initial public analysis scope. The project has not undergone a formal
+external statistical audit. Pin the package version for consequential work
+and independently check important analyses. See the repository
 [changelog](https://github.com/ZhaoboDing/PyMetaAnalysis/blob/main/CHANGELOG.md)
 and [contribution guide](development.md). For manuscripts and archived
 analyses, see [citing PyMetaAnalysis](citation.md).