epilink 0.2.1a0__tar.gz

epilink-0.2.1a0/.github/workflows/ci.yml

@@ -0,0 +1,59 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11"]
+        jit: ["on", "off"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[dev]
+
+      - name: Lint + type-check
+        run: |
+          ruff check .
+          black --check .
+          mypy src/epilink
+
+      - name: Test
+        env:
+          NUMBA_DISABLE_JIT: ${{ matrix.jit == 'off' && '1' || '0' }}
+        run: |
+          if [ "${{ matrix.jit }}" = "off" ]; then
+            THRESH=80
+          else
+            THRESH=70
+          fi
+          pytest --cov=epilink --cov-report=xml --cov-report=term-missing \
+                 --cov-fail-under=$THRESH \
+                 tests/ \
+                 -W error::DeprecationWarning:epilink
+
+      - name: Upload coverage to Codecov
+        if: always()
+        uses: codecov/codecov-action@v4
+        with:
+          files: ./coverage.xml
+          # Set a secret CODECOV_TOKEN for private repos; for public repos this can be omitted
+          token: ${{ secrets.CODECOV_TOKEN }}
+          fail_ci_if_error: false
+          flags: unittests
+          name: py${{ matrix.python-version }}-jit-${{ matrix.jit }}

epilink-0.2.1a0/.github/workflows/release.yml

@@ -0,0 +1,35 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/epilink
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Build distributions
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m build
+          python -m twine check dist/*
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

epilink-0.2.1a0/.github/workflows/test-release.yml

@@ -0,0 +1,93 @@
+name: Test Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version_suffix:
+        description: 'PEP 440 suffix (e.g., dev123, rc1, b1). Leave blank for dev<run_number>.'
+        required: false
+        default: ''
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish-testpypi:
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/epilink
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Set test version
+        run: |
+          python -m pip install --upgrade pip tomlkit
+          SUFFIX="${{ inputs.version_suffix }}"
+          if [ -z "$SUFFIX" ]; then
+            SUFFIX="dev${GITHUB_RUN_NUMBER}"
+          fi
+
+          export EPILINK_SUFFIX="$SUFFIX"
+          python - <<'PY'
+          import os
+          from pathlib import Path
+          import subprocess
+          import tomlkit
+
+          path = Path("pyproject.toml")
+          text = path.read_text(encoding="utf-8")
+          data = tomlkit.parse(text)
+          project = data.get("project")
+          if not project:
+            raise SystemExit("version not found in pyproject.toml")
+
+          if "version" in project:
+            base_version = str(project["version"])
+          elif "version" in project.get("dynamic", []):
+            try:
+              tag = subprocess.check_output(
+                  ["git", "describe", "--tags", "--abbrev=0"],
+                  text=True,
+              ).strip()
+            except subprocess.CalledProcessError:
+              tag = "0.0.0"
+            base_version = tag[1:] if tag.startswith("v") else tag
+          else:
+            raise SystemExit("version not found in pyproject.toml")
+
+          suffix = os.environ["EPILINK_SUFFIX"]
+          new_version = f"{base_version}.{suffix}"
+
+          project["version"] = new_version
+          if "dynamic" in project:
+            dynamic = [item for item in project["dynamic"] if item != "version"]
+            if dynamic:
+              project["dynamic"] = dynamic
+            else:
+              del project["dynamic"]
+
+          path.write_text(tomlkit.dumps(data), encoding="utf-8")
+          print(f"Using test version: {new_version}")
+          PY
+
+      - name: Build distributions
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m build
+          python -m twine check dist/*
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          verbose: true

epilink-0.2.1a0/.gitignore

@@ -0,0 +1,35 @@
+# Python bytecode
+__pycache__/
+*.py[cod]
+
+# Build artifacts
+build/
+dist/
+*.egg-info/
+*.egg
+*.whl
+src/epilink/_version.py
+
+# Test and coverage artifacts
+.coverage
+.coverage.*
+htmlcov/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# MkDocs
+site/
+
+# IDEs
+.idea/
+.vscode/
+*.iml
+
+# macOS
+.DS_Store

epilink-0.2.1a0/.pre-commit-config.yaml

@@ -0,0 +1,14 @@
+repos:
+  - repo: https://github.com/psf/black
+    rev: 24.8.0
+    hooks:
+      - id: black
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.4
+    hooks:
+      - id: ruff
+        args: [--fix]
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.11.2
+    hooks:
+      - id: mypy

epilink-0.2.1a0/CITATION.cff

@@ -0,0 +1,24 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+title: "epilink: Epidemiological Linkage Inference from Temporal and Genetic Data with a Variable Infectiousness (E/P/I) Model for SARS-CoV-2"
+version: "0.1.0"
+license: "MIT"
+url: "https://github.com/ydnkka/epilink"
+authors:
+  - family-names: Arthur
+    given-names: Dominic
+repository-code: "https://github.com/ydnkka/epilink"
+references:
+  - type: article
+    authors:
+      - family-names: Hart
+        given-names: William S
+      - family-names: Maini
+        given-names: Philip K
+      - family-names: Thompson
+        given-names: Robin N
+    title: "High infectiousness immediately before COVID-19 symptom onset highlights the importance of continued contact tracing"
+    journal: "eLife"
+    year: 2021
+    volume: "10"
+    doi: "10.7554/eLife.65534"

epilink-0.2.1a0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Dominic Arthur
+
+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.

epilink-0.2.1a0/PKG-INFO

@@ -0,0 +1,287 @@
+Metadata-Version: 2.4
+Name: epilink
+Version: 0.2.1a0
+Summary: Epidemiological Linkage Inference from Temporal and Genetic Data with a Variable Infectiousness (E/P/I) Model for SARS-CoV-2.
+Project-URL: Homepage, https://github.com/ydnkka/epilink
+Project-URL: Issues, https://github.com/ydnkka/epilink/issues
+Project-URL: Documentation, https://github.com/ydnkka/epilink#readme
+Project-URL: Repository, https://github.com/ydnkka/epilink
+Project-URL: Bug Tracker, https://github.com/ydnkka/epilink/issues
+Project-URL: Release Notes, https://github.com/ydnkka/epilink/releases
+Author-email: Dominic Arthur <arthurdominic04@gmail.com>
+Maintainer-email: Dominic Arthur <arthurdominic04@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 Dominic Arthur
+        
+        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.
+License-File: LICENSE
+Keywords: SARS-CoV-2,epidemiology,genomics,infectious-disease,linkage-inference,transmission
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.9
+Requires-Dist: llvmlite<0.44,>=0.41
+Requires-Dist: networkx<4.0,>=3.0
+Requires-Dist: numba<0.61,>=0.58
+Requires-Dist: numpy<2.0,>=1.22
+Requires-Dist: pandas<3.0,>=2.0
+Requires-Dist: scipy<2.0,>=1.9
+Provides-Extra: all
+Requires-Dist: black>=24.1; extra == 'all'
+Requires-Dist: mkdocs-material>=9.5; extra == 'all'
+Requires-Dist: mkdocs>=1.5; extra == 'all'
+Requires-Dist: mkdocstrings[python]>=0.24; extra == 'all'
+Requires-Dist: mypy>=1.4; extra == 'all'
+Requires-Dist: pytest-cov>=4.0; extra == 'all'
+Requires-Dist: pytest-mock>=3.10; extra == 'all'
+Requires-Dist: pytest>=7.3; extra == 'all'
+Requires-Dist: ruff>=0.5; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: black>=24.1; extra == 'dev'
+Requires-Dist: mypy>=1.4; extra == 'dev'
+Requires-Dist: pre-commit>=3.3; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.10; extra == 'dev'
+Requires-Dist: pytest>=7.3; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs>=1.5; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
+Provides-Extra: lint
+Requires-Dist: black>=24.1; extra == 'lint'
+Requires-Dist: ruff>=0.5; extra == 'lint'
+Provides-Extra: test
+Requires-Dist: pytest-cov>=4.0; extra == 'test'
+Requires-Dist: pytest-mock>=3.10; extra == 'test'
+Requires-Dist: pytest>=7.3; extra == 'test'
+Provides-Extra: type-check
+Requires-Dist: mypy>=1.4; extra == 'type-check'
+Description-Content-Type: text/markdown
+
+# epilink: Epidemiological Linkage from Temporal and Genetic Data
+
+[![codecov](https://codecov.io/gh/ydnkka/epilink/branch/master/graph/badge.svg)](https://codecov.io/gh/ydnkka/epilink)
+
+Estimate the probability that two cases are epidemiologically linked from their temporal and genetic distances. Implements a mechanistic SARS‑CoV‑2 infectiousness model (E/P/I) with optional Numba acceleration. Usable from Python or the command line.
+
+## Features
+
+- Estimate P(link | genetic distance g, temporal gap t)
+- Parameterised infectiousness profiles (TOIT/TOST; configurable)
+- Fast simulation kernels with optional JIT (Numba)
+- Python API plus a lightweight CLI for batch runs
+
+---
+
+## Installation
+
+From PyPI (yet to be released):
+
+```bash
+pip install epilink
+```
+
+Recommended (conda/mamba):
+
+```bash
+# Create a fresh env (uses compiled deps from conda-forge)
+conda create -n epilink -c conda-forge python=3.11 numpy scipy numba networkx pandas pip
+conda activate epilink
+git clone https://github.com/ydnkka/epilink.git
+cd epilink
+
+# Install the package from source without touching conda-managed deps
+pip install -e . --no-deps
+
+# (Optional) Dev tools: tests, linting, docs
+pip install "pytest>=7.3" "pytest-cov>=4.0" "mypy>=1.4" "ruff>=0.5" "black>=24.1" \
+            "pre-commit>=3.3" "mkdocs>=1.5" "mkdocs-material>=9.5" "mkdocstrings[python]>=0.24"
+```
+
+Alternative (pip + venv):
+
+```bash
+python -m venv .venv
+source .venv/bin/activate  # Windows: .venv\Scripts\activate
+python -m pip install --upgrade pip
+pip install -e .[dev]
+```
+
+Notes:
+- Prefer conda-forge for NumPy/SciPy/Numba (especially on Apple Silicon).
+- In a conda env, avoid pip-installing compiled deps; use `pip install -e . --no-deps`.
+
+---
+
+## Quickstart
+
+### Python API
+
+```python
+import numpy as np
+from epilink import TOIT, MolecularClock, linkage_probability, linkage_probability_matrix
+
+toit = TOIT(rng_seed=123)
+clock = MolecularClock(relax_rate=False, rng_seed=123)
+
+# Probability that a pair with 2 SNPs and 4 days apart is directly linked (m=0)
+p = linkage_probability(
+    toit=toit,
+    clock=clock,
+    genetic_distance=2,
+    temporal_distance=4,
+    intermediate_generations=0,
+    num_simulations=10_000,
+)
+print("P(link):", p)
+
+# Grid over genetic distances (SNPs) and temporal gaps (days)
+gd = np.arange(0, 6)       # 0..5 SNPs
+td = np.arange(0, 15, 3)   # 0..12 days, step 3
+mat = linkage_probability_matrix(
+    toit=toit,
+    clock=clock,
+    genetic_distances=gd,
+    temporal_distances=td,
+    num_simulations=10_000,
+)
+print(mat)
+```
+
+### CLI
+
+```bash
+# Help
+epilink --help
+epilink point --help
+epilink grid --help
+
+# Single pair
+epilink point -g 2 -t 4 --nsims 200
+
+# Multiple pairs (CSV to stdout)
+epilink point -g 0 1 2 -t 0 2 5 --nsims 500 > out.csv
+
+# Custom infectiousness profile and TOIT support
+epilink point -g 2 -t 4 --nsims 200 \
+             --a 0 --b 40 \
+             --incubation-shape 5.0 --incubation-scale 1.1 \
+             --latent-shape 2.0 --symptomatic-rate 0.4 \
+             --symptomatic-shape 1.2 --rel-presymptomatic-infectiousness 2.0
+
+# Grid (CSV to file)
+epilink grid --g-start 0 --g-stop 5 --g-step 1 \
+             --t-start 0 --t-stop 12 --t-step 3 \
+             --nsims 10000 --out grid.csv
+```
+
+Commonly used options (see `--help` for full list):
+- `-m, --intermediate-generations` e.g. `"0,1,2"`
+- `--relax-rate`
+- `--subs-rate 1e-3`
+- `--subs-rate-sigma 0.33`
+- `--seed 12345`
+- `--a 0 --b 60` (TOIT support bounds)
+- `--incubation-shape`, `--incubation-scale`, `--latent-shape`, `--symptomatic-rate`, `--symptomatic-shape`, `--rel-presymptomatic-infectiousness`
+
+---
+
+## Development
+
+Run tests:
+
+```bash
+pytest --cov=epilink --cov-report=term-missing
+# To count Python-side coverage of JIT kernels:
+# NUMBA_DISABLE_JIT=1 pytest
+```
+
+Code quality:
+
+```bash
+ruff check .
+black .
+mypy src/epilink
+```
+
+Pre-commit:
+
+```bash
+pre-commit install
+pre-commit run -a
+```
+
+Docs:
+
+```bash
+mkdocs serve
+```
+
+---
+
+## Examples
+
+Examples in `examples/`:
+- `python examples/quickstart.py`
+- `python examples/grid_to_csv.py --out grid.csv`
+
+Install plotting deps if needed:
+
+```bash
+mamba install -c conda-forge matplotlib seaborn
+```
+
+---
+
+## License
+
+MIT License (see [LICENSE](LICENSE))
+
+---
+
+## Development & Contributing
+
+For developers:
+- **Testing releases**: See [TESTPYPI.md](TESTPYPI.md) for instructions on testing package releases on TestPyPI before publishing to PyPI
+- **Contributing**: Pull requests welcome! Please ensure tests pass and coverage remains high
+
+---
+
+## Contact
+
+- Questions or issues: open an [issue](https://github.com/ydnkka/epilink/issues)
+- Maintainer: [@ydnkka](https://github.com/ydnkka)
+
+---
+
+## Reference
+
+Hart WS, Maini PK, Thompson RN (2021). High infectiousness immediately before COVID‑19 symptom onset highlights the importance of continued contact tracing. eLife, 10:e65534. https://doi.org/10.7554/eLife.65534