PyMetaAnalysis 0.7.0__tar.gz → 0.8.0__tar.gz

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

@@ -6,6 +6,26 @@ 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

{pymetaanalysis-0.7.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.7.0
-date-released: 2026-09-02
+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.7.0 → pymetaanalysis-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyMetaAnalysis
-Version: 0.7.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
@@ -195,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()
@@ -210,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
@@ -240,7 +249,7 @@ The complete documentation is published at
 - [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.7.0 → pymetaanalysis-0.8.0}/README.md

@@ -145,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()
@@ -160,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
@@ -190,7 +199,7 @@ The complete documentation is published at
 - [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.7.0 → pymetaanalysis-0.8.0}/docs/getting-started.md

@@ -160,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.7.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.7.0 → pymetaanalysis-0.8.0}/docs/guides/plotting.md

@@ -83,6 +83,22 @@ appear toward the top. The vertical reference is the fitted pooled estimate.
 Pseudo confidence limits are centered on that estimate and do not include
 tau-squared.
 
+Add two-sided significance contours around the null effect with:
+
+```python
+ax = result.funnel(
+    contour_levels=(0.90, 0.95, 0.99),
+)
+```
+
+These confidence levels define the visible bands `0.05 < p <= 0.10`,
+`0.01 < p <= 0.05`, and `p <= 0.01`; the central `p > 0.10` region remains
+unshaded. The solid vertical line remains the fitted pooled estimate, while a
+dotted line marks the null used for the contours. When contours are enabled,
+their background replaces the ordinary blue pseudo-limit fill so the colors
+do not mix. The pseudo-limit boundary lines are still drawn unless
+`show_pseudo_confidence_interval=False`.
+
 ### Funnel parameters
 
 | Parameter | Meaning |
@@ -90,14 +106,41 @@ tau-squared.
 | `ax` | Existing axes; a new one is created when omitted |
 | `effect_label` | X-axis label |
 | `confidence_level` | Pseudo-limit level; defaults to the fitted level |
-| `show_pseudo_confidence_interval` | Draw the shaded pseudo-limit region |
+| `show_pseudo_confidence_interval` | Draw pooled pseudo-limit boundaries and, without contours, their shaded region |
+| `contour_levels` | Strictly increasing confidence levels in `(0,1)`; `None` disables contours |
+| `contour_colors` | One valid Matplotlib color per contour level; defaults to light-to-dark gray |
+| `contour_reference` | Contour null on the display scale; defaults to 1 for ratios and 0 otherwise |
+| `show_contour_legend` | Show the corresponding two-sided p-value bands |
 | `warn_on_few_studies` | Warn when fewer than 10 studies are plotted |
 | `log_scale` | Override the default logarithmic ratio axis |
 
+For example, customize the bands and null reference with:
+
+```python
+ax = result.funnel(
+    contour_levels=(0.90, 0.95),
+    contour_colors=("#fee2e2", "#ef4444"),
+    contour_reference=0.0,
+    show_contour_legend=True,
+)
+```
+
+`contour_reference` uses the displayed effect scale. It must therefore be
+positive for OR/RR results, whose default is `1`, and strictly between `-1`
+and `1` for displayed correlations. Boundaries are calculated on the model
+scale before the normal display transformation. Contours are always based on
+sampling standard errors and do not incorporate tau-squared.
+
 Funnel asymmetry can reflect small-study effects, heterogeneity, outcome
 selection, design differences, chance, or publication processes. It is not by
-itself evidence of publication bias. PyMetaAnalysis currently provides the
-plot but not formal asymmetry tests.
+itself evidence of publication bias. Contours help assess whether apparent
+missing areas are predominantly statistically non-significant, but they do not
+show that studies are actually missing or determine why asymmetry exists. Use
+the separately documented classical
+[`result.egger_test()`](small-study-effects.md), or `result.harbord_test()` /
+`result.peters_test()` for an eligible binary OR analysis, when a formal
+regression diagnostic is appropriate. None changes the plot or proves a
+publication mechanism.
 
 ## Meta-regression bubble plots
 

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

@@ -25,6 +25,10 @@ fixtures used by this project.
 | Meta-regression collinearity | `regression.collinearity()` | `vif()` plus weighted design diagnostics | — |
 | Meta-regression linear contrasts | `regression.contrast(...)` | `anova(..., X=..., rhs=...)` | — |
 | Cumulative analysis | `result.cumulative()` | `cumul()` | `metacum()` |
+| Contour-enhanced funnel plot | `result.funnel(contour_levels=(...))` | `funnel(level=c(...), refline=...)` | `funnel(contour.levels=c(...), ref=...)` |
+| Classical Egger test | `result.egger_test()` | `regtest(..., model="lm", predictor="sei")` | `metabias(..., method.bias="Egger")` |
+| Harbord binary-OR test | `result.harbord_test()` | manual documented score regression | `metabias(..., method.bias="Harbord")` |
+| Peters binary-OR test | `result.peters_test()` | manual documented WLS | `metabias(..., method.bias="Peters")` |
 
 PyMetaAnalysis intentionally has no `metabin`, `metacont`, or `rma` aliases.
 One documented Python entry point per input shape keeps result types and
@@ -212,6 +216,66 @@ metagen(
 Check the R package's explicit ad hoc HK option before treating the last call
 as numerically equivalent.
 
+## Classical Egger regression
+
+```python
+egger = result.egger_test()
+```
+
+corresponds to the classical `metafor` configuration:
+
+```r
+regtest(fit, model = "lm", predictor = "sei")
+```
+
+PyMetaAnalysis does not currently expose `metafor`'s default
+`model="rma"` version. The returned `intercept` is the tested asymmetry
+coefficient, while `limit_estimate` is the extrapolated effect as the standard
+error tends to zero. Review the dedicated
+[small-study-effects guide](small-study-effects.md) before treating similarly
+named R functions as numerically interchangeable.
+
+## Harbord regression for binary odds ratios
+
+```python
+harbord = binary_or_result.harbord_test()
+```
+
+corresponds to:
+
+```r
+metabias(binary_or_fit, method.bias = "Harbord")
+```
+
+PyMetaAnalysis calculates the null efficient score `Z` and score variance `V`
+directly from retained treatment/control counts. It fits the standardized form
+`Z/sqrt(V)` on `sqrt(V)`, which is algebraically equivalent to the
+`V`-weighted `Z/V` on `1/sqrt(V)` regression used by R `meta`. The intercept is
+the tested asymmetry coefficient, with multiplicative dispersion and
+`t_(k-2)` inference. Study-level continuity corrections and the source pooling
+method do not enter the score calculation.
+
+## Peters regression for binary odds ratios
+
+```python
+peters = binary_or_result.peters_test()
+```
+
+corresponds to:
+
+```r
+metabias(binary_or_fit, method.bias = "Peters")
+```
+
+PyMetaAnalysis requires an OR result created by `meta_binary()` because Peters
+regression needs the original treatment/control counts. It reconstructs
+conventional continuity-corrected study log odds ratios, uses inverse total
+sample size as predictor and `S*F/N` weights, and applies multiplicative
+dispersion with `t_(k-2)` inference. `slope` is the tested coefficient;
+`limit_estimate` is the extrapolated log OR at infinite total sample size.
+The source common/random and MH/IV/Peto pooling choice does not enter this
+separate regression.
+
 ## Primary R references
 
 - [`metafor::rma.uni`](https://wviechtb.github.io/metafor/reference/rma.uni.html)
@@ -219,7 +283,9 @@ as numerically equivalent.
 - [`metafor::rma.mh`](https://wviechtb.github.io/metafor/reference/rma.mh.html)
 - [`metafor::rma.peto`](https://wviechtb.github.io/metafor/reference/rma.peto.html)
 - [`metafor::escalc`](https://wviechtb.github.io/metafor/reference/escalc.html)
+- [`metafor::regtest`](https://wviechtb.github.io/metafor/reference/regtest.html)
 - [`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)
+- [`meta::metabias`](https://search.r-project.org/CRAN/refmans/meta/html/metabias.html)

pymetaanalysis-0.8.0/docs/guides/small-study-effects.md

@@ -0,0 +1,257 @@
+# Small-study effects and regression tests
+
+PyMetaAnalysis provides classical Egger regression plus Harbord and Peters
+tests for two-group binary odds ratios as companions to the descriptive funnel
+plot. They diagnose funnel-plot asymmetry or small-study effects; none is a
+direct test for publication bias.
+
+## Run the classical Egger test
+
+Start from any fitted `MetaAnalysisResult`:
+
+```python
+import meta_analyze as ma
+
+result = ma.meta_analysis(
+    studies,
+    effect="effect",
+    standard_error="standard_error",
+    model="random",
+)
+
+egger = result.egger_test()
+print(egger)
+```
+
+Only rows with `included=True` enter the regression. The original pooling
+model, tau-squared estimate, confidence-interval method, weights, and result
+object are not changed. The Egger calculation is the same whether the source
+result was fitted as common or random effects because this first API implements
+only the classical regression form.
+
+Pair the numerical result with the plot:
+
+```python
+ax = result.funnel(contour_levels=(0.90, 0.95, 0.99))
+print(egger.statistic, egger.df, egger.pvalue)
+```
+
+The optional contours mark two-sided significance regions around the null
+effect. They can make it easier to see whether an apparently missing part of
+the funnel lies mainly in a non-significant region, but they do not establish
+that studies are missing.
+
+## Harbord test for binary odds ratios
+
+For an analysis fitted from retained two-group counts with
+`meta_binary(..., measure="OR")`, Harbord regression uses the efficient score
+and its variance:
+
+```python
+odds_ratios = ma.meta_binary(
+    trials,
+    event_treat="event_treat",
+    n_treat="n_treat",
+    event_control="event_control",
+    n_control="n_control",
+    measure="OR",
+    method="MH",
+)
+
+harbord = odds_ratios.harbord_test()
+print(harbord.statistic, harbord.df, harbord.pvalue)
+```
+
+`harbord.intercept` is the tested asymmetry coefficient in the standardized
+score regression. `harbord.limit_estimate` is its efficient-score limit
+coefficient; `display_limit_estimate` and `display_limit_ci` exponentiate that
+coefficient. Treat these as regression outputs, not replacements for the
+pooled estimate.
+
+Harbord derives null efficient scores directly from raw treatment/control
+counts. It does not use continuity-corrected study log odds ratios, so changing
+the source study-level correction does not change the diagnostic. It is also
+independent of whether the source analysis used MH, inverse variance,
+random-effects inverse variance, or Peto pooling. Single-arm zero-event studies
+remain usable when their total event and non-event margins are positive.
+
+The result records the standardized-score response, square-root score-variance
+predictor, equivalent weighting convention, residual dispersion, scaled-design
+condition number, and the fact that no continuity correction is used.
+
+## Peters test for binary odds ratios
+
+When the analysis was fitted from retained two-group counts with
+`meta_binary(..., measure="OR")`, use the outcome-specific Peters regression:
+
+```python
+odds_ratios = ma.meta_binary(
+    trials,
+    event_treat="event_treat",
+    n_treat="n_treat",
+    event_control="event_control",
+    n_control="n_control",
+    measure="OR",
+    method="MH",
+)
+
+peters = odds_ratios.peters_test()
+print(peters.statistic, peters.df, peters.pvalue)
+```
+
+The test reconstructs conventional study log odds ratios from the retained
+four-cell counts and the analysis's recorded study-level continuity correction.
+Its result is therefore independent of whether the source pooled estimate used
+MH, inverse variance, random-effects inverse variance, or Peto. If the source
+used Peto, a note makes the different study-effect construction explicit.
+
+The tested coefficient is `peters.slope`, the slope of log OR on inverse total
+sample size. `peters.limit_estimate` is the extrapolated log OR as total sample
+size tends to infinity; `display_limit_estimate` and `display_limit_ci` are on
+the OR scale. These are regression extrapolations, not replacements for the
+pooled estimate. The result also records `residual_dispersion`,
+`weight_method`, the continuity-correction contract, corrected-study count,
+and the scaled-design condition number.
+
+Peters regression is unavailable for generic effects whose original four-cell
+counts are no longer known, and for RR, RD, continuous, correlation, or
+diagnostic-accuracy analyses.
+
+## Inspect the Egger result
+
+The tested coefficient is the intercept in the standardized-normal-deviate
+form of the Egger regression:
+
+```python
+egger.intercept
+egger.intercept_standard_error
+egger.intercept_ci
+egger.statistic
+egger.df
+egger.pvalue
+```
+
+The result also exposes the extrapolated effect as the standard error tends to
+zero:
+
+```python
+egger.limit_estimate
+egger.limit_standard_error
+egger.limit_ci
+egger.display_limit_estimate
+egger.display_limit_ci
+```
+
+`limit_estimate` remains on the analysis model scale. Its display counterpart
+is exponentiated for OR/RR and back-transformed with `tanh` for Fisher's z
+correlations. It is an extrapolated regression intercept, not an automatically
+bias-corrected replacement for the fitted pooled estimate.
+
+`to_dict()` returns a detached mapping containing the coefficients, intervals,
+test, method identifiers, condition number, scales, and warnings:
+
+```python
+payload = egger.to_dict()
+```
+
+Pass an explicit confidence level for the two coefficient intervals, or omit
+it to reuse the fitted analysis level:
+
+```python
+egger_90 = result.egger_test(confidence_level=0.90)
+```
+
+Changing the confidence level does not change the coefficient estimates, test
+statistic, or p-value.
+
+## Statistical form
+
+The classical equation is:
+
+```text
+y_i / s_i = alpha + beta * (1 / s_i) + error_i
+```
+
+where `y_i` is the effect and `s_i` is its standard error. The two-sided test
+is `H0: alpha = 0` and uses a t distribution with `k-2` degrees of freedom.
+The fitted `beta` is the limit estimate.
+
+PyMetaAnalysis evaluates the algebraically equivalent weighted regression of
+`y_i` on `s_i`, using inverse sampling-variance weights and a multiplicative
+residual-dispersion estimate. The implementation scales the weights and design
+columns for numerical stability without changing the coefficients or their
+covariance. This contract corresponds to:
+
+```r
+metafor::regtest(
+  effect,
+  variance,
+  model = "lm",
+  predictor = "sei"
+)
+```
+
+The random/mixed-effects regression version of `metafor::regtest()` is a
+different model and is not silently substituted.
+
+## Applicability checks
+
+At least three included studies are mathematically required. PyMetaAnalysis
+returns a result for `3 <= k < 10` but records a warning because funnel-
+asymmetry tests generally have low power with fewer than ten studies. The
+[Cochrane Handbook](https://www.cochrane.org/authors/handbooks-and-manuals/handbook/current/chapter-13#section-13-3-4-4)
+uses ten studies as a rule of thumb and also advises against testing when study
+standard errors are all similar.
+
+Exactly or numerically non-identifiable standard errors produce an error
+instead of an unstable coefficient. For less extreme cases, inspect the study
+size distribution and `egger.condition_number`; the library does not invent a
+universal cutoff for “enough” variation.
+
+The classical Egger test is particularly problematic for some effect measures
+because the effect and its standard error can be inherently associated.
+PyMetaAnalysis therefore records an additional warning for:
+
+- odds ratios, for which binary-outcome alternatives such as Harbord or Peters
+  may be preferable;
+- standardized mean differences, for which the same association can produce
+  distorted funnel plots.
+
+Harbord and Peters regression are available for OR analyses created by
+`meta_binary()`. A generic effect labeled `GENERIC` cannot reveal the original
+two-group counts, so neither binary-specific method accepts it.
+
+For Harbord regression, the efficient-score variances must vary enough to
+identify the asymmetry intercept. Every included study must have positive total
+events and non-events. The method uses raw counts and never applies the source
+continuity correction. At least three studies are mathematically required, and
+the same fewer-than-ten warning applies.
+
+For Peters regression, total sample sizes must vary enough to identify the
+slope. The method uses `S*F/N` weights, where `S` and `F` are the raw total
+events and non-events. Its continuity correction affects only the reconstructed
+study log OR, not these marginal-count weights. At least three studies are
+mathematically required, and the same fewer-than-ten warning applies.
+
+## Interpretation
+
+A small p-value indicates evidence of the association defined by the selected
+diagnostic: effect with standard error for Egger, standardized efficient score
+with score precision for Harbord, or log OR with inverse total sample size for
+Peters. Possible explanations include genuine heterogeneity, design or
+population differences, selective outcome reporting, other non-reporting
+mechanisms, artefactual associations, and chance.
+
+A large p-value does not demonstrate symmetry or exclude missing evidence,
+especially with few studies. A small p-value does not establish publication
+bias. Interpret the test alongside the funnel plot, heterogeneity, study
+characteristics, protocol information, and sensitivity analyses. Contour-
+enhanced funnels add useful significance context, but neither locate missing
+studies nor identify the mechanism behind asymmetry. The
+[original Egger paper](https://doi.org/10.1136/bmj.315.7109.629) and
+[`metafor::regtest`](https://wviechtb.github.io/metafor/reference/regtest.html)
+provide the methodological and software references for the Egger
+implementation. The Harbord and Peters implementations follow the documented
+[`meta::metabias`](https://search.r-project.org/CRAN/refmans/meta/html/metabias.html)
+contract and the corresponding Harbord et al. (2006) and Peters et al. (2006)
+methods cited there.

{pymetaanalysis-0.7.0 → pymetaanalysis-0.8.0}/docs/index.md

@@ -65,8 +65,9 @@ Binary analyses with sparse data should also review
 [zero-event studies](guides/zero-events.md).
 
 After fitting a model, continue with [sensitivity analysis](guides/sensitivity-analysis.md)
-and [provenance and reporting](guides/provenance-reporting.md) to assess stability
-and create an auditable export.
+and [small-study effects](guides/small-study-effects.md) to assess stability and
+funnel asymmetry. Use [provenance and reporting](guides/provenance-reporting.md)
+to create an auditable export.
 
 The [statistical methods](methods/statistical-methods.md) page is the formula-
 level implementation contract. [Validation](validation.md) explains the R
@@ -86,13 +87,13 @@ lists unsupported methods explicitly.
 
 ## Project status
 
-PyMetaAnalysis 0.7.0 adds independent Pearson-correlation pooling on Fisher's
-z scale, including common- and random-effects fits, back-transformed displays,
-subgroups, sensitivity workflows, plots, reports, and independent R
-references. It also tightens categorical moderator and method-option contracts
-and expands small-sample and Q-profile validation. The project has not
-undergone a formal external statistical audit. Pin the package version for
-consequential work and independently check important analyses. See the
+PyMetaAnalysis 0.8.0 adds classical Egger regression plus Harbord and Peters
+tests for two-group odds ratios, together with optional contour-enhanced funnel
+plots. These small-study-effect diagnostics include explicit applicability
+warnings, documented interpretation limits, and independent R reference
+fixtures where corresponding implementations are available. The project has
+not undergone a formal external statistical audit. Pin the package version
+for consequential work and independently check important analyses. See the
 repository
 [changelog](https://github.com/ZhaoboDing/PyMetaAnalysis/blob/main/CHANGELOG.md)
 and [contribution guide](development.md). For manuscripts and archived