PyMetaAnalysis 0.5.0__tar.gz → 0.7.0__tar.gz

{pymetaanalysis-0.5.0 → pymetaanalysis-0.7.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.5.0 → pymetaanalysis-0.7.0}/CHANGELOG.md

@@ -6,6 +6,54 @@ Changes planned for the next release accumulate under `Unreleased`.
 
 ## Unreleased
 
+## 0.7.0 - 2026-09-02
+
+### Added
+
+- `meta_correlation()` for independent study-level correlations using Fisher's
+  r-to-z transformation (`ZCOR`), `1 / (n - 3)` sampling variances, common- or
+  REML/PM/DL random-effects inverse-variance pooling, back-transformed result
+  displays, subgroup and sensitivity workflows, plotting, provenance, reports,
+  and independent R `metafor` references.
+
+### Changed
+
+- integer-valued floating-point categorical moderators now match declared
+  integer levels while booleans remain distinct, supporting pandas columns
+  promoted to floating point by missing values;
+- MH pooling corrections now use `None` as the context-sensitive scope default;
+  explicitly supplying either MH-only option to IV or Peto pooling raises an
+  error, and non-MH method metadata no longer records unused MH settings;
+- estimator documentation now makes the pooled-mean-only Q-profile contract,
+  the prefiltered `fit_peto()` input contract, and sparse MH RD boundary policy
+  explicit;
+- fixed-version `metafor` references now cover a two-study Hartung-Knapp
+  interval and Q-profile intervals reached through random-effects subgroups.
+
+### Fixed
+
+- normal-inference subgroup tests reuse each fitted standard error directly,
+  avoiding an unnecessary recomputation and last-bit numerical drift.
+- Peto observed-minus-expected arithmetic now uses a treatment/control-symmetric
+  formulation, preventing avoidable last-bit drift for highly imbalanced arms.
+
+## 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
@@ -26,6 +74,21 @@ Changes planned for the next release accumulate under `Unreleased`.
   Mantel-Haenszel pooling correction; iterative failure paths have direct
   regression tests.
 
+### Breaking changes
+
+- explicitly supplying `tau2_method` to a common-effect model, including the
+  former default spelling `"REML"`, now raises an error instead of being
+  ignored; explicitly inapplicable SMD variance settings follow the same rule;
+- cumulative analysis now rejects a string `order` selector when the name is
+  present in both source data and the calculated study table, instead of
+  silently preferring the source-data column;
+- `LeaveOneOutResult.results` now preserves failed refits as `None`, and its
+  table adds `refit_success`, `error_type`, and `error_message` columns;
+- pooled-result `prediction_interval_method` metadata now uses `null` when an
+  interval is unavailable and `"HK-PR"` for Hartung-Knapp intervals. Report
+  schema 1.2 remains unchanged because the field itself was already present;
+  consumers must handle the documented value set.
+
 ### Fixed
 
 - inverse-variance means, heterogeneity statistics, and pooling and
@@ -54,9 +117,6 @@ Changes planned for the next release accumulate under `Unreleased`.
   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
@@ -64,8 +124,6 @@ Changes planned for the next release accumulate under `Unreleased`.
 - 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.
@@ -77,8 +135,6 @@ Changes planned for the next release accumulate under `Unreleased`.
   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,

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyMetaAnalysis
-Version: 0.5.0
+Version: 0.7.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
@@ -133,8 +133,9 @@ 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 |
+| Correlations + sample sizes | Fisher's z (`ZCOR`) | Common/random inverse variance |
 | Effect + variance/SE + moderators | Generic | Common/mixed Meta-regression |
 
 Random-effects inverse-variance models support REML (default), Paule-Mandel,
@@ -153,6 +154,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
 
@@ -176,7 +183,8 @@ markdown = report.to_markdown()
 
 OR and RR remain on the log model scale in auditable numeric attributes;
 `display_estimate`, `display_ci`, and `display_prediction_interval` provide
-exponentiated ratios.
+exponentiated ratios. `ZCOR` results similarly retain Fisher's z internally
+and expose back-transformed correlations through the display properties.
 
 Rows excluded by missing-value or sparse-data policies remain in
 `study_results` with a stable `row_id`, `included=False`, and an
@@ -229,7 +237,7 @@ The complete documentation is published at
 - [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
+- [Generic](https://zhaoboding.github.io/PyMetaAnalysis/guides/generic-effects/), [binary](https://zhaoboding.github.io/PyMetaAnalysis/guides/binary-outcomes/), [continuous](https://zhaoboding.github.io/PyMetaAnalysis/guides/continuous-outcomes/), and [correlation](https://zhaoboding.github.io/PyMetaAnalysis/guides/correlation-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/)
@@ -252,7 +260,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.5.0 → pymetaanalysis-0.7.0}/README.md

@@ -83,8 +83,9 @@ 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 |
+| Correlations + sample sizes | Fisher's z (`ZCOR`) | Common/random inverse variance |
 | Effect + variance/SE + moderators | Generic | Common/mixed Meta-regression |
 
 Random-effects inverse-variance models support REML (default), Paule-Mandel,
@@ -103,6 +104,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
 
@@ -126,7 +133,8 @@ markdown = report.to_markdown()
 
 OR and RR remain on the log model scale in auditable numeric attributes;
 `display_estimate`, `display_ci`, and `display_prediction_interval` provide
-exponentiated ratios.
+exponentiated ratios. `ZCOR` results similarly retain Fisher's z internally
+and expose back-transformed correlations through the display properties.
 
 Rows excluded by missing-value or sparse-data policies remain in
 `study_results` with a stable `row_id`, `included=False`, and an
@@ -179,7 +187,7 @@ The complete documentation is published at
 - [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
+- [Generic](https://zhaoboding.github.io/PyMetaAnalysis/guides/generic-effects/), [binary](https://zhaoboding.github.io/PyMetaAnalysis/guides/binary-outcomes/), [continuous](https://zhaoboding.github.io/PyMetaAnalysis/guides/continuous-outcomes/), and [correlation](https://zhaoboding.github.io/PyMetaAnalysis/guides/correlation-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/)
@@ -202,7 +210,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.5.0 → pymetaanalysis-0.7.0}/benchmarks/README.md

@@ -1,10 +1,10 @@
 # Core performance baseline
 
-`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.
+`benchmark_core.py` measures representative generic, binary, continuous,
+correlation, 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.5.0 → pymetaanalysis-0.7.0}/benchmarks/benchmark_core.py

@@ -48,6 +48,8 @@ def _cases(studies: int) -> dict[str, Callable[[], object]]:
     mean_treat = mean_control + rng.normal(0.25, 0.18, size=studies)
     sd_treat = rng.uniform(0.7, 1.6, size=studies)
     sd_control = rng.uniform(0.7, 1.6, size=studies)
+    correlation = rng.uniform(-0.65, 0.65, size=studies)
+    correlation_n = rng.integers(20, 300, size=studies)
 
     return {
         "generic_random_reml": lambda: ma.meta_analysis(
@@ -77,6 +79,12 @@ def _cases(studies: int) -> dict[str, Callable[[], object]]:
             model="random",
             tau2_method="REML",
         ),
+        "correlation_random_reml": lambda: ma.meta_correlation(
+            correlation=correlation,
+            n=correlation_n,
+            model="random",
+            tau2_method="REML",
+        ),
         "meta_regression_multivariable_reml": lambda: ma.meta_regression(
             effect=generic_effect,
             variance=generic_variance,

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

@@ -4,6 +4,10 @@
 - 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
 
@@ -44,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:
 

pymetaanalysis-0.7.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.7.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.7.0/docs/adr/0007-fisher-z-correlation.md

@@ -0,0 +1,66 @@
+# ADR 0007: Fisher's z correlation pooling
+
+- Status: Accepted
+- Date: 2026-09-02
+
+## Context
+
+Study-level correlations are common in behavioral, educational, and medical
+research. Directly pooling raw correlations is possible but their sampling
+distribution is bounded, asymmetric away from zero, and has a variance that
+depends on the underlying correlation. Fisher's r-to-z transformation is the
+standard first implementation in R `meta` and `metafor` and composes with the
+library's existing inverse-variance machinery.
+
+The API also needs an explicit position on perfect correlations, very small
+samples, displayed values, and multiple correlations drawn from the same
+participants.
+
+## Decision
+
+`meta_correlation()` accepts raw `correlation` and sample size `n`, but its
+first supported measure is only `ZCOR`:
+
+```text
+y_i = atanh(r_i)
+v_i = 1 / (n_i - 3)
+```
+
+All fitting and heterogeneity calculations use Fisher's z. Result display
+properties and plots use `tanh` to return the correlation scale. The result
+records `effect_scale="fisher_z"`, `display_scale="tanh"`, the transformation,
+variance equation, affected rows, and input sources.
+
+Included correlations must be finite and strictly between -1 and 1. Sample
+sizes must be whole numbers of at least 4. The implementation does not clip
+perfect correlations or replace invalid sample sizes because either action
+would introduce an undocumented effect or variance.
+
+The default is the library's random-effects inverse-variance policy: REML
+tau-squared and a normal confidence interval. Common effects, PM/DL, the two
+documented Hartung-Knapp options, shared prediction intervals, Q-profile
+heterogeneity intervals, subgroups, repeated-fit sensitivity, reports, and
+plots reuse their existing contracts.
+
+Rows are assumed independent. Duplicate labels remain allowed and warned, but
+do not imply a dependence correction. Raw-correlation pooling (`COR`),
+dependent correlations, partial/rank correlations, and reliability
+corrections are deferred.
+
+## Validation
+
+Committed fixtures generated by `metafor::escalc(measure="ZCOR")` and
+`rma.uni()` validate study effects, variances, common-effect and REML fits,
+weights, and back-transformation. Targeted and property-based tests cover
+domain boundaries, missing rows, sign symmetry, row-order invariance,
+subgroups, sensitivity refits, reports, and Matplotlib coordinates.
+
+## Consequences
+
+- users can supply pandas columns without calculating z values or variances;
+- model-scale and correlation-scale results remain distinguishable;
+- behavior matches a documented R workflow without importing R at runtime;
+- perfect correlations and samples smaller than four require an upstream,
+  scientifically justified decision rather than silent repair;
+- users with dependent correlations must use a method outside the current
+  univariate scope.

{pymetaanalysis-0.5.0 → pymetaanalysis-0.7.0}/docs/citation.md

@@ -19,7 +19,7 @@ print(ma.__version__)
 A provisional citation can use:
 
 ```text
-PyMetaAnalysis contributors. PyMetaAnalysis (version <version>):
+Zhaobo Ding. PyMetaAnalysis (version <version>):
 a pandas-first meta-analysis library for Python.
 https://github.com/ZhaoboDing/PyMetaAnalysis
 ```

{pymetaanalysis-0.5.0 → pymetaanalysis-0.7.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

{pymetaanalysis-0.5.0 → pymetaanalysis-0.7.0}/docs/getting-started.md

@@ -120,8 +120,9 @@ schema, strict JSON behavior, and subgroup reports.
 ## 6. Understand model and display scales
 
 Generic effects, MD, SMD, and RD use the identity scale. OR and RR are modeled
-on a log scale, so their audit-friendly numeric attributes remain logarithmic.
-Use display properties for ratios:
+on a log scale, while `ZCOR` is modeled on Fisher's z scale. Their audit-
+friendly numeric attributes remain on those model scales. Use display
+properties for ratios and back-transformed correlations:
 
 ```python
 result.display_estimate
@@ -130,7 +131,8 @@ result.display_prediction_interval
 ```
 
 The [binary-outcome guide](guides/binary-outcomes.md) includes a complete ratio
-example.
+example; the [correlation guide](guides/correlation-outcomes.md) explains the
+Fisher transformation.
 
 ## 7. Check sensitivity
 

{pymetaanalysis-0.5.0 → pymetaanalysis-0.7.0}/docs/guides/binary-outcomes.md

@@ -35,8 +35,33 @@ result = ma.meta_binary(
 print(result.summary())
 ```
 
-Mantel-Haenszel pooling currently supports OR and RR with `model="common"` and
-`ci_method="normal"`.
+Mantel-Haenszel pooling supports OR, RR, and RD with `model="common"` and
+`ci_method="normal"`. MH risk differences use the Sato-Greenland-Robins
+sampling variance, recorded in `dict(result.method.options)`.
+
+## Peto common-effect odds ratio
+
+Peto's one-step estimator is an explicit alternative for common-effect OR:
+
+```python
+peto = ma.meta_binary(
+    studies,
+    event_treat="events_t",
+    n_treat="total_t",
+    event_control="events_c",
+    n_control="total_c",
+    measure="OR",
+    method="Peto",
+    model="common",
+)
+```
+
+Peto pooling uses the raw 2-by-2 tables and its own observed-minus-expected
+heterogeneity statistic. The study table contains Peto one-step effects;
+`continuity_correction` affects those displayed study effects but not the
+pooled result. Peto is intended for rare outcomes when treatment/control arm
+sizes are similar within studies and effects are not large. The result always
+retains this caveat in `warnings` and Methods text.
 
 ## Random-effects analysis
 
@@ -71,7 +96,8 @@ them to the generic inverse-variance model.
 For OR and RR, `result.estimate` and `result.ci` stay on the log model scale.
 Use `display_estimate` and `display_ci` for exponentiated ratios.
 
-RD is available through inverse-variance pooling:
+For a common-effect RD, choose either MH or inverse-variance pooling explicitly.
+The MH form is:
 
 ```python
 result = ma.meta_binary(
@@ -81,7 +107,7 @@ result = ma.meta_binary(
     event_control="events_c",
     n_control="total_c",
     measure="RD",
-    method="IV",
+    method="MH",
     model="common",
     rd_zero_variance="correct",
 )
@@ -91,6 +117,8 @@ result = ma.meta_binary(
 their raw RD and uses corrected counts only for sampling variance. Use
 `"exclude"` for a protocol that excludes these studies before all synthesis
 calculations. See [zero-event studies](zero-events.md) for details.
+Use `method="IV"` for random-effects RD or when inverse-variance common-effect
+pooling is the prespecified estimator.
 
 ## Input validation
 
@@ -104,5 +132,5 @@ Sparse tables require additional decisions. Read
 settings.
 
 See [statistical methods](../methods/statistical-methods.md#binary-study-effects)
-for the OR/RR/RD and Mantel-Haenszel equations, and
+for the OR/RR/RD, Mantel-Haenszel, and Peto equations, and
 [validation](../validation.md) for cross-software coverage.