agingclockbench 0.1.0__tar.gz

agingclockbench-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aaditya Srivant Geddam
+
+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.

agingclockbench-0.1.0/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: agingclockbench
+Version: 0.1.0
+Summary: Benchmark biological aging clocks on your data — PhenoAge, KDM, DunedinPACE proxy
+License: MIT
+License-File: LICENSE
+Keywords: aging,biomarkers,aging-clocks,longevity,biological-age,phenoage,kdm,nhanes,mortality
+Author: Aaditya Geddam
+Author-email: aaditya.geddam@gmail.com
+Requires-Python: >=3.11,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Dist: click (>=8.1.0)
+Requires-Dist: lifelines (>=0.28.0)
+Requires-Dist: matplotlib (>=3.8.0)
+Requires-Dist: numpy (>=1.26.0)
+Requires-Dist: pandas (>=2.2.0)
+Requires-Dist: plotly (>=5.17.0)
+Requires-Dist: pyarrow (>=13.0.0)
+Requires-Dist: pydantic (>=2.3.0)
+Requires-Dist: scipy (>=1.13.0)
+Requires-Dist: seaborn (>=0.13.0)
+Project-URL: Documentation, https://aadityageddam-ux.github.io/aging_clock_bench/
+Project-URL: Homepage, https://aadityageddam-ux.github.io/aging_clock_bench/
+Project-URL: Repository, https://github.com/aadityageddam-ux/aging_clock_bench
+Description-Content-Type: text/markdown
+
+# AgingClockBench
+
+[![PyPI version](https://badge.fury.io/py/agingclockbench.svg)](https://badge.fury.io/py/agingclockbench)
+[![Tests](https://github.com/aadityageddam-ux/aging_clock_bench/actions/workflows/test.yml/badge.svg)](https://github.com/aadityageddam-ux/aging_clock_bench/actions/workflows/test.yml)
+[![Coverage](https://img.shields.io/badge/coverage-89%25-brightgreen)](https://github.com/aadityageddam-ux/aging_clock_bench)
+[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://aadityageddam-ux.github.io/aging_clock_bench/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
+
+**Benchmark biological aging clocks on your data in minutes.**
+
+Multiple biological aging clocks exist — PhenoAge, KDM, DunedinPACE — but no standard tool lets researchers compare them side-by-side. AgingClockBench is the **first open-source Python package** implementing multiple clocks with a unified interface and reproducible mortality-validated benchmarking.
+
+📖 **[Full Documentation](https://aadityageddam-ux.github.io/aging_clock_bench/)**
+
+---
+
+## Install
+
+```bash
+pip install agingclockbench
+```
+
+Requires Python 3.11+.
+
+---
+
+## Quick Start
+
+```python
+from agingclockbench import PhenoAge, KDM, BenchmarkSuite
+from agingclockbench.datasets import load_nhanes_sample
+
+# Load bundled NHANES 1999-2000 (N=4,086, 20-year mortality follow-up)
+df = load_nhanes_sample()
+
+# Compute biological ages
+results = {
+    "PhenoAge": PhenoAge().transform(df),
+    "KDM":      KDM().transform(df),
+}
+
+# Benchmark against mortality
+suite = BenchmarkSuite(mortality_col="mortstat", followup_col="permth_exm")
+report = suite.run(df, results)
+
+print(report.to_dataframe())
+```
+
+```
+Clock     Pearson r  Mort HR (per SD accel)  Mort p-value
+PhenoAge      0.930                    1.83      0.000001
+KDM           0.677                    1.41      0.000001
+```
+
+```python
+report.plot_km_survival()      # Kaplan-Meier by acceleration quartile
+report.plot_comparison()       # biological age vs chronological age
+report.to_html("report.html")  # interactive Plotly report
+```
+
+---
+
+## CLI
+
+```bash
+# Benchmark on bundled NHANES with HTML report
+agingclockbench benchmark --data bundled --clocks all --report
+
+# Your own data
+agingclockbench benchmark \
+  --data my_cohort.csv \
+  --clocks PhenoAge KDM \
+  --mortality-col vital_status \
+  --followup-col followup_months \
+  --output ./results/
+```
+
+---
+
+## Implemented Clocks
+
+| Clock | Reference | Biomarkers | Key metric (NHANES) |
+|-------|-----------|-----------|---------------------|
+| **PhenoAge** | Levine et al. 2018 *Aging Cell* | 9 blood | Pearson r=0.93, HR=1.83 |
+| **KDM** | Klemera & Doubal 2006 *Mech Ageing Dev* | 8 blood | Pearson r=0.68, HR=1.41 |
+| **DunedinPACEProxy** | Proxy (NOT Belsky 2022) | 7 blood | pace corr w/ PhenoAge accel r=0.84 |
+
+> **Note:** DunedinPACEProxy is a blood-biomarker approximation. The real DunedinPACE requires DNA methylation data (Illumina EPIC array).
+
+---
+
+## Features
+
+- ✅ **Unified interface** — all clocks share the same `transform()` API
+- ✅ **Validated** — PhenoAge implementation cross-validated against reference; zero numerical difference on N=4,086 NHANES participants  
+- ✅ **Mortality benchmarking** — Cox PH hazard ratios, Kaplan-Meier curves
+- ✅ **Bundled data** — NHANES 1999-2000 with 20-year mortality follow-up, ready to use
+- ✅ **Interactive reports** — Plotly HTML with comparison plots and benchmark table
+- ✅ **CLI tool** — `agingclockbench benchmark` works out of the box
+- ✅ **89% test coverage** — 76+ tests, CI/CD on every push
+
+---
+
+## Documentation
+
+| Resource | Link |
+|----------|------|
+| Full docs | [aadityageddam-ux.github.io/aging_clock_bench](https://aadityageddam-ux.github.io/aging_clock_bench/) |
+| Quickstart | [docs/quickstart](https://aadityageddam-ux.github.io/aging_clock_bench/quickstart/) |
+| PhenoAge algorithm | [docs/algorithms/phenoage](https://aadityageddam-ux.github.io/aging_clock_bench/algorithms/phenoage/) |
+| FAQ | [docs/faq](https://aadityageddam-ux.github.io/aging_clock_bench/faq/) |
+| Example notebooks | [examples/](examples/) |
+
+---
+
+## Citation
+
+If you use AgingClockBench in your research, please cite:
+
+```bibtex
+@software{geddam2026agingclockbench,
+  author = {Geddam, Aaditya},
+  title  = {AgingClockBench: Benchmarking biological aging clocks},
+  url    = {https://github.com/aadityageddam-ux/aging_clock_bench},
+  year   = {2026}
+}
+```
+
+**Also cite the underlying clock papers:**
+
+- Levine ME, et al. *Aging Cell.* 2018. (PhenoAge)
+- Klemera P, Doubal S. *Mech Ageing Dev.* 2006. (KDM)
+
+---
+
+## Contributing
+
+Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+To add a new clock, implement the `BaseClock` interface — see the [FAQ](https://aadityageddam-ux.github.io/aging_clock_bench/faq/#how-do-i-add-a-new-clock).
+
+---
+
+## License
+
+MIT © Aaditya Geddam
+

agingclockbench-0.1.0/README.md

@@ -0,0 +1,147 @@
+# AgingClockBench
+
+[![PyPI version](https://badge.fury.io/py/agingclockbench.svg)](https://badge.fury.io/py/agingclockbench)
+[![Tests](https://github.com/aadityageddam-ux/aging_clock_bench/actions/workflows/test.yml/badge.svg)](https://github.com/aadityageddam-ux/aging_clock_bench/actions/workflows/test.yml)
+[![Coverage](https://img.shields.io/badge/coverage-89%25-brightgreen)](https://github.com/aadityageddam-ux/aging_clock_bench)
+[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://aadityageddam-ux.github.io/aging_clock_bench/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
+
+**Benchmark biological aging clocks on your data in minutes.**
+
+Multiple biological aging clocks exist — PhenoAge, KDM, DunedinPACE — but no standard tool lets researchers compare them side-by-side. AgingClockBench is the **first open-source Python package** implementing multiple clocks with a unified interface and reproducible mortality-validated benchmarking.
+
+📖 **[Full Documentation](https://aadityageddam-ux.github.io/aging_clock_bench/)**
+
+---
+
+## Install
+
+```bash
+pip install agingclockbench
+```
+
+Requires Python 3.11+.
+
+---
+
+## Quick Start
+
+```python
+from agingclockbench import PhenoAge, KDM, BenchmarkSuite
+from agingclockbench.datasets import load_nhanes_sample
+
+# Load bundled NHANES 1999-2000 (N=4,086, 20-year mortality follow-up)
+df = load_nhanes_sample()
+
+# Compute biological ages
+results = {
+    "PhenoAge": PhenoAge().transform(df),
+    "KDM":      KDM().transform(df),
+}
+
+# Benchmark against mortality
+suite = BenchmarkSuite(mortality_col="mortstat", followup_col="permth_exm")
+report = suite.run(df, results)
+
+print(report.to_dataframe())
+```
+
+```
+Clock     Pearson r  Mort HR (per SD accel)  Mort p-value
+PhenoAge      0.930                    1.83      0.000001
+KDM           0.677                    1.41      0.000001
+```
+
+```python
+report.plot_km_survival()      # Kaplan-Meier by acceleration quartile
+report.plot_comparison()       # biological age vs chronological age
+report.to_html("report.html")  # interactive Plotly report
+```
+
+---
+
+## CLI
+
+```bash
+# Benchmark on bundled NHANES with HTML report
+agingclockbench benchmark --data bundled --clocks all --report
+
+# Your own data
+agingclockbench benchmark \
+  --data my_cohort.csv \
+  --clocks PhenoAge KDM \
+  --mortality-col vital_status \
+  --followup-col followup_months \
+  --output ./results/
+```
+
+---
+
+## Implemented Clocks
+
+| Clock | Reference | Biomarkers | Key metric (NHANES) |
+|-------|-----------|-----------|---------------------|
+| **PhenoAge** | Levine et al. 2018 *Aging Cell* | 9 blood | Pearson r=0.93, HR=1.83 |
+| **KDM** | Klemera & Doubal 2006 *Mech Ageing Dev* | 8 blood | Pearson r=0.68, HR=1.41 |
+| **DunedinPACEProxy** | Proxy (NOT Belsky 2022) | 7 blood | pace corr w/ PhenoAge accel r=0.84 |
+
+> **Note:** DunedinPACEProxy is a blood-biomarker approximation. The real DunedinPACE requires DNA methylation data (Illumina EPIC array).
+
+---
+
+## Features
+
+- ✅ **Unified interface** — all clocks share the same `transform()` API
+- ✅ **Validated** — PhenoAge implementation cross-validated against reference; zero numerical difference on N=4,086 NHANES participants  
+- ✅ **Mortality benchmarking** — Cox PH hazard ratios, Kaplan-Meier curves
+- ✅ **Bundled data** — NHANES 1999-2000 with 20-year mortality follow-up, ready to use
+- ✅ **Interactive reports** — Plotly HTML with comparison plots and benchmark table
+- ✅ **CLI tool** — `agingclockbench benchmark` works out of the box
+- ✅ **89% test coverage** — 76+ tests, CI/CD on every push
+
+---
+
+## Documentation
+
+| Resource | Link |
+|----------|------|
+| Full docs | [aadityageddam-ux.github.io/aging_clock_bench](https://aadityageddam-ux.github.io/aging_clock_bench/) |
+| Quickstart | [docs/quickstart](https://aadityageddam-ux.github.io/aging_clock_bench/quickstart/) |
+| PhenoAge algorithm | [docs/algorithms/phenoage](https://aadityageddam-ux.github.io/aging_clock_bench/algorithms/phenoage/) |
+| FAQ | [docs/faq](https://aadityageddam-ux.github.io/aging_clock_bench/faq/) |
+| Example notebooks | [examples/](examples/) |
+
+---
+
+## Citation
+
+If you use AgingClockBench in your research, please cite:
+
+```bibtex
+@software{geddam2026agingclockbench,
+  author = {Geddam, Aaditya},
+  title  = {AgingClockBench: Benchmarking biological aging clocks},
+  url    = {https://github.com/aadityageddam-ux/aging_clock_bench},
+  year   = {2026}
+}
+```
+
+**Also cite the underlying clock papers:**
+
+- Levine ME, et al. *Aging Cell.* 2018. (PhenoAge)
+- Klemera P, Doubal S. *Mech Ageing Dev.* 2006. (KDM)
+
+---
+
+## Contributing
+
+Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+To add a new clock, implement the `BaseClock` interface — see the [FAQ](https://aadityageddam-ux.github.io/aging_clock_bench/faq/#how-do-i-add-a-new-clock).
+
+---
+
+## License
+
+MIT © Aaditya Geddam

agingclockbench-0.1.0/pyproject.toml

@@ -0,0 +1,76 @@
+[tool.poetry]
+name = "agingclockbench"
+version = "0.1.0"
+description = "Benchmark biological aging clocks on your data — PhenoAge, KDM, DunedinPACE proxy"
+authors = ["Aaditya Geddam <aaditya.geddam@gmail.com>"]
+license = "MIT"
+readme = "README.md"
+homepage = "https://aadityageddam-ux.github.io/aging_clock_bench/"
+repository = "https://github.com/aadityageddam-ux/aging_clock_bench"
+documentation = "https://aadityageddam-ux.github.io/aging_clock_bench/"
+keywords = ["aging", "biomarkers", "aging-clocks", "longevity", "biological-age",
+            "phenoage", "kdm", "nhanes", "mortality"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+    "Topic :: Scientific/Engineering :: Medical Science Apps.",
+]
+packages = [{include = "agingclockbench", from = "src"}]
+include = ["src/agingclockbench/datasets/nhanes_sample.parquet"]
+
+[tool.poetry.dependencies]
+python = "^3.11"
+pandas = ">=2.2.0"
+numpy = ">=1.26.0"
+scipy = ">=1.13.0"
+lifelines = ">=0.28.0"
+pydantic = ">=2.3.0"
+plotly = ">=5.17.0"
+seaborn = ">=0.13.0"
+matplotlib = ">=3.8.0"
+click = ">=8.1.0"
+pyarrow = ">=13.0.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "~7.4.0"
+pytest-cov = "~4.1.0"
+hypothesis = "~6.82.0"
+black = "~23.9.0"
+ruff = "~0.1.0"
+mypy = "~1.5.0"
+mkdocs = "~1.5.0"
+mkdocs-material = "~9.1.0"
+mkdocstrings = {version = ">=0.24.0", extras = ["python"]}
+
+[tool.poetry.scripts]
+agingclockbench = "agingclockbench.cli:cli"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.black]
+line-length = 88
+target-version = ["py311"]
+
+[tool.ruff]
+line-length = 88
+select = ["E", "F", "W", "I"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = false
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v"
+
+[tool.coverage.run]
+source = ["src/agingclockbench"]
+omit = ["*/tests/*", "*/__init__.py"]

agingclockbench-0.1.0/src/agingclockbench/__init__.py

@@ -0,0 +1,9 @@
+"""AgingClockBench: Benchmark biological aging clocks on your data."""
+
+from agingclockbench.clocks.phenoage import PhenoAge
+from agingclockbench.clocks.kdm import KDM
+from agingclockbench.clocks.dunedinpace import DunedinPACEProxy
+from agingclockbench.benchmarks.suite import BenchmarkSuite
+
+__version__ = "0.1.0"
+__all__ = ["PhenoAge", "KDM", "DunedinPACEProxy", "BenchmarkSuite"]

agingclockbench-0.1.0/src/agingclockbench/benchmarks/__init__.py

@@ -0,0 +1,3 @@
+from agingclockbench.benchmarks.suite import BenchmarkSuite, BenchmarkResult, BenchmarkReport
+
+__all__ = ["BenchmarkSuite", "BenchmarkResult", "BenchmarkReport"]

agingclockbench-0.1.0/src/agingclockbench/benchmarks/metrics.py

@@ -0,0 +1,22 @@
+"""Individual metric functions used by BenchmarkSuite."""
+
+import numpy as np
+import pandas as pd
+from scipy import stats
+
+
+def pearson_correlation(x: pd.Series, y: pd.Series) -> tuple[float, float]:
+    """Return (r, p-value) Pearson correlation between x and y."""
+    r, p = stats.pearsonr(x, y)
+    return float(r), float(p)
+
+
+def spearman_correlation(x: pd.Series, y: pd.Series) -> float:
+    """Return Spearman rho between x and y."""
+    return float(stats.spearmanr(x, y).statistic)
+
+
+def coefficient_of_variation(series: pd.Series) -> float:
+    """Return coefficient of variation (SD / mean)."""
+    mean = series.mean()
+    return float(series.std() / mean) if mean != 0 else float("nan")