PyMetaAnalysis 0.4.0__tar.gz → 0.6.0__tar.gz

{pymetaanalysis-0.4.0 → pymetaanalysis-0.6.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.4.0 → pymetaanalysis-0.6.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.4.0 → pymetaanalysis-0.6.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.4.0 → pymetaanalysis-0.6.0}/.gitignore

@@ -1,5 +1,6 @@
 # Local design notes are intentionally not part of the published project.
 /DESIGN.md
+/articles/
 
 # Python environments and generated files
 /.venv/

pymetaanalysis-0.6.0/CHANGELOG.md

@@ -0,0 +1,204 @@
+# Changelog
+
+All notable changes to PyMetaAnalysis will be documented in this file.
+
+Changes planned for the next release accumulate under `Unreleased`.
+
+## Unreleased
+
+## 0.6.0 - 2026-08-13
+
+### Added
+
+- common-effect Peto one-step odds-ratio pooling, including Peto-specific
+  study estimates, O-minus-E heterogeneity, explicit approximation warnings,
+  provenance/report metadata, and independent R `metafor` references;
+- common-effect Mantel-Haenszel risk-difference pooling with the
+  Sato-Greenland-Robins sampling variance, explicit method metadata,
+  sparse-table policy integration, and independent R `metafor` references.
+
+### Fixed
+
+- isolated builds temporarily cap Hatchling below 1.32 so the release
+  workflow continues to produce Core Metadata 2.4 accepted by Twine 6.2;
+  the cap can be removed once Twine validates Metadata 2.5.
+
+## 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.4.0 → pymetaanalysis-0.6.0}/CITATION.cff

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyMetaAnalysis
-Version: 0.4.0
+Version: 0.6.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
@@ -132,14 +133,17 @@ not individual-level or causal effects.
 | Input | Effects | Pooling/models |
 | --- | --- | --- |
 | 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 events + totals | OR, RR, RD | Common MH; common Peto OR; 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
 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
@@ -149,6 +153,12 @@ Sparse binary behavior is explicit: study-level and Mantel-Haenszel continuity
 corrections are separate, relative-effect double-zero/double-all rows remain
 visible as exclusions, and RD exposes
 `rd_zero_variance="correct" | "exclude"`.
+Peto OR uses raw tables for pooling and a separate one-step study estimator;
+it always reports a caution that its approximation is intended for rare
+outcomes, similar within-study arm sizes, and effects that are not large.
+Common-effect MH risk differences use the Sato-Greenland-Robins sampling
+variance; random-effects binary analyses continue to use inverse-variance
+pooling.
 
 ## Inspect and report
 
@@ -157,6 +167,7 @@ result.estimate
 result.display_estimate
 result.ci
 result.tau2
+tau2_interval = result.tau2_confidence_interval()
 result.i2
 result.i2_method
 result.diagnostics
@@ -247,7 +258,7 @@ python -m mkdocs serve
 
 The test suite combines hand calculations, statistical invariants, numerical
 edge cases, and committed R `metafor` reference fixtures. CI covers Python
-3.10–3.13, declared dependency lower bounds, strict typing/linting, docs, and
+3.10–3.14, declared dependency lower bounds, strict typing/linting, docs, and
 distribution builds.
 
 This is independent cross-software validation, not a formal external

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

@@ -83,14 +83,17 @@ not individual-level or causal effects.
 | Input | Effects | Pooling/models |
 | --- | --- | --- |
 | 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 events + totals | OR, RR, RD | Common MH; common Peto OR; 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
 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
@@ -100,6 +103,12 @@ Sparse binary behavior is explicit: study-level and Mantel-Haenszel continuity
 corrections are separate, relative-effect double-zero/double-all rows remain
 visible as exclusions, and RD exposes
 `rd_zero_variance="correct" | "exclude"`.
+Peto OR uses raw tables for pooling and a separate one-step study estimator;
+it always reports a caution that its approximation is intended for rare
+outcomes, similar within-study arm sizes, and effects that are not large.
+Common-effect MH risk differences use the Sato-Greenland-Robins sampling
+variance; random-effects binary analyses continue to use inverse-variance
+pooling.
 
 ## Inspect and report
 
@@ -108,6 +117,7 @@ result.estimate
 result.display_estimate
 result.ci
 result.tau2
+tau2_interval = result.tau2_confidence_interval()
 result.i2
 result.i2_method
 result.diagnostics
@@ -198,7 +208,7 @@ python -m mkdocs serve
 
 The test suite combines hand calculations, statistical invariants, numerical
 edge cases, and committed R `metafor` reference fixtures. CI covers Python
-3.10–3.13, declared dependency lower bounds, strict typing/linting, docs, and
+3.10–3.14, declared dependency lower bounds, strict typing/linting, docs, and
 distribution builds.
 
 This is independent cross-software validation, not a formal external

{pymetaanalysis-0.4.0 → pymetaanalysis-0.6.0}/docs/adr/0002-statistical-policy.md

@@ -2,6 +2,12 @@
 
 - Status: Accepted
 - Date: 2026-07-15
+- Amendment: the prediction-interval variance decision is superseded by
+  [ADR 0004](0004-hartung-knapp-prediction-intervals.md).
+- Amendment: the decision to defer Mantel-Haenszel risk differences is
+  superseded by [ADR 0005](0005-mantel-haenszel-risk-difference.md).
+- Amendment: the decision to defer Peto pooling is superseded by
+  [ADR 0006](0006-peto-odds-ratio.md).
 
 ## Context
 
@@ -42,13 +48,15 @@ option, and a provenance transformation.
 Mantel-Haenszel pooling remains a common-effect estimator for OR and RR. It
 uses raw tables by default and has a correction setting separate from the one
 used for individual-study effects. Random-effects Mantel-Haenszel, RD
-Mantel-Haenszel, and Peto pooling are outside the current scope.
+Mantel-Haenszel, and Peto pooling were outside the scope of this original
+decision; ADRs 0005 and 0006 supersede the latter two deferrals.
 
 ### Heterogeneity
 
 Cochran's Q, degrees of freedom, and p-value always use common-effect inverse-
 variance weights. Common-effect and Mantel-Haenszel analyses use Q-based
-I-squared and H-squared.
+I-squared and H-squared. ADR 0006 adds Peto's estimator-specific Q while
+retaining those Q-based inconsistency transformations.
 
 Random-effects analyses use:
 
@@ -65,10 +73,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.6.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.6.0/docs/adr/0005-mantel-haenszel-risk-difference.md

@@ -0,0 +1,65 @@
+# ADR 0005: Mantel-Haenszel risk difference
+
+- Status: Accepted
+- Date: 2026-08-13
+- Supersedes: the RD exclusion from the Mantel-Haenszel scope in
+  [ADR 0002](0002-statistical-policy.md)
+
+## Context
+
+ADR 0002 limited Mantel-Haenszel pooling to common-effect odds ratios and risk
+ratios while the risk-difference estimator and its variance convention were
+still undecided. This left inverse variance as the only pooling method for RD,
+although conventional R implementations provide a common-effect MH RD.
+
+The point estimator is straightforward, but several variance estimators have
+appeared in the literature. The selected rule must work under both large-
+stratum and sparse-data limiting models, preserve treatment/control symmetry,
+and remain explicit in reports and cross-software validation.
+
+## Decision
+
+PyMetaAnalysis supports `measure="RD", method="MH", model="common"`. With
+treatment total `n1_i`, control total `n0_i`, total `N_i`, and
+`w_i = n1_i n0_i / N_i`, the estimate is:
+
+```text
+RD_i = a_i / n1_i - c_i / n0_i
+RD_MH = sum(w_i RD_i) / sum(w_i)
+```
+
+The normal confidence interval uses the Sato-Greenland-Robins sampling
+variance. The resolved method options record
+`mh_rd_variance="Sato-Greenland-Robins"`.
+
+Raw tables are used for MH pooling by default. `mh_continuity_correction` and
+`mh_correction_scope` remain the only settings that alter MH pooling tables;
+the separate study-effect correction continues to control displayed study
+uncertainty and the inverse-variance heterogeneity calculation. The existing
+`rd_zero_variance` policy determines whether boundary studies enter all
+synthesis calculations. A non-positive pooled Sato variance raises a domain
+error instead of silently adding a correction.
+
+Random-effects MH remains unsupported. Random-effects RD continues to use
+inverse-variance pooling with an explicit tau-squared estimator.
+
+## Validation
+
+- direct formula tests cover the estimate, Sato variance, weights, and normal
+  interval;
+- treatment/control swaps negate the estimate and mirror its interval without
+  changing the standard error;
+- row reordering and common count scaling preserve the expected invariants;
+- extreme finite counts exercise the overflow-safe scaled implementation;
+- boundary-policy, explicit-correction, subgroup, leave-one-out, and
+  cumulative paths are covered; and
+- fixed-version `metafor::rma.mh(measure="RD")` fixtures cover ordinary,
+  sparse, and explicitly corrected tables.
+
+## Consequences
+
+- common-effect OR, RR, and RD all support MH or inverse-variance pooling;
+- study-table MH weights for RD are proportional to `n1_i n0_i / N_i`;
+- the selected RD variance convention is recoverable from method metadata and
+  generated reports; and
+- documentation must continue to distinguish MH RD from random-effects IV RD.

pymetaanalysis-0.6.0/docs/adr/0006-peto-odds-ratio.md

@@ -0,0 +1,87 @@
+# ADR 0006: Peto one-step odds ratio
+
+- Status: Accepted
+- Date: 2026-08-13
+- Supersedes: the Peto deferral in
+  [ADR 0002](0002-statistical-policy.md)
+
+## Context
+
+Peto's one-step method is a conventional common-effect estimator for binary
+outcomes and is particularly associated with rare-event meta-analysis. It is
+not interchangeable with an ordinary inverse-variance odds ratio: it derives
+both the study contribution and pooled estimate from observed-minus-expected
+events and hypergeometric information.
+
+The approximation can be biased when treatment and control group sizes differ
+substantially within studies, effects are large, or events are not rare. Its
+zero-cell behavior also differs from ordinary log odds ratios, so pooling and
+display corrections must not be conflated.
+
+## Decision
+
+PyMetaAnalysis supports `measure="OR", method="Peto", model="common"` with
+`ci_method="normal"`. `"peto_one_step"` is an accepted alias and the resolved
+pooling method is `"peto"`.
+
+For stratum `i`, let `O_i = a_i`, `m_i = a_i + c_i`, treatment and control
+totals be `n1_i` and `n0_i`, and `N_i = n1_i + n0_i`. Define:
+
+```text
+E_i = m_i n1_i / N_i
+V_i = m_i (N_i - m_i) n1_i n0_i / (N_i^2 (N_i - 1))
+```
+
+The individual and pooled model-scale estimates are:
+
+```text
+y_i = (O_i - E_i) / V_i
+Var(y_i) = 1 / V_i
+y_Peto = sum(O_i - E_i) / sum(V_i)
+Var(y_Peto) = 1 / sum(V_i)
+```
+
+Pooling always uses raw 2-by-2 tables. The existing
+`continuity_correction` and `correction_scope` settings affect only displayed
+study estimates and variances; there is no Peto pooling correction parameter.
+Double-zero and double-all rows are excluded before every synthesis
+calculation because they contain no relative-effect information.
+
+Peto heterogeneity uses the fitted pooled coefficient and the same
+observed-minus-expected contributions:
+
+```text
+Q = sum(((O_i - E_i) - y_Peto V_i)^2 / V_i)
+```
+
+Q-based I-squared and H-squared follow the project's common-effect
+conventions. Method options record `peto_pooling_tables="raw"` and
+`peto_heterogeneity="O-minus-E"`. Every Peto result carries an approximation
+warning naming the rare-outcome, balanced-arm, and modest-effect conditions.
+
+Random-effects Peto and Peto RR/RD are unsupported. Users requesting those
+estimands must select an implemented inverse-variance or Mantel-Haenszel
+combination explicitly.
+
+## Validation
+
+- direct formula tests cover study estimates, pooled estimate, variance,
+  weights, confidence interval, and Peto Q;
+- treatment/control swapping reverses and exponentiates the log-OR limits as
+  expected, while row order leaves the fit unchanged;
+- count scaling and extreme finite-count tests exercise overflow-safe
+  arithmetic;
+- sparse tables verify that study-level correction does not alter raw Peto
+  pooling and that double-zero/double-all rows are excluded; and
+- fixed-version `metafor::escalc(measure="PETO")` and `metafor::rma.peto()`
+  fixtures cover ordinary and sparse datasets.
+
+## Consequences
+
+- common-effect binary OR now offers MH, Peto, and inverse-variance pooling;
+- Peto results remain on the log-OR model scale and use exponentiated display
+  values like other OR results;
+- sensitivity, subgroup, provenance, reporting, and plotting workflows reuse
+  the same public result contracts; and
+- documentation and reports must preserve the Peto applicability warning
+  rather than presenting it as a general sparse-data default.

{pymetaanalysis-0.4.0 → pymetaanalysis-0.6.0}/docs/development.md

@@ -11,7 +11,7 @@ cd PyMetaAnalysis
 python -m pip install -e ".[test,dev,docs,plot]"
 ```
 
-Use a supported Python version (3.10–3.13). Keep changes focused and preserve
+Use a supported Python version (3.10–3.14). Keep changes focused and preserve
 unrelated worktree modifications.
 
 ## Run checks
@@ -31,7 +31,7 @@ python -m build
 python tools/inspect_distribution.py dist
 ```
 
-The CI matrix also tests Python 3.10–3.13 and declared dependency lower bounds.
+The CI matrix also tests Python 3.10–3.14 and declared dependency lower bounds.
 Install the `notebook` extra before running the notebook executor.
 
 ## Statistical changes