PyMetaAnalysis 0.2.1__tar.gz → 0.3.0__tar.gz

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

@@ -6,6 +6,28 @@ 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

{pymetaanalysis-0.2.1 → 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.1
-date-released: 2026-07-17
+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.1 → pymetaanalysis-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyMetaAnalysis
-Version: 0.2.1
+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
@@ -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,6 +189,9 @@ 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
 
@@ -182,6 +202,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.3.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
@@ -123,6 +140,9 @@ 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
 
@@ -133,6 +153,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.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.1 → 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.1 → 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.1 → 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.1 → 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.

{pymetaanalysis-0.2.1 → pymetaanalysis-0.3.0}/docs/limitations.md

@@ -17,13 +17,16 @@ deferred functionality explicit.
 - independent subgroup fits and a formal subgroup-differences test;
 - leave-one-out and cumulative repeated-fit workflows;
 - forest and descriptive funnel plots;
-- structured provenance and reports.
+- structured provenance and reports;
+- study-level Meta-regression with numeric and explicitly encoded categorical
+  moderators, generalized DL/PM/REML, and normal/Hartung-Knapp inference.
 
 ## Not currently implemented
 
 - Peto odds ratios;
 - Mantel-Haenszel risk differences or random-effects MH pooling;
-- meta-regression or continuous/categorical moderator models;
+- formula parsing, automatic interactions/splines, stepwise moderator
+  selection, multiplicity correction, or arbitrary linear contrasts;
 - multilevel, multivariate, network, dose-response, diagnostic-accuracy, or
   individual-participant-data meta-analysis;
 - robust variance estimation or dependent-effect clustering;
@@ -51,8 +54,14 @@ of heterogeneity and should not be interpreted as interchangeable decision
 rules. A non-significant Q test is not evidence of homogeneity.
 
 Subgroup analyses estimate tau-squared independently within each random-
-effects subgroup. A common tau-squared strategy and meta-regression-based
-moderator tests are not yet available.
+effects subgroup. This differs from fitting a Meta-regression with categorical
+moderators and a single residual tau-squared.
+
+Meta-regression uses aggregate study-level moderators. Coefficients are
+susceptible to ecological bias, confounding, measurement error, low power, and
+post-hoc model selection. They do not establish individual-level associations
+or causal effects. The package warns below ten studies but does not prohibit a
+scientifically prespecified, full-rank model when `k > p`.
 
 Funnel plots are descriptive. Their pseudo confidence limits exclude tau-
 squared, and asymmetry does not establish publication bias.

{pymetaanalysis-0.2.1 → pymetaanalysis-0.3.0}/docs/methods/statistical-methods.md

@@ -161,6 +161,127 @@ proportion internally and is formatted as a percentage in human-readable
 output. With one study, Q is zero and its p-value, I-squared, and H-squared are
 unavailable.
 
+## Meta-regression
+
+For `k` study effects, let `X` be the full-rank `k`-by-`p` design matrix. It
+contains an intercept by default plus numeric moderator columns and treatment-
+coded categorical terms:
+
+```text
+y = X beta + u + epsilon
+epsilon ~ N(0, V),  V = diag(v_i)
+u ~ N(0, tau^2 I)
+```
+
+Given residual tau-squared:
+
+```text
+W = diag(1 / (v_i + tau^2))
+B = (X' W X)^(-1)
+beta_hat = B X' W y
+P = W - W X B X' W
+residual df = k - p
+```
+
+The implementation uses stable linear solves rather than forming an explicit
+matrix inverse. A rank-deficient design or `k <= p` is rejected; terms are not
+silently removed and a pseudo-inverse is not used.
+
+### Residual tau-squared
+
+For generalized DL, define `W0` and `P0` at tau-squared zero:
+
+```text
+QE0 = y' P0 y
+C = trace(P0)
+tau^2_DL = max(0, (QE0 - (k-p)) / C)
+```
+
+PM solves:
+
+```text
+y' P(tau^2) y = k - p
+```
+
+REML solves the restricted score:
+
+```text
+y' P(tau^2)^2 y - trace(P(tau^2)) = 0
+```
+
+All estimators are constrained to non-negative tau-squared. PM and REML use a
+bracketed scalar root; a non-positive equation at zero returns the boundary.
+Failure raises `ConvergenceError` without estimator fallback.
+
+### Coefficient and moderator inference
+
+Normal inference uses covariance `B`, z coefficient tests, and a chi-squared
+Wald test for one or more moderator terms.
+
+For both Hartung-Knapp choices:
+
+```text
+q = y' P(tau^2) y / (k-p)
+Cov_HK(beta_hat) = q B
+```
+
+Coefficient tests use a t distribution with `k-p` degrees of freedom. Joint
+tests divide their Wald statistic by the number of tested terms and use an F
+distribution with that numerator df and `k-p` denominator df.
+`hartung_knapp_adhoc` replaces `q` with `max(1, q)`; unmodified
+`hartung_knapp` retains `q` and warns when it is below one.
+
+The global moderator test covers every non-intercept term.
+`test_moderator(name)` covers every encoded term for one original moderator,
+so a multi-level category receives a joint test.
+
+### Residual heterogeneity and pseudo-R-squared
+
+Residual heterogeneity uses:
+
+```text
+QE = y' P0 y
+QE ~ chi-square_(k-p) under the null
+```
+
+Common models derive residual I-squared and H-squared from QE. Mixed models
+use:
+
+```text
+v_typical = (k-p) / trace(P0)
+I^2_residual = tau^2 / (tau^2 + v_typical)
+H^2_residual = 1 + tau^2 / v_typical
+```
+
+For mixed models with an intercept, the same rows are refitted with an
+intercept-only design and the same tau-squared estimator:
+
+```text
+R^2_raw = 1 - tau^2_model / tau^2_null
+R^2 = max(0, R^2_raw)
+```
+
+The raw value is retained. Pseudo-R-squared is unavailable when the null
+tau-squared is zero and is not equivalent to ordinary regression R-squared.
+
+### Meta-regression prediction
+
+For a new design vector `x0`:
+
+```text
+fitted = x0' beta_hat
+Var_mean = x0' Cov(beta_hat) x0
+```
+
+Mean-effect intervals use the selected normal or `t_(k-p)` critical value. A
+mixed model additionally reports a true-effect prediction interval:
+
+```text
+fitted +/- critical * sqrt(tau^2 + Var_mean)
+```
+
+It does not include a sampling variance for a future observed effect.
+
 ## Binary study effects
 
 For a treatment/control 2-by-2 table: