PyMetaAnalysis 0.3.0__tar.gz → 0.5.0__tar.gz

{pymetaanalysis-0.3.0 → pymetaanalysis-0.5.0}/.github/workflows/ci.yml

@@ -22,7 +22,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
 
     steps:
       - name: Check out repository

{pymetaanalysis-0.3.0 → pymetaanalysis-0.5.0}/.github/workflows/pages.yml

@@ -8,7 +8,7 @@ on:
 
 concurrency:
   group: pages
-  cancel-in-progress: true
+  cancel-in-progress: false
 
 jobs:
   build:
@@ -17,7 +17,6 @@ jobs:
     timeout-minutes: 10
     permissions:
       contents: read
-      pages: write
 
     steps:
       - name: Check out repository

{pymetaanalysis-0.3.0 → pymetaanalysis-0.5.0}/.github/workflows/release.yml

@@ -35,14 +35,17 @@ jobs:
           cache: pip
           cache-dependency-path: pyproject.toml
 
-      - name: Install build tools
+      - name: Install release dependencies
         run: |
           python -m pip install --upgrade pip
-          python -m pip install build twine
+          python -m pip install ".[test]" build twine
 
       - name: Validate release metadata
         run: python tools/check_release.py --tag "$GITHUB_REF_NAME"
 
+      - name: Run tests with branch coverage
+        run: python -m pytest --cov=meta_analyze --cov-branch --cov-report=term-missing
+
       - name: Build distributions
         run: python -m build
 
@@ -91,7 +94,8 @@ jobs:
           path: dist/
 
       - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@release/v1
+        # release/v1.14, pinned because this step holds the PyPI OIDC permission.
+        uses: pypa/gh-action-pypi-publish@ba38be9e461d3875417946c167d0b5f3d385a247
 
   github-release:
     name: Create GitHub Release

pymetaanalysis-0.5.0/CHANGELOG.md

@@ -0,0 +1,187 @@
+# Changelog
+
+All notable changes to PyMetaAnalysis will be documented in this file.
+
+Changes planned for the next release accumulate under `Unreleased`.
+
+## Unreleased
+
+## 0.5.0 - 2026-07-25
+
+### Added
+
+- random-effects inverse-variance results now provide opt-in Q-profile
+  confidence intervals for tau-squared, tau, I-squared, and H-squared, with an
+  explicit formal-empty-set flag at the constrained `[0, 0]` boundary.
+
+### Changed
+
+- sensitivity and influence workflows now borrow internal fitted buffers during
+  refits instead of repeatedly materializing public defensive copies;
+- Meta-regression stores its classic coefficient covariance alongside the
+  selected inference covariance and reuses one shared precision-geometry
+  implementation across fitting and diagnostics.
+- independent `metafor` fixtures now cover categorical and multivariable
+  influence diagnostics, no-intercept Riley prediction intervals, and explicit
+  Mantel-Haenszel pooling correction; iterative failure paths have direct
+  regression tests.
+
+### Fixed
+
+- inverse-variance means, heterogeneity statistics, and pooling and
+  meta-regression tau-squared equations now use overflow-safe relative-weight
+  calculations at the supported float64 boundary;
+- subnormal variances and non-finite derived effects now raise explicit domain
+  errors instead of leaking runtime warnings or returning invalid results;
+- binary OR, RD, and Mantel-Haenszel arithmetic now avoids intermediate
+  overflow for very large finite counts;
+- the sensitivity guide no longer incorrectly states that Meta-regression
+  Cook's distance and DFBETAS are unavailable.
+- subgroup-differences tests now use classic model variances independently of
+  Hartung-Knapp confidence-interval adjustments;
+- leave-one-out and cumulative workflows now retain or skip, respectively,
+  reduced Mantel-Haenszel fits that are not estimable instead of aborting the
+  complete sensitivity analysis;
+- forest and subgroup-forest plots now reject non-positive displayed
+  coordinates before enabling a logarithmic axis;
+- uncorrected risk-ratio analyses now accept a zero non-event cell when the
+  study effect and sampling variance remain well defined.
+- Hartung-Knapp random-effects prediction intervals now use the selected
+  adjusted pooled-mean variance and are recorded as `HK-PR`, matching
+  `metafor` Riley predictions;
+- random-effects subgroup analyses now retain single-study subgroups through
+  an explicit, warned common-effect fallback instead of failing the complete
+  analysis;
+- tagged releases now rerun the full branch-coverage test suite before
+  distributions can be built and published.
+- tau-squared methods and SMD variance conventions now use `None` as the
+  context-sensitive default, so explicitly inapplicable settings raise domain
+  errors instead of being silently ignored;
+- duplicate study labels now add a row-position warning while preserving
+  `row_id` as the unique audit key;
+- report JSON now serializes `pd.NaT` study labels as `null` rather than the
+  string `"NaT"`.
+- Meta-regression with `missing="drop"` now determines complete-row exclusions
+  before validating moderator values, so invalid values in already excluded
+  rows cannot abort the analysis;
+- cumulative analysis now rejects ambiguous string `order` selectors that
+  exist in both source data and study results;
+- empty inputs now report that at least one study row is required, and binary
+  zero-cell errors identify when `correction_scope="none"` disables an
+  otherwise positive correction.
+- iterative tau-squared estimators now mark only an exact constrained zero as
+  a boundary solution, rather than treating every positive root below `atol`
+  as zero;
+- the exported pooling and Meta-regression tau-squared estimators now reject
+  insufficient study or residual degrees of freedom with domain-specific
+  errors;
+- the Mantel-Haenszel estimator now rejects empty and zero-total strata before
+  division, preventing NaN propagation and misleading variance diagnostics.
+- prediction-interval metadata is now `None` when too few studies prevent an
+  interval from being calculated;
+- categorical moderator encoding no longer conflates booleans, integers, and
+  floating-point values through Python's cross-type numeric equality;
+- CI now covers Python 3.14, Pages deployments are not cancelled mid-flight,
+  and the credential-bearing PyPI publisher action is pinned to an immutable
+  commit.
+
+## 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
+
+- 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
+
+- generic `meta_analysis()` accepts either sampling variances or standard
+  errors, with explicit validation and auditable conversion provenance.
+
+### Changed
+
+- package author metadata identifies the project maintainer directly.
+
+### Fixed
+
+- GitHub Release creation receives explicit repository context in tag-driven
+  release jobs.
+
+## 0.1.0 - 2026-07-15
+
+### Added
+
+- pandas-first generic, binary, and continuous study-level meta-analysis APIs;
+- common-effect and random-effects inverse-variance models;
+- common-effect Mantel-Haenszel OR/RR pooling;
+- REML, Paule-Mandel, and DerSimonian-Laird tau-squared estimators;
+- normal, Hartung-Knapp, and safeguarded Hartung-Knapp confidence intervals;
+- HTS random-effects prediction intervals;
+- subgroup, leave-one-out, and cumulative workflows;
+- optional Matplotlib forest, subgroup forest, and funnel plots;
+- immutable results, diagnostics, provenance, Methods text, and JSON/Markdown
+  reports;
+- R `metafor` cross-software fixtures, property tests, and numerical edge-case
+  coverage;
+- explicit RD zero-variance boundary policy and heterogeneity-definition
+  reporting;
+- complete MkDocs user, methods, API, validation, limitation, and development
+  documentation;
+- R `meta`/`metafor` terminology and parameter mappings;
+- machine-readable citation metadata and an executable end-to-end notebook;
+- GitHub Pages and PyPI Trusted Publishing release workflows;
+- release metadata, distribution-content, notebook-execution, and performance
+  baseline tooling.
+
+### Changed
+
+- independent external statistical review is documented as a recommended
+  validation activity rather than a release requirement;
+- report schema 1.1 records `heterogeneity.i2_method`;
+- random-effects I-squared/H-squared use tau-squared and typical within-study
+  variance, while common-effect/MH analyses retain Q-based definitions;
+- random-effects summaries provide method-selection notes for small-study and
+  positive-heterogeneity cases.

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyMetaAnalysis
-Version: 0.3.0
+Version: 0.5.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
@@ -18,6 +18,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
 Requires-Python: >=3.10
 Requires-Dist: numpy>=1.24
@@ -28,7 +29,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'
@@ -139,7 +140,10 @@ not individual-level or causal effects.
 Random-effects inverse-variance models support REML (default), Paule-Mandel,
 and DerSimonian-Laird tau-squared estimators. Mean confidence intervals support
 the normal default plus unmodified and safeguarded Hartung-Knapp variants.
-Eligible random-effects fits include an HTS prediction interval.
+Eligible random-effects fits include an HTS prediction interval under normal
+inference and an HK-PR interval under either Hartung-Knapp variant. Call
+`result.tau2_confidence_interval()` for a Q-profile interval around
+heterogeneity.
 
 Generic analyses accept exactly one of `variance=` or `standard_error=`.
 Standard errors are squared internally and the conversion is recorded in the
@@ -157,6 +161,7 @@ result.estimate
 result.display_estimate
 result.ci
 result.tau2
+tau2_interval = result.tau2_confidence_interval()
 result.i2
 result.i2_method
 result.diagnostics
@@ -177,11 +182,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()
@@ -189,9 +206,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.
-An eligible single-numeric-moderator Meta-regression result additionally
-provides `regression.bubble()` with fitted confidence and optional prediction
-bands.
+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
 

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

@@ -90,7 +90,10 @@ not individual-level or causal effects.
 Random-effects inverse-variance models support REML (default), Paule-Mandel,
 and DerSimonian-Laird tau-squared estimators. Mean confidence intervals support
 the normal default plus unmodified and safeguarded Hartung-Knapp variants.
-Eligible random-effects fits include an HTS prediction interval.
+Eligible random-effects fits include an HTS prediction interval under normal
+inference and an HK-PR interval under either Hartung-Knapp variant. Call
+`result.tau2_confidence_interval()` for a Q-profile interval around
+heterogeneity.
 
 Generic analyses accept exactly one of `variance=` or `standard_error=`.
 Standard errors are squared internally and the conversion is recorded in the
@@ -108,6 +111,7 @@ result.estimate
 result.display_estimate
 result.ci
 result.tau2
+tau2_interval = result.tau2_confidence_interval()
 result.i2
 result.i2_method
 result.diagnostics
@@ -128,11 +132,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()
@@ -140,9 +156,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.
-An eligible single-numeric-moderator Meta-regression result additionally
-provides `regression.bubble()` with fitted confidence and optional prediction
-bands.
+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
 

{pymetaanalysis-0.3.0 → pymetaanalysis-0.5.0}/docs/adr/0002-statistical-policy.md

@@ -2,6 +2,8 @@
 
 - Status: Accepted
 - Date: 2026-07-15
+- Amendment: the prediction-interval variance decision is superseded by
+  [ADR 0004](0004-hartung-knapp-prediction-intervals.md).
 
 ## Context
 
@@ -65,10 +67,11 @@ percentage in human-readable output.
 
 ### Prediction intervals
 
-Random-effects inverse-variance models use the Higgins-Thompson-Spiegelhalter
-prediction interval with `k - 2` degrees of freedom and the classic variance
-of the pooled mean. It is unavailable below three studies. With three or four
-studies it is calculated with an explicit uncertainty warning.
+The original decision used the Higgins-Thompson-Spiegelhalter prediction
+interval with `k - 2` degrees of freedom and the classic variance of the
+pooled mean for every confidence-interval method. ADR 0004 replaces that
+variance rule for Hartung-Knapp fits while retaining the study-count boundary
+and small-sample warning.
 
 ## Validation
 

pymetaanalysis-0.5.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.5.0/docs/adr/0004-hartung-knapp-prediction-intervals.md

@@ -0,0 +1,46 @@
+# ADR 0004: Hartung-Knapp prediction intervals
+
+- Status: Accepted
+- Date: 2026-07-24
+
+## Context
+
+ADR 0002 applied the classic pooled-mean variance to every `k - 2`
+random-effects prediction interval. That kept the interval independent of
+`ci_method`, but it diverged from `metafor` Riley predictions and the
+Hartung-Knapp Partlett-Riley option in R `meta`. Both use the covariance
+selected for mean inference inside the prediction variance.
+
+This difference was material when the unmodified Hartung-Knapp variance was
+below or above the classic variance. The result metadata still identified the
+interval as `HTS`, so callers could not discover the difference from method
+configuration alone.
+
+## Decision
+
+Random-effects inverse-variance prediction intervals retain the `k - 2`
+critical value and three-study minimum:
+
+```text
+mu_hat +/- t_(k - 2, 1 - alpha/2)
+          * sqrt(tau^2 + Var_selected(mu_hat))
+```
+
+- normal inference uses the classic pooled-mean variance and records `HTS`;
+- `hartung_knapp` uses its unmodified adjusted variance and records `HK-PR`;
+- `hartung_knapp_adhoc` uses its lower-bounded adjusted variance and records
+  `HK-PR`.
+
+Committed values are generated directly from
+`metafor::predict(fit, predtype="Riley")` for all three inference choices.
+Prediction intervals remain unavailable below three included studies and
+retain the explicit warning with three or four studies.
+
+## Consequences
+
+- prediction intervals and mean intervals use a coherent selected covariance;
+- HK and safeguarded HK prediction intervals can differ from the normal HTS
+  interval even when tau-squared and the pooled estimate are unchanged;
+- `result.method.prediction_interval_method` distinguishes `HTS` from
+  `HK-PR`;
+- this decision supersedes only the prediction-variance paragraph of ADR 0002.

{pymetaanalysis-0.3.0 → pymetaanalysis-0.5.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
 ```

{pymetaanalysis-0.3.0 → pymetaanalysis-0.5.0}/docs/guides/input-data.md

@@ -54,7 +54,10 @@ zero.
 `row_id` is the zero-based input position. It is independent of the study
 label and remains stable through exclusion, subgroup, leave-one-out, and
 cumulative workflows. Use it when study labels are duplicated or not suitable
-as identifiers.
+as identifiers. Duplicate labels are accepted because several rows can
+legitimately originate from the same publication, but the result records the
+affected row positions in `warnings` so accidental duplication remains
+auditable.
 
 The complete row table is available from:
 
@@ -84,6 +87,13 @@ result = ma.meta_analysis(
 result.excluded_studies[["row_id", "study", "exclusion_reason"]]
 ```
 
+For Meta-regression, missingness is resolved across the outcome, uncertainty,
+study label, and every moderator before moderator values are validated.
+Consequently, a moderator value in an already excluded row is retained for
+audit but cannot abort or influence the fitted design matrix. Moderator values
+in included rows must still satisfy the declared numeric or categorical
+contract.
+
 Dropped rows do not contribute to pooled estimates, Q, tau-squared, prediction
 intervals, or weights. Missing subgroup labels are always rejected because
 silently assigning or dropping them would change the subgroup definition.
@@ -92,7 +102,7 @@ silently assigning or dropping them would change the subgroup definition.
 
 | Input family | Required validation |
 | --- | --- |
-| Generic | finite effect; finite, strictly positive sampling variance |
+| Generic | finite effect; finite, strictly positive sampling variance large enough for a finite float64 inverse weight |
 | Binary | integer event counts and totals; positive totals; `0 <= events <= total` |
 | Continuous | finite means/SDs; non-negative SDs; integer group sizes of at least 2 |
 
@@ -100,6 +110,12 @@ Binary and continuous APIs preserve their raw input columns in
 `study_results`. Derived effects, variances, correction indicators, and
 weights appear alongside them.
 
+All numerical calculations use float64. Internally derived effects and
+variances must remain finite, and every included sampling variance must be
+large enough to produce a finite inverse-variance weight. Values outside that
+representable range raise `InvalidStudyDataError` instead of returning
+non-finite fitted results.
+
 ## Exclusion is visible
 
 Rows excluded by a configured rule remain present with: