PyMetaAnalysis 0.6.0__tar.gz → 0.8.0__tar.gz

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

@@ -6,6 +6,57 @@ Changes planned for the next release accumulate under `Unreleased`.
 
 ## Unreleased
 
+## 0.8.0 - 2026-09-04
+
+### Added
+
+- `MetaAnalysisResult.funnel()` supports optional contour-enhanced two-sided
+  significance regions with validated levels, display-scale null references,
+  configurable colors and legend, while preserving pooled pseudo-limit lines.
+- `MetaAnalysisResult.egger_test()` implements the classical standard-error
+  Egger regression test for funnel-plot asymmetry with multiplicative
+  dispersion, t inference, an explicitly labeled limit estimate, applicability
+  warnings, and an independent R `metafor` reference fixture.
+- `MetaAnalysisResult.harbord_test()` implements the Harbord efficient-score
+  test for two-group binary odds ratios, without continuity correction, with
+  multiplicative dispersion, t inference, and an independent R `meta`
+  reference fixture.
+- `MetaAnalysisResult.peters_test()` implements the Peters regression test for
+  two-group binary odds ratios, reusing the recorded study-level continuity
+  correction and validating the slope, limit estimate, and multiplicative
+  dispersion against an independent R `meta` reference fixture.
+
+## 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 +94,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 +137,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 +144,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 +155,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.8.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.8.0
+date-released: 2026-09-04
 repository-code: https://github.com/ZhaoboDing/PyMetaAnalysis
 url: https://zhaoboding.github.io/PyMetaAnalysis/
 license: MIT

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyMetaAnalysis
-Version: 0.6.0
+Version: 0.8.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
@@ -193,6 +195,9 @@ Rows excluded by missing-value or sparse-data policies remain in
 ```python
 leave_one_out = result.leave_one_out().to_dataframe()
 cumulative = result.cumulative(order="publication_year").to_dataframe()
+egger = result.egger_test()
+harbord = binary_or_result.harbord_test()
+peters = binary_or_result.peters_test()
 regression_deleted = regression.leave_one_out()
 regression_coefficient_changes = regression_deleted.coefficients
 regression_influence = regression.influence()
@@ -208,10 +213,16 @@ south_vs_east = regression.contrast(
 
 ax = result.forest(show_prediction_interval=True)
 ax = result.funnel()
+contour_ax = result.funnel(contour_levels=(0.90, 0.95, 0.99))
 ```
 
 Plotting methods return Matplotlib axes and never call `show()`. Funnel plots
-are descriptive small-study-effect diagnostics, not proof of publication bias.
+are descriptive small-study-effect diagnostics; optional significance contours
+show where two-sided p-value bands fall relative to the null. Classical Egger
+regression is available for general effects, while Harbord and Peters provide
+outcome-specific alternatives for two-group binary odds ratios. All include
+explicit applicability cautions. Neither a funnel plot nor any test proves
+publication bias.
 Meta-regression leave-one-out results also expose a long-form coefficient
 change table. Exact influence diagnostics add externally standardized
 residuals, Cook's distance, DFBETAS, and explicit heuristic screening
@@ -235,10 +246,10 @@ 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/)
+- [Sensitivity analysis](https://zhaoboding.github.io/PyMetaAnalysis/guides/sensitivity-analysis/), [small-study effects](https://zhaoboding.github.io/PyMetaAnalysis/guides/small-study-effects/), and [plotting](https://zhaoboding.github.io/PyMetaAnalysis/guides/plotting/)
 - [Public API](https://zhaoboding.github.io/PyMetaAnalysis/reference/api/), [result objects](https://zhaoboding.github.io/PyMetaAnalysis/reference/results/), and [report schema](https://zhaoboding.github.io/PyMetaAnalysis/reference/report-schema/)
 - [Validation strategy](https://zhaoboding.github.io/PyMetaAnalysis/validation/) and [scope/limitations](https://zhaoboding.github.io/PyMetaAnalysis/limitations/)
 - [Citation guidance](https://zhaoboding.github.io/PyMetaAnalysis/citation/)

{pymetaanalysis-0.6.0 → pymetaanalysis-0.8.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
@@ -143,6 +145,9 @@ Rows excluded by missing-value or sparse-data policies remain in
 ```python
 leave_one_out = result.leave_one_out().to_dataframe()
 cumulative = result.cumulative(order="publication_year").to_dataframe()
+egger = result.egger_test()
+harbord = binary_or_result.harbord_test()
+peters = binary_or_result.peters_test()
 regression_deleted = regression.leave_one_out()
 regression_coefficient_changes = regression_deleted.coefficients
 regression_influence = regression.influence()
@@ -158,10 +163,16 @@ south_vs_east = regression.contrast(
 
 ax = result.forest(show_prediction_interval=True)
 ax = result.funnel()
+contour_ax = result.funnel(contour_levels=(0.90, 0.95, 0.99))
 ```
 
 Plotting methods return Matplotlib axes and never call `show()`. Funnel plots
-are descriptive small-study-effect diagnostics, not proof of publication bias.
+are descriptive small-study-effect diagnostics; optional significance contours
+show where two-sided p-value bands fall relative to the null. Classical Egger
+regression is available for general effects, while Harbord and Peters provide
+outcome-specific alternatives for two-group binary odds ratios. All include
+explicit applicability cautions. Neither a funnel plot nor any test proves
+publication bias.
 Meta-regression leave-one-out results also expose a long-form coefficient
 change table. Exact influence diagnostics add externally standardized
 residuals, Cook's distance, DFBETAS, and explicit heuristic screening
@@ -185,10 +196,10 @@ 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/)
+- [Sensitivity analysis](https://zhaoboding.github.io/PyMetaAnalysis/guides/sensitivity-analysis/), [small-study effects](https://zhaoboding.github.io/PyMetaAnalysis/guides/small-study-effects/), and [plotting](https://zhaoboding.github.io/PyMetaAnalysis/guides/plotting/)
 - [Public API](https://zhaoboding.github.io/PyMetaAnalysis/reference/api/), [result objects](https://zhaoboding.github.io/PyMetaAnalysis/reference/results/), and [report schema](https://zhaoboding.github.io/PyMetaAnalysis/reference/report-schema/)
 - [Validation strategy](https://zhaoboding.github.io/PyMetaAnalysis/validation/) and [scope/limitations](https://zhaoboding.github.io/PyMetaAnalysis/limitations/)
 - [Citation guidance](https://zhaoboding.github.io/PyMetaAnalysis/citation/)

{pymetaanalysis-0.6.0 → pymetaanalysis-0.8.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.8.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.8.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.8.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.8.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
 
@@ -158,10 +160,34 @@ After installing the `plot` extra:
 ```python
 ax = result.forest(show_prediction_interval=True)
 ax = result.funnel()
+contour_ax = result.funnel(contour_levels=(0.90, 0.95, 0.99))
 ```
 
 Both methods return a Matplotlib `Axes` and never call `show()`. This keeps them
-usable in notebooks, scripts, tests, and composed figures.
+usable in notebooks, scripts, tests, and composed figures. Funnel contours show
+two-sided significance regions around the null effect; they do not estimate
+missing studies.
+
+The classical Egger regression test is available separately from plotting:
+
+```python
+egger = result.egger_test()
+print(egger)
+```
+
+It tests for funnel-plot asymmetry or small-study effects, not publication bias
+itself. Read [small-study effects](guides/small-study-effects.md) before using or
+interpreting it.
+
+For a two-group binary odds-ratio result, the outcome-specific Harbord and
+Peters tests are also available:
+
+```python
+harbord = binary_or_result.harbord_test()
+peters = binary_or_result.peters_test()
+```
+
+They require the retained event and group-size counts from `meta_binary()`.
 
 See [plotting](guides/plotting.md) for every parameter, display-scale rules,
 axes composition, and interpretation cautions.

{pymetaanalysis-0.6.0 → pymetaanalysis-0.8.0}/docs/guides/binary-outcomes.md

@@ -120,6 +120,27 @@ 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.
 
+## Harbord and Peters small-study-effect tests for odds ratios
+
+An OR result retains the original two-group counts needed for both
+outcome-specific regressions:
+
+```python
+harbord = odds_ratio_result.harbord_test()
+peters = odds_ratio_result.peters_test()
+print(harbord)
+print(peters)
+```
+
+Call these only when the result was fitted with `measure="OR"`. Harbord uses
+null efficient scores and no continuity correction; Peters reconstructs study
+log odds ratios with the recorded study-level correction. Both are independent
+of the source MH, IV, random-effects IV, or Peto pooling choice. They diagnose
+different forms of small-study association and do not prove publication bias
+or replace the pooled estimate. See
+[small-study effects](small-study-effects.md) for the complete method and
+interpretation contract.
+
 ## Input validation
 
 Event counts and sample sizes must be finite, integer-valued, and non-negative;

pymetaanalysis-0.8.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.8.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.8.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.8.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