PyMetaAnalysis 0.6.0__tar.gz → 0.7.0__tar.gz

{pymetaanalysis-0.6.0 → pymetaanalysis-0.7.0}/CHANGELOG.md

@@ -6,6 +6,37 @@ 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
@@ -43,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
@@ -71,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
@@ -81,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.
@@ -94,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.6.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.6.0
-date-released: 2026-08-13
+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.6.0 → pymetaanalysis-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyMetaAnalysis
-Version: 0.6.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
@@ -135,6 +135,7 @@ not individual-level or causal effects.
 | Effect + sampling variance or standard error | Generic | Common/random inverse variance |
 | 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,
@@ -182,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
@@ -235,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/)

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

@@ -85,6 +85,7 @@ not individual-level or causal effects.
 | Effect + sampling variance or standard error | Generic | Common/random inverse variance |
 | 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,
@@ -132,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
@@ -185,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/)

{pymetaanalysis-0.6.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.6.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.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.6.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.6.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.7.0/docs/guides/correlation-outcomes.md

@@ -0,0 +1,150 @@
+# Correlation outcomes
+
+Use `meta_correlation()` when each independent study contributes a Pearson
+correlation and its sample size. The first implementation deliberately
+supports only Fisher's z (`measure="ZCOR"`), the conventional
+variance-stabilizing route implemented by R `metafor::escalc(measure="ZCOR")`
+and `meta::metacor(sm="ZCOR")`.
+
+## DataFrame input
+
+```python
+import pandas as pd
+import meta_analyze as ma
+
+studies = pd.DataFrame(
+    {
+        "r": [0.18, 0.42, -0.05, 0.31, 0.27],
+        "sample_size": [84, 120, 63, 95, 150],
+    },
+    index=["Study A", "Study B", "Study C", "Study D", "Study E"],
+)
+
+result = ma.meta_correlation(
+    studies,
+    correlation="r",
+    n="sample_size",
+    model="random",
+    tau2_method="REML",
+)
+```
+
+Omitting `study=` uses the DataFrame index. Lists, NumPy arrays, and pandas
+Series are also accepted directly.
+
+## Model and display scales
+
+Each study is transformed before fitting:
+
+```text
+z_i = atanh(r_i)
+variance_i = 1 / (n_i - 3)
+```
+
+The model, confidence interval, prediction interval, tau-squared, and
+heterogeneity calculations remain on Fisher's z scale. This is explicit in
+the result:
+
+```python
+result.effect_scale  # "fisher_z"
+result.estimate  # pooled Fisher's z
+result.ci  # Fisher's z confidence interval
+```
+
+Use display properties for back-transformed correlations:
+
+```python
+result.display_scale  # "tanh"
+result.display_estimate
+result.display_ci
+result.display_prediction_interval
+```
+
+The pooled correlation is `tanh(pooled_z)`. It is not a direct weighted
+average of the raw correlations.
+
+## Input boundaries
+
+Included rows must satisfy:
+
+- a finite correlation strictly between -1 and 1;
+- a whole-number sample size of at least 4.
+
+Values at -1 or 1 would produce an infinite Fisher's z. A sample size no
+larger than 3 would make `1 / (n - 3)` non-positive or undefined. Both cases
+raise `InvalidStudyDataError` instead of being clipped or corrected.
+
+With `missing="drop"`, missing correlation or sample-size rows remain in
+`study_results` as explicit exclusions. Invalid non-missing values still
+raise an error.
+
+## Models and uncertainty
+
+The default is a random-effects inverse-variance model with REML. Common-
+effect pooling and the same random-effects choices as the generic API are
+available:
+
+```python
+common = ma.meta_correlation(
+    studies,
+    correlation="r",
+    n="sample_size",
+    model="common",
+)
+
+hk = ma.meta_correlation(
+    studies,
+    correlation="r",
+    n="sample_size",
+    model="random",
+    tau2_method="PM",
+    ci_method="hartung_knapp_adhoc",
+)
+```
+
+`tau2_method` supports REML, PM, and DL for random effects. Normal,
+Hartung-Knapp, prediction-interval, and Q-profile behavior follows the shared
+inverse-variance implementation and remains on the z scale until displayed.
+
+## Subgroups, sensitivity, reports, and plots
+
+The standard workflows are available without reconstructing effects by hand:
+
+```python
+studies = studies.assign(
+    population=["adult", "adult", "adult", "youth", "youth"],
+    publication_year=[2001, 2004, 2008, 2011, 2015],
+)
+
+subgroups = ma.meta_correlation(
+    studies,
+    correlation="r",
+    n="sample_size",
+    subgroup="population",
+)
+
+leave_one_out = result.leave_one_out().to_dataframe()
+cumulative = result.cumulative(order="publication_year").to_dataframe()
+methods = result.method_details()
+report = result.report().to_dict()
+forest_ax = result.forest()
+funnel_ax = result.funnel()
+```
+
+Forest and funnel x-coordinates are back-transformed correlations on a linear
+axis by default. Funnel standard errors remain model-scale Fisher's z standard
+errors.
+
+## Independence boundary
+
+This API assumes one independent effect per study. Repeated outcomes,
+different variable pairs, or multiple time points from the same participants
+are statistically dependent even if their rows have different labels.
+PyMetaAnalysis does not currently estimate the covariance matrix or fit a
+multilevel/multivariate model for those data. Select one prespecified effect,
+combine effects using an appropriate external method, or use software that
+models dependence explicitly.
+
+The first release also does not support raw-correlation pooling (`COR`),
+partial correlations, rank correlations, or reliability corrections. Passing
+`measure="COR"` raises `UnsupportedMethodError`.

{pymetaanalysis-0.6.0 → pymetaanalysis-0.7.0}/docs/guides/input-data.md

@@ -2,7 +2,7 @@
 
 Every analysis entry point accepts either DataFrame column names or
 one-dimensional array-like values. This page describes rules shared by the
-generic, binary, and continuous APIs.
+generic, binary, continuous, and correlation APIs.
 
 ## DataFrame columns
 
@@ -105,8 +105,9 @@ silently assigning or dropping them would change the subgroup definition.
 | 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 |
+| Correlation | finite `-1 < correlation < 1`; integer sample size `n >= 4` |
 
-Binary and continuous APIs preserve their raw input columns in
+Binary, continuous, and correlation APIs preserve their raw input columns in
 `study_results`. Derived effects, variances, correction indicators, and
 weights appear alongside them.
 

{pymetaanalysis-0.6.0 → pymetaanalysis-0.7.0}/docs/guides/meta-regression.md

@@ -67,10 +67,11 @@ 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.
-Categorical matching preserves scalar kinds: Python and NumPy integers are
-equivalent, for example, but booleans do not match integer levels and
-floating-point values do not match integer levels. Declare levels using the
-same scalar kind as the observed moderator values.
+Categorical matching keeps booleans distinct from numeric levels. Python and
+NumPy integers are equivalent, and integer-valued floats such as `1.0` match
+the corresponding integer level `1`. This accommodates pandas integer columns
+that become floating point after introducing a missing value. Non-integer
+floats such as `1.5` do not match integer levels.
 
 Formula parsing, automatic interactions, splines, and polynomial terms are not
 implemented. Construct those columns explicitly before fitting when they are

{pymetaanalysis-0.6.0 → pymetaanalysis-0.7.0}/docs/guides/method-selection.md

@@ -23,6 +23,7 @@ The high-level APIs intentionally have outcome-specific defaults:
 | --- | --- |
 | `meta_analysis()` | random-effects inverse variance, REML |
 | `meta_continuous()` | random-effects inverse variance, REML |
+| `meta_correlation()` | random-effects inverse variance, REML |
 | `meta_binary()` | common-effect Mantel-Haenszel |
 | `meta_regression()` | mixed-effects inverse variance, REML |
 
@@ -40,6 +41,7 @@ protocols.
 | Binary RR/RD, common effect | Mantel-Haenszel or inverse variance |
 | Binary OR/RR/RD, random effects | Inverse variance |
 | Continuous MD/SMD, common or random | Inverse variance |
+| Fisher's z correlation, common or random | Inverse variance |
 
 Mantel-Haenszel and inverse variance are different estimators, not aliases.
 PyMetaAnalysis does not extrapolate its common-effect Mantel-Haenszel weights

{pymetaanalysis-0.6.0 → pymetaanalysis-0.7.0}/docs/guides/plotting.md

@@ -50,7 +50,9 @@ fig.tight_layout()
 | `log_scale` | Override the default logarithmic ratio axis |
 
 OR and RR are modeled on a log scale but displayed as ratios on a logarithmic
-axis by default. Other measures use an identity display scale and linear axis.
+axis by default. `ZCOR` is modeled on Fisher's z scale, back-transformed to
+correlations, and displayed on a linear axis. Other measures use an identity
+display scale and linear axis.
 When overriding `log_scale=True`, all displayed effects and the null value must
 be strictly positive.
 

{pymetaanalysis-0.6.0 → pymetaanalysis-0.7.0}/docs/guides/r-interoperability.md

@@ -18,6 +18,7 @@ fixtures used by this project.
 | Binary 2x2 tables, Mantel-Haenszel | `meta_binary(..., method="MH")` | `rma.mh()` | `metabin(..., method="MH")` |
 | Binary 2x2 tables, Peto OR | `meta_binary(..., measure="OR", method="Peto")` | `rma.peto()` | `metabin(..., sm="OR", method="Peto")` |
 | Continuous group summaries | `meta_continuous()` | `escalc()` then `rma.uni()` | `metacont()` |
+| Correlations and sample sizes | `meta_correlation()` | `escalc(measure="ZCOR")` then `rma.uni()` | `metacor(sm="ZCOR")` |
 | Subgroups | `subgroup=` on a high-level call | separate fits or a moderator model | `subgroup=` |
 | Leave-one-out | `result.leave_one_out()` | `leave1out()` for supported fits | `metainf()` |
 | Meta-regression influence | `regression.influence()` | `influence()`, `rstudent()`, `cooks.distance()`, `dfbetas()` | — |
@@ -42,6 +43,7 @@ provenance behavior consistent.
 | Control total | `n_control` | `n2i` | `n.c` |
 | Treatment mean/SD | `mean_treat`, `sd_treat` | `m1i`, `sd1i` | `mean.e`, `sd.e` |
 | Control mean/SD | `mean_control`, `sd_control` | `m2i`, `sd2i` | `mean.c`, `sd.c` |
+| Correlation/sample size | `correlation`, `n` | `ri`, `ni` | `cor`, `n` |
 
 PyMetaAnalysis accepts DataFrame column names or aligned one-dimensional
 array-like values. When `study=` is omitted for a DataFrame, its index supplies
@@ -56,11 +58,14 @@ the display labels.
 | `"RD"` | Risk difference | `"RD"` | `"RD"` | identity |
 | `"MD"` | Mean difference | `"MD"` | `"MD"` | identity |
 | `"SMD"` | Exact-corrected Hedges' g | `"SMD"` with the documented correction | `"SMD"` with exact Hedges correction | identity |
+| `"ZCOR"` | Fisher's z-transformed correlation | `"ZCOR"` | `"ZCOR"` | Fisher's z |
 
-For OR and RR, `estimate` and `ci` remain on the log model scale.
-`display_estimate` and `display_ci` provide exponentiated ratios. This is
-similar to choosing transformed or untransformed printing in R, but both scales
-remain explicit attributes in Python.
+For OR and RR, `estimate` and `ci` remain on the log model scale;
+`display_estimate` and `display_ci` provide exponentiated ratios. For `ZCOR`,
+the model attributes remain Fisher's z values and the display attributes apply
+`tanh` to return correlations. This is similar to choosing transformed or
+untransformed printing in R, but both scales remain explicit attributes in
+Python.
 
 ## Models, pooling, and heterogeneity
 
@@ -68,7 +73,7 @@ remain explicit attributes in Python.
 | --- | --- | --- | --- |
 | `model="common"` | `rma.uni(..., method="EE")` | `common=TRUE, random=FALSE` | Inverse-variance common-effect fit |
 | `model="random"` | random-effects `rma.uni()` | `random=TRUE` | Requires a tau-squared policy |
-| `method="IV"` | inverse-variance weighting | `method="Inverse"` | Binary API only; generic and continuous fits are IV |
+| `method="IV"` | inverse-variance weighting | `method="Inverse"` | Binary API only; generic, continuous, and correlation fits are IV |
 | `method="MH"` | `rma.mh()` | `method="MH"` | Common-effect OR/RR/RD |
 | `method="Peto"` | `rma.peto()` | `method="Peto"` | Common-effect OR; raw pooling tables and O-minus-E heterogeneity |
 | `tau2_method=None` (resolved as `"REML"`) | `method="REML"` | `method.tau="REML"` | PyMetaAnalysis random-effects default |
@@ -217,3 +222,4 @@ as numerically equivalent.
 - [`meta::metagen`](https://search.r-project.org/CRAN/refmans/meta/html/metagen.html)
 - [`meta::metabin`](https://search.r-project.org/CRAN/refmans/meta/html/metabin.html)
 - [`meta::metacont`](https://search.r-project.org/CRAN/refmans/meta/html/metacont.html)
+- [`meta::metacor`](https://search.r-project.org/CRAN/refmans/meta/html/metacor.html)

{pymetaanalysis-0.6.0 → pymetaanalysis-0.7.0}/docs/guides/sensitivity-analysis.md

@@ -164,8 +164,8 @@ Every refit reuses the original result's:
 - tau-squared and confidence-interval methods;
 - confidence level, absolute tolerance, and iteration limit;
 - missing-data policy;
-- binary continuity corrections and RD zero-variance policy, or the continuous
-  effect-size convention.
+- binary continuity corrections and RD zero-variance policy, the continuous
+  effect-size convention, or the Fisher's z correlation convention.
 
 Meta-regression refits additionally reuse the intercept choice, inference
 method, moderator order, and complete explicit categorical level definitions.

{pymetaanalysis-0.6.0 → pymetaanalysis-0.7.0}/docs/guides/zero-events.md

@@ -76,20 +76,25 @@ default:
 
 ```python
 mh_continuity_correction = None
-mh_correction_scope = "only_zero_studies"
+mh_correction_scope = None  # resolves to "only_zero_studies" for MH
 ```
 
 `continuity_correction` still controls the study-level effects used for display
 and heterogeneity. It does not silently alter the pooled Mantel-Haenszel
 estimator. If an exact pooled estimator is undefined, choose an explicit
 positive `mh_continuity_correction` and report that decision.
+Both MH-specific options are rejected when explicitly supplied to IV or Peto
+pooling, where they would otherwise have no effect.
 
 For MH RD, `rd_zero_variance="exclude"` removes zero-variance boundary rows
 before every synthesis calculation. With the default `"correct"` policy, the
 raw table still enters the MH point estimate unless an explicit
 `mh_continuity_correction` is supplied. If the Sato-Greenland-Robins variance
 is non-positive, the uncorrected fit raises instead of silently changing the
-tables; a positive MH correction is an explicit protocol choice.
+tables; a positive MH correction is an explicit protocol choice. Some other
+implementations, including `metafor`, can report a degenerate zero or near-zero
+standard error for such boundary data. PyMetaAnalysis rejects that result by
+the policy recorded in ADR 0005.
 
 ## Peto pooling always uses raw tables
 
@@ -103,6 +108,10 @@ pooling-correction option.
 Double-zero and double-all studies have zero Peto information and are excluded
 before pooling, Q, I-squared, H-squared, and weights. The result retains the
 same structured exclusion reasons used for other relative-effect analyses.
+This means `fit_peto()` expects already-filtered tables. It also differs from
+the pooling side of `metafor::rma.peto()` under its default `drop00` handling,
+which can retain zero-information rows when calculating `k` and Q degrees of
+freedom even though those rows contribute no Peto information.
 Peto's lack of a single-zero pooling correction does not make it universally
 preferable: its rare-outcome, balanced-arm, and modest-effect assumptions must
 still be considered.
@@ -123,10 +132,10 @@ columns = [
 result.study_results[columns]
 ```
 
-Resolved correction values and scopes also appear in
-`dict(result.method.options)`. RD analyses additionally record the resolved
-zero-variance policy and affected row IDs in provenance. This makes it possible
-to distinguish a corrected analysis from an exact or exclusion-based one after
-fitting.
+Applicable resolved correction values and scopes also appear in
+`dict(result.method.options)`. MH-specific keys are present only for MH fits.
+RD analyses additionally record the resolved zero-variance policy and affected
+row IDs in provenance. This makes it possible to distinguish a corrected
+analysis from an exact or exclusion-based one after fitting.
 Peto analyses additionally record `peto_pooling_tables="raw"` and
 `peto_heterogeneity="O-minus-E"`.