agingclockbench 0.1.0__py3-none-any.whl

agingclockbench/datasets/__init__.py

@@ -0,0 +1,3 @@
+from agingclockbench.datasets.loaders import load_nhanes_sample
+
+__all__ = ["load_nhanes_sample"]

agingclockbench/datasets/loaders.py

@@ -0,0 +1,54 @@
+"""Dataset loaders for bundled reference data."""
+
+from pathlib import Path
+
+import pandas as pd
+
+_DATA_DIR = Path(__file__).parent
+
+
+def load_nhanes_sample() -> pd.DataFrame:
+    """Load the bundled NHANES 1999-2000 sample (N=4,086 complete cases).
+
+    Source: CDC National Health and Nutrition Examination Survey 1999-2000,
+    with mortality linkage from NCHS Public-Use Linked Mortality Files.
+    All biomarkers are complete (no missing values). Participants are 20-85 years
+    old.
+
+    Columns
+    -------
+    seqn             : int   — NHANES participant sequence number
+    age              : float — chronological age in years
+    sex              : str   — 'male' or 'female'
+    albumin_g_dl     : float — albumin (g/dL)
+    creatinine_mg_dl : float — creatinine (mg/dL)
+    glucose_mg_dl    : float — glucose (mg/dL)
+    crp_mg_l         : float — C-reactive protein (mg/L)
+    lymphocyte_pct   : float — lymphocyte percentage (%)
+    mcv_fl           : float — mean corpuscular volume (fL)
+    rdw_pct          : float — red cell distribution width (%)
+    alp_u_l          : float — alkaline phosphatase (U/L)
+    wbc_k_ul         : float — white blood cell count (10³/μL)
+    mortstat         : int   — vital status at follow-up (1=deceased, 0=alive/censored)
+    permth_exm       : float — months from examination to death or censoring
+
+    Returns
+    -------
+    pd.DataFrame with 4,086 rows and 14 columns.
+
+    Examples
+    --------
+    >>> df = load_nhanes_sample()
+    >>> len(df)
+    4086
+    >>> list(df.columns[:4])
+    ['seqn', 'age', 'sex', 'albumin_g_dl']
+    """
+    parquet_path = _DATA_DIR / "nhanes_sample.parquet"
+    if not parquet_path.exists():
+        raise FileNotFoundError(
+            f"Bundled NHANES sample not found at {parquet_path}.\n"
+            "This file should be included in the installed package. "
+            "If you installed from source, run: python -m agingclockbench.datasets.build"
+        )
+    return pd.read_parquet(parquet_path)

agingclockbench/utils/__init__.py

@@ -0,0 +1,3 @@
+from agingclockbench.utils.validation import validate_dataframe
+
+__all__ = ["validate_dataframe"]

agingclockbench/utils/validation.py

@@ -0,0 +1,10 @@
+"""Input validation helpers."""
+
+import pandas as pd
+
+
+def validate_dataframe(df: pd.DataFrame, required_cols: list[str]) -> None:
+    """Raise ValueError if any required column is missing from df."""
+    missing = [c for c in required_cols if c not in df.columns]
+    if missing:
+        raise ValueError(f"Input DataFrame is missing columns: {missing}")

agingclockbench-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,22 @@
+agingclockbench/__init__.py,sha256=g3RTmbyvlBvHY_vNY99QqWIlbxWLYw3qTGmtospxcjk,383
+agingclockbench/benchmarks/__init__.py,sha256=wwd4cyk88Sg9RCNxRLsOVd77FbHOvP-XTwnivWkrYqo,162
+agingclockbench/benchmarks/metrics.py,sha256=t-CHTmTMjDg4t8zCHQvQrpDPiwD8-fc9gPEU5qzw5NQ,700
+agingclockbench/benchmarks/plots.py,sha256=sddHj759tq7_hFaZMhg3TUNZAKXhrnfsCbALL95zjds,9655
+agingclockbench/benchmarks/suite.py,sha256=mWu4uVFLk8KmJGi0pYeEN1QCoq40QV3NauC4BvSfFJ0,9641
+agingclockbench/cli.py,sha256=YDLeYfDI_bVZTAZxdy1XAnjF9QihaLGKgz6QoxsWYXo,5650
+agingclockbench/clocks/__init__.py,sha256=io2YgI0K8ZI9fPHYAInl21GPLGk1HNfl8MtSlVOf4x8,302
+agingclockbench/clocks/base.py,sha256=ZXj1AAYRZjszgf98SvQ6nNCUyrep_S0nRee2u8-KZeY,1487
+agingclockbench/clocks/dunedinpace.py,sha256=srkBPrsjNfxs5h6tE4qLDA3VNoGgwU4hSGWcMb0KuwY,5639
+agingclockbench/clocks/kdm.py,sha256=rZoh-WQVQ2dElVJFf_jKP6EpqLwBPV7bi6DaWnaRqlM,7067
+agingclockbench/clocks/phenoage.py,sha256=c6yNBOlpsLsqama53BuvUDZp-xHFnBNQ6pquBwgVVZg,5865
+agingclockbench/config.py,sha256=H44ipvRA9k2B8vMcygbpTLQOUaP-FlQ7Q7fO9cUjZVw,101
+agingclockbench/datasets/__init__.py,sha256=LdhvZbM4SaYzejba8GX2iSJ32dmfN7J-pfXgR-yNHKc,98
+agingclockbench/datasets/loaders.py,sha256=ARoJmzH1-FIo1nOV5IrvhAa-AeaBfBMBDwISuDEqLgs,2026
+agingclockbench/datasets/nhanes_sample.parquet,sha256=wq4b8DplDuQ0ptJ8IDXkLJMgVQsvFjHgbrH6DPn9qSc,83940
+agingclockbench/utils/__init__.py,sha256=zixmsyfK5er4Td5ojGjjHVivwE2re0OJwiQCkYMXdHc,98
+agingclockbench/utils/validation.py,sha256=EUL5wALV0rVBbI8VetrO-ANx_cgyP0qlRsYGVGemLeY,356
+agingclockbench-0.1.0.dist-info/METADATA,sha256=-JzlkaNX983dwNiJVCahUaVgg1utAC180cCl6ofu-E4,6550
+agingclockbench-0.1.0.dist-info/WHEEL,sha256=EGEvSphFYqXKs23-kQBeyNoJP1nrT8ZJKQoi5p5DYL8,88
+agingclockbench-0.1.0.dist-info/entry_points.txt,sha256=6noLfhRpuq6EkoSsCyV56xnG_daYauXFjhHrTT9ibLw,59
+agingclockbench-0.1.0.dist-info/licenses/LICENSE,sha256=_chuVHJJdKuUZ2igQszY3gJmce-B5nr6I1tTo5F1xOs,1079
+agingclockbench-0.1.0.dist-info/RECORD,,

agingclockbench-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.4.0
+Root-Is-Purelib: true
+Tag: py3-none-any

agingclockbench-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+agingclockbench=agingclockbench.cli:cli
+

agingclockbench-0.1.0.dist-info/licenses/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.