README.md

---
license: other
library_name: pyaging
tags:
  - biology
  - aging
  - biological-age
  - pytorch
---

# pyaging data

This public repository contains the model weights and data files used by
[`lucascamillomd/pyaging`](https://github.com/lucascamillomd/pyaging).

## Contents

- Clock model weights live in one repository per clock under the
  [`pyaging` organization](https://huggingface.co/pyaging) (e.g.
  `pyaging/horvath2013`); each repo carries the weight file, the audited clock
  metadata as `config.json`, and a model card. Root-level `*.pt` files here are
  compatibility copies used when a per-clock repository or revision is unavailable.
- `all_clock_metadata.pt` is the live aggregate clock catalog. Retired clock files
  may remain here to preserve earlier releases; file presence is not current catalogue membership.
- Root-level example files support the pyaging tutorials.
- `PAD000022_subset.pkl` contains 32 real plasma samples and 134 Olink Explore
  3072 assays for the OrganAge tutorial. Its [data card](PAD000022_README.md)
  documents the CC0 source, selection, normalization and limitations.
- `supporting_files/` contains dependencies used to construct or document clocks.

Files used by the Python package are intentionally stored at the repository root and
downloaded through the standard Hugging Face cache.
The `main` branch is the live data release and may change independently of the Python
package version.

## Versioning and reproducibility

Each pyaging release tags this repository with the matching package version (e.g.
`v0.3.1`), so a release tag captures the exact data files that shipped with that
version of the package. By default pyaging downloads from `main`; set the
`PYAGING_DATA_REVISION` environment variable to a release tag (or any commit) to pin
downloads to that revision:

```bash
PYAGING_DATA_REVISION=v0.3.1 python my_analysis.py
```

Release tags only exist for pyaging versions published after the tagging scheme was
introduced.

## Harmonized clock metadata

The clock catalogue uses controlled, multi-valued metadata so clocks can be
filtered consistently:

- `tissue` records the biological material used to develop or train the model.
- `platform` records the measurement platform used for model development.
- `predicts` describes how to interpret the value returned by the packaged
  model.
- `training_target` records the outcome used to fit or derive the model.
- `unit` records the physical or statistical unit of the returned,
  postprocessed value.

Each of these fields is an array of controlled terms, even when a clock has only
one value. Precise wording from the paper, supplement, implementation, or author
communication is retained in the notebooks' same-line metadata comments and in
the field-level evidence ledger. The canonical
[`clock_metadata.json`](https://github.com/lucascamillomd/pyaging/blob/main/clocks/metadata/clock_metadata.json)
registry and
[`evidence_ledger.jsonl`](https://github.com/lucascamillomd/pyaging/blob/main/clocks/metadata/evidence_ledger.jsonl)
are maintained in the pyaging repository.

## Clinical PhenoAge correction

Use **pyaging >=0.5.7** for clinical `phenoage`. The corrected Gompertz parameter
is `gamma = 0.0076927`; earlier package versions used the Cox variable-selection
penalty `0.0192` instead. That inflated finite estimates by approximately
9.619365 years for the same log hazard. Recalculate prior clinical PhenoAge
results after upgrading. The formula is implemented in the Python class, so a
new weight download alone cannot fix an older package. DNAm PhenoAge and the
separately fitted Sao Paulo model are unaffected. The
[original supplementary methods](https://cdn.aging-us.com/article/101414/supplementary/SD1/0/aging-v10i4-101414-supplementary-material-SD1.pdf)
distinguish the two parameters on pages 1 and 2.

## Licensing and provenance

This is a mixed-provenance research collection, so the repository license is `other`.
The pyaging MIT license does not grant additional rights to third-party clock weights or
source datasets. Consult each clock's embedded metadata, cited publication, and notes
before use. Some clocks are marked research-only or have separate commercial terms.

## Security

Clock files are trusted Python/PyTorch objects loaded by pyaging with
`torch.load(..., weights_only=False)`. Loading a malicious pickle can execute code. Only
load these files from this official repository and review unexpected repository changes.

## Publishing policy

The repository is maintained solely by Lucas Paulo de Lima Camillo (`lucascamillomd`).
Weights are uploaded before aggregate metadata so the catalog never advertises a missing
clock file. Public users need no Hugging Face token to download files.

## Proteomic inputs

The 0.5.6 catalogue contains HPS, PAOPAC Conventional, PAC and 46 full Olink
Explore 3072 OrganAge models. Their input units and protein identifiers are
model-specific. OrganAge uses case-sensitive original symbols; HPS and PAC use
lowercase symbols plus age in years. PAOPAC follows its original interface's
NPX exponentiation, cohort standardization and LOWESS age-bias correction. Its
predictions depend on the submitted cohort and require chronological age.
NPX is log2 relative abundance, not concentration; cross-platform and serum/plasma
harmonization are external preparation decisions. See the
[proteomics tutorial](https://pyaging.readthedocs.io/en/latest/tutorials/tutorial_proteomics.html).

The reduced Olink Explore 1536 OrganAge models leave the current catalogue, and
full-model names drop `olink3000`. Existing 0.5.4 tags and files remain intact.
ProtAge and ipfP3GPT are not executable pyaging entries in this release; the
guide explains the unavailable or restricted author assets. HPS returns a
0–1 healthspan probability (higher is healthier), not an age in years.