PyMetaAnalysis 0.1.0__tar.gz

pymetaanalysis-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,201 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install test dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install ".[test]"
+
+      - name: Run tests with branch coverage
+        run: python -m pytest --cov=meta_analyze --cov-branch --cov-report=term-missing
+
+  minimum-dependencies:
+    name: Minimum direct dependencies (Python 3.10)
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      - name: Set up Python 3.10
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.10"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install declared lower bounds
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install \
+            "numpy==1.24.0" \
+            "pandas==2.0.0" \
+            "scipy==1.10.0" \
+            "hypothesis==6.100.0" \
+            "matplotlib==3.7.0" \
+            "pytest==8.0.0" \
+            "pytest-cov==5.0.0"
+          python -m pip install --no-deps --editable .
+
+      - name: Report resolved dependency versions
+        run: |
+          python -m pip list
+          python -m pip check
+
+      - name: Run tests at declared lower bounds
+        run: python -m pytest --cov=meta_analyze --cov-branch --cov-report=term-missing
+
+  quality:
+    name: Static checks
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install development dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install ".[dev,plot]"
+
+      - name: Check formatting
+        run: python -m ruff format --check .
+
+      - name: Lint
+        run: python -m ruff check .
+
+      - name: Validate GitHub Actions workflows
+        run: actionlint
+
+      - name: Type check
+        run: python -m mypy
+
+      - name: Check release metadata consistency
+        run: python tools/check_release.py
+
+  docs:
+    name: Documentation
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install documentation dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install ".[docs,notebook]"
+
+      - name: Build documentation
+        run: python -m mkdocs build --strict
+
+      - name: Execute example notebooks
+        run: python tools/execute_notebooks.py
+
+  build:
+    name: Build and inspect distributions
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install build frontend
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build
+
+      - name: Build wheel and source distribution
+        run: python -m build
+
+      - name: Verify distribution contents
+        run: python tools/inspect_distribution.py dist
+
+      - name: Smoke test the installed wheel
+        shell: bash
+        run: |
+          python -m pip install --force-reinstall dist/*.whl
+          cd "$RUNNER_TEMP"
+          python - <<'PY'
+          import importlib.metadata
+
+          import meta_analyze as ma
+
+          result = ma.meta_analysis(
+              effect=[1.0, 2.0, 3.0],
+              variance=[1.0, 1.0, 1.0],
+              model="common",
+          )
+          assert result.k == 3
+          assert result.estimate == 2.0
+          print(importlib.metadata.version("PyMetaAnalysis"))
+          PY

pymetaanalysis-0.1.0/.github/workflows/pages.yml

@@ -0,0 +1,66 @@
+name: Documentation site
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build documentation site
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      pages: write
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install documentation dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install ".[docs]"
+
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@v6
+
+      - name: Build strict MkDocs site
+        run: python -m mkdocs build --strict
+
+      - name: Upload GitHub Pages artifact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: site
+
+  deploy:
+    name: Deploy documentation site
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    permissions:
+      pages: write
+      id-token: write
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

pymetaanalysis-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,125 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build release artifacts
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Check out tagged revision
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Require the tagged commit to belong to main
+        run: git merge-base --is-ancestor "$GITHUB_SHA" origin/main
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build twine
+
+      - name: Validate release metadata
+        run: python tools/check_release.py --tag "$GITHUB_REF_NAME"
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Check distribution metadata and contents
+        run: |
+          python -m twine check dist/*
+          python tools/inspect_distribution.py dist
+
+      - name: Benchmark the built wheel
+        run: |
+          python -m pip install --force-reinstall dist/*.whl
+          python benchmarks/benchmark_core.py --output release-benchmark.json
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v7
+        with:
+          name: python-package-distributions
+          path: dist/
+          if-no-files-found: error
+          retention-days: 7
+
+      - name: Upload release benchmark
+        uses: actions/upload-artifact@v7
+        with:
+          name: release-benchmark
+          path: release-benchmark.json
+          if-no-files-found: error
+          retention-days: 7
+
+  publish:
+    name: Publish distributions to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/p/PyMetaAnalysis
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v8
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: Create GitHub Release
+    needs: publish
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v8
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Download release benchmark
+        uses: actions/download-artifact@v8
+        with:
+          name: release-benchmark
+
+      - name: Create release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          args=("$GITHUB_REF_NAME" dist/* release-benchmark.json --verify-tag --generate-notes)
+          version="${GITHUB_REF_NAME#v}"
+          if [[ "$version" =~ [[:alpha:]] ]]; then
+            args+=(--prerelease)
+          fi
+          gh release create "${args[@]}"

pymetaanalysis-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+# Local design notes are intentionally not part of the published project.
+/DESIGN.md
+
+# Python environments and generated files
+/.venv/
+/.release-smoke/
+.ipynb_checkpoints/
+__pycache__/
+*.py[cod]
+*.egg-info/
+/.pytest_cache/
+/.hypothesis/
+/.mypy_cache/
+/.ruff_cache/
+/.coverage
+/htmlcov/
+/build/
+/dist/
+/site/

pymetaanalysis-0.1.0/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to PyMetaAnalysis will be documented in this file.
+
+Changes planned for the next release accumulate under `Unreleased`.
+
+## Unreleased
+
+## 0.1.0 - 2026-07-15
+
+### Added
+
+- pandas-first generic, binary, and continuous study-level meta-analysis APIs;
+- common-effect and random-effects inverse-variance models;
+- common-effect Mantel-Haenszel OR/RR pooling;
+- REML, Paule-Mandel, and DerSimonian-Laird tau-squared estimators;
+- normal, Hartung-Knapp, and safeguarded Hartung-Knapp confidence intervals;
+- HTS random-effects prediction intervals;
+- subgroup, leave-one-out, and cumulative workflows;
+- optional Matplotlib forest, subgroup forest, and funnel plots;
+- immutable results, diagnostics, provenance, Methods text, and JSON/Markdown
+  reports;
+- R `metafor` cross-software fixtures, property tests, and numerical edge-case
+  coverage;
+- explicit RD zero-variance boundary policy and heterogeneity-definition
+  reporting;
+- complete MkDocs user, methods, API, validation, limitation, and development
+  documentation;
+- R `meta`/`metafor` terminology and parameter mappings;
+- machine-readable citation metadata and an executable end-to-end notebook;
+- GitHub Pages and PyPI Trusted Publishing release workflows;
+- release metadata, distribution-content, notebook-execution, and performance
+  baseline tooling.
+
+### Changed
+
+- independent external statistical review is documented as a recommended
+  validation activity rather than a release requirement;
+- report schema 1.1 records `heterogeneity.i2_method`;
+- random-effects I-squared/H-squared use tau-squared and typical within-study
+  variance, while common-effect/MH analyses retain Q-based definitions;
+- random-effects summaries provide method-selection notes for small-study and
+  positive-heterogeneity cases.

pymetaanalysis-0.1.0/CITATION.cff

@@ -0,0 +1,21 @@
+cff-version: 1.2.0
+message: >-
+  If you use PyMetaAnalysis in research, cite the exact software release and
+  report the statistical methods used in the analysis.
+title: PyMetaAnalysis
+type: software
+authors:
+  - name: PyMetaAnalysis contributors
+version: 0.1.0
+date-released: 2026-07-15
+repository-code: https://github.com/ZhaoboDing/PyMetaAnalysis
+url: https://zhaoboding.github.io/PyMetaAnalysis/
+license: MIT
+abstract: >-
+  A pandas-first Python library for auditable, conventional study-level
+  meta-analysis.
+keywords:
+  - meta-analysis
+  - statistics
+  - systematic review
+  - evidence-based medicine

pymetaanalysis-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,32 @@
+# Contributing to PyMetaAnalysis
+
+Thank you for helping improve PyMetaAnalysis. Contributions may include code,
+documentation, reproducible bug reports, statistical review, and independent
+reference cases.
+
+## Development setup
+
+```console
+git clone https://github.com/ZhaoboDing/PyMetaAnalysis.git
+cd PyMetaAnalysis
+python -m pip install -e ".[test,dev,docs,plot]"
+```
+
+Run the project checks before opening a pull request:
+
+```console
+python -m ruff format .
+python -m ruff check .
+python -m mypy
+python -m pytest --cov=meta_analyze --cov-branch --cov-report=term-missing
+python -m mkdocs build --strict
+python -m build
+```
+
+Statistical changes need formula documentation, boundary tests, and an
+independent reference comparison where possible. Do not replace committed
+golden values without explaining and reviewing the discrepancy.
+
+See the full [development and contribution guide](docs/development.md) for
+statistical-change requirements, R fixture regeneration, documentation rules,
+and issue-reporting guidance.

pymetaanalysis-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PyMetaAnalysis contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.