pyaging 0.4.0__tar.gz → 0.5.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (28) hide show
  1. {pyaging-0.4.0 → pyaging-0.5.0}/.gitignore +1 -0
  2. {pyaging-0.4.0 → pyaging-0.5.0}/PKG-INFO +2 -2
  3. {pyaging-0.4.0 → pyaging-0.5.0}/README.md +1 -1
  4. {pyaging-0.4.0 → pyaging-0.5.0}/src/pyaging/__init__.py +1 -1
  5. pyaging-0.5.0/src/pyaging/data/feature_ranges.json +143 -0
  6. {pyaging-0.4.0 → pyaging-0.5.0}/src/pyaging/logger/_live.py +0 -5
  7. {pyaging-0.4.0 → pyaging-0.5.0}/src/pyaging/logger/_logger.py +2 -7
  8. {pyaging-0.4.0 → pyaging-0.5.0}/src/pyaging/models/__init__.py +8 -0
  9. {pyaging-0.4.0 → pyaging-0.5.0}/src/pyaging/models/_base_models.py +1 -0
  10. {pyaging-0.4.0 → pyaging-0.5.0}/src/pyaging/models/_models.py +279 -1
  11. {pyaging-0.4.0 → pyaging-0.5.0}/src/pyaging/predict/__init__.py +4 -0
  12. {pyaging-0.4.0 → pyaging-0.5.0}/src/pyaging/predict/_inverse_transforms.py +31 -0
  13. {pyaging-0.4.0 → pyaging-0.5.0}/src/pyaging/predict/_pred.py +5 -0
  14. {pyaging-0.4.0 → pyaging-0.5.0}/src/pyaging/predict/_pred_utils.py +148 -0
  15. {pyaging-0.4.0 → pyaging-0.5.0}/src/pyaging/predict/_transforms.py +57 -0
  16. {pyaging-0.4.0 → pyaging-0.5.0}/src/pyaging/preprocess/_preprocess_utils.py +2 -2
  17. {pyaging-0.4.0 → pyaging-0.5.0}/src/pyaging/utils/__init__.py +3 -0
  18. pyaging-0.5.0/src/pyaging/utils/_feature_ranges.py +165 -0
  19. {pyaging-0.4.0 → pyaging-0.5.0}/src/pyaging/utils/_hf.py +3 -3
  20. {pyaging-0.4.0 → pyaging-0.5.0}/src/pyaging/utils/_utils.py +4 -5
  21. {pyaging-0.4.0 → pyaging-0.5.0}/LICENSE +0 -0
  22. {pyaging-0.4.0 → pyaging-0.5.0}/pyproject.toml +0 -0
  23. {pyaging-0.4.0 → pyaging-0.5.0}/src/pyaging/data/__init__.py +0 -0
  24. {pyaging-0.4.0 → pyaging-0.5.0}/src/pyaging/data/_data.py +0 -0
  25. {pyaging-0.4.0 → pyaging-0.5.0}/src/pyaging/logger/__init__.py +0 -0
  26. {pyaging-0.4.0 → pyaging-0.5.0}/src/pyaging/preprocess/__init__.py +0 -0
  27. {pyaging-0.4.0 → pyaging-0.5.0}/src/pyaging/preprocess/_preprocess.py +0 -0
  28. {pyaging-0.4.0 → pyaging-0.5.0}/src/pyaging/py.typed +0 -0
@@ -59,3 +59,4 @@ docs/source/clock_notebooks/
59
59
 
60
60
  # Local scratch
61
61
  tmp/
62
+ /data/
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: pyaging
3
- Version: 0.4.0
3
+ Version: 0.5.0
4
4
  Summary: A Python-based compendium of GPU-optimized aging clocks.
5
5
  Project-URL: homepage, https://github.com/lucascamillomd/pyaging
6
6
  Project-URL: repository, https://github.com/lucascamillomd/pyaging
@@ -89,7 +89,7 @@ If you have recently developed an aging clock and would like it to be integrated
89
89
  For coding-related queries, feedback, and discussions, please visit our [GitHub Issues](https://github.com/lucascamillomd/pyaging/issues) page.
90
90
 
91
91
  ## 📝 Changelog
92
- Release notes for each version are available on the [GitHub Releases](https://github.com/lucascamillomd/pyaging/releases) page.
92
+ Notable changes, including breaking ones, are recorded in [`CHANGELOG.md`](https://github.com/lucascamillomd/pyaging/blob/main/CHANGELOG.md). Per-version release artifacts and the commit log are on the [GitHub Releases](https://github.com/lucascamillomd/pyaging/releases) page.
93
93
 
94
94
  ## 📖 Citation
95
95
 
@@ -58,7 +58,7 @@ If you have recently developed an aging clock and would like it to be integrated
58
58
  For coding-related queries, feedback, and discussions, please visit our [GitHub Issues](https://github.com/lucascamillomd/pyaging/issues) page.
59
59
 
60
60
  ## 📝 Changelog
61
- Release notes for each version are available on the [GitHub Releases](https://github.com/lucascamillomd/pyaging/releases) page.
61
+ Notable changes, including breaking ones, are recorded in [`CHANGELOG.md`](https://github.com/lucascamillomd/pyaging/blob/main/CHANGELOG.md). Per-version release artifacts and the commit log are on the [GitHub Releases](https://github.com/lucascamillomd/pyaging/releases) page.
62
62
 
63
63
  ## 📖 Citation
64
64
 
@@ -4,4 +4,4 @@ from . import data, logger, models, utils
4
4
  from . import predict as pred
5
5
  from . import preprocess as pp
6
6
 
7
- __version__ = "0.4.0"
7
+ __version__ = "0.5.0"
@@ -0,0 +1,143 @@
1
+ {
2
+ "schema_version": 1,
3
+ "modality_defaults": {
4
+ "DNA methylation": {"unit": "beta value", "low": 0.0, "high": 1.0},
5
+ "transcriptomics": {"unit": null, "low": 0.0, "high": null},
6
+ "histone modification": {"unit": null, "low": 0.0, "high": null},
7
+ "chromatin accessibility": {"unit": null, "low": 0.0, "high": null}
8
+ },
9
+ "features": {
10
+ "age": {"unit": "years", "low": 0.0, "high": 122.5},
11
+ "female": {"unit": "indicator (1 = female, 0 = male)", "low": 0.0, "high": 1.0},
12
+ "alanine_aminotransferase": {"unit": "U/L", "low": 1.0, "high": 10000.0},
13
+ "albumin": {"unit": "g/L", "low": 10.0, "high": 70.0},
14
+ "alkaline_phosphatase": {"unit": "U/L", "low": 5.0, "high": 5000.0},
15
+ "aspartate_aminotransferase": {"unit": "U/L", "low": 1.0, "high": 10000.0},
16
+ "basophil_count": {"unit": "10^3 cells/uL", "low": 0.0, "high": 100.0},
17
+ "basophil_percent": {"unit": "%", "low": 0.0, "high": 100.0},
18
+ "bicarbonate": {"unit": "mmol/L", "low": 5.0, "high": 50.0},
19
+ "blood_urea_nitrogen": {"unit": "mmol/L", "low": 0.5, "high": 60.0},
20
+ "body_mass_index": {"unit": "kg/m^2", "low": 8.0, "high": 100.0},
21
+ "c_reactive_protein": {"unit": "mg/dL", "low": 0.01, "high": 50.0},
22
+ "calcium": {"unit": "mmol/L", "low": 1.0, "high": 5.0},
23
+ "chloride": {"unit": "mmol/L", "low": 60.0, "high": 140.0},
24
+ "comorbidity_index": {"unit": "fraction of 22 reported conditions", "low": 0.0, "high": 1.0},
25
+ "confusion_or_memory_problems": {"unit": "NHANES yes/no code (1 = yes, 2 = no, 7 = refused, 9 = don't know)", "low": 1.0, "high": 9.0},
26
+ "cotinine": {"unit": "ng/mL", "low": 0.0, "high": 2000.0},
27
+ "cpgpt_calb2": {"unit": "z-score of a DNAm-predicted plasma protein level", "low": -10.0, "high": 10.0},
28
+ "cpgpt_ccl14": {"unit": "z-score of a DNAm-predicted plasma protein level", "low": -10.0, "high": 10.0},
29
+ "cpgpt_ccl19": {"unit": "z-score of a DNAm-predicted plasma protein level", "low": -10.0, "high": 10.0},
30
+ "cpgpt_cd200": {"unit": "z-score of a DNAm-predicted plasma protein level", "low": -10.0, "high": 10.0},
31
+ "cpgpt_chit1": {"unit": "z-score of a DNAm-predicted plasma protein level", "low": -10.0, "high": 10.0},
32
+ "cpgpt_cst3": {"unit": "z-score of a DNAm-predicted plasma protein level", "low": -10.0, "high": 10.0},
33
+ "cpgpt_ctf1": {"unit": "z-score of a DNAm-predicted plasma protein level", "low": -10.0, "high": 10.0},
34
+ "cpgpt_cxcl2": {"unit": "z-score of a DNAm-predicted plasma protein level", "low": -10.0, "high": 10.0},
35
+ "cpgpt_faslg": {"unit": "z-score of a DNAm-predicted plasma protein level", "low": -10.0, "high": 10.0},
36
+ "cpgpt_gzma": {"unit": "z-score of a DNAm-predicted plasma protein level", "low": -10.0, "high": 10.0},
37
+ "cpgpt_il17ra": {"unit": "z-score of a DNAm-predicted plasma protein level", "low": -10.0, "high": 10.0},
38
+ "cpgpt_il1rn": {"unit": "z-score of a DNAm-predicted plasma protein level", "low": -10.0, "high": 10.0},
39
+ "cpgpt_il20": {"unit": "z-score of a DNAm-predicted plasma protein level", "low": -10.0, "high": 10.0},
40
+ "cpgpt_il34": {"unit": "z-score of a DNAm-predicted plasma protein level", "low": -10.0, "high": 10.0},
41
+ "cpgpt_il5": {"unit": "z-score of a DNAm-predicted plasma protein level", "low": -10.0, "high": 10.0},
42
+ "cpgpt_il6r": {"unit": "z-score of a DNAm-predicted plasma protein level", "low": -10.0, "high": 10.0},
43
+ "cpgpt_lilrb2": {"unit": "z-score of a DNAm-predicted plasma protein level", "low": -10.0, "high": 10.0},
44
+ "cpgpt_nampt": {"unit": "z-score of a DNAm-predicted plasma protein level", "low": -10.0, "high": 10.0},
45
+ "cpgpt_pdcd1": {"unit": "z-score of a DNAm-predicted plasma protein level", "low": -10.0, "high": 10.0},
46
+ "cpgpt_pdgfa": {"unit": "z-score of a DNAm-predicted plasma protein level", "low": -10.0, "high": 10.0},
47
+ "cpgpt_postn": {"unit": "z-score of a DNAm-predicted plasma protein level", "low": -10.0, "high": 10.0},
48
+ "cpgpt_s100a9": {"unit": "z-score of a DNAm-predicted plasma protein level", "low": -10.0, "high": 10.0},
49
+ "cpgpt_sdc1": {"unit": "z-score of a DNAm-predicted plasma protein level", "low": -10.0, "high": 10.0},
50
+ "cpgpt_snap25": {"unit": "z-score of a DNAm-predicted plasma protein level", "low": -10.0, "high": 10.0},
51
+ "cpgpt_tek": {"unit": "z-score of a DNAm-predicted plasma protein level", "low": -10.0, "high": 10.0},
52
+ "cpgpt_tgfb1": {"unit": "z-score of a DNAm-predicted plasma protein level", "low": -10.0, "high": 10.0},
53
+ "cpgpt_timp1": {"unit": "z-score of a DNAm-predicted plasma protein level", "low": -10.0, "high": 10.0},
54
+ "cpgpt_timp3": {"unit": "z-score of a DNAm-predicted plasma protein level", "low": -10.0, "high": 10.0},
55
+ "cpgpt_tnf": {"unit": "z-score of a DNAm-predicted plasma protein level", "low": -10.0, "high": 10.0},
56
+ "cpgpt_tnfrsf13c": {"unit": "z-score of a DNAm-predicted plasma protein level", "low": -10.0, "high": 10.0},
57
+ "cpgpt_tnfsf15": {"unit": "z-score of a DNAm-predicted plasma protein level", "low": -10.0, "high": 10.0},
58
+ "creatinine": {"unit": "umol/L", "low": 10.0, "high": 3000.0},
59
+ "diastolic_blood_pressure": {"unit": "mmHg", "low": 20.0, "high": 200.0},
60
+ "eosinophil_count": {"unit": "10^3 cells/uL", "low": 0.0, "high": 100.0},
61
+ "eosinophil_percent": {"unit": "%", "low": 0.0, "high": 100.0},
62
+ "ferritin": {"unit": "ug/L", "low": 1.0, "high": 20000.0},
63
+ "folate": {"unit": "nmol/L", "low": 0.5, "high": 500.0},
64
+ "forced_expiratory_volume": {"unit": "L", "low": 0.1, "high": 8.0},
65
+ "fractured_hip": {"unit": "NHANES yes/no code (1 = yes, 2 = no, 7 = refused, 9 = don't know)", "low": 1.0, "high": 9.0},
66
+ "fractured_spine": {"unit": "NHANES yes/no code (1 = yes, 2 = no, 7 = refused, 9 = don't know)", "low": 1.0, "high": 9.0},
67
+ "fractured_wrist": {"unit": "NHANES yes/no code (1 = yes, 2 = no, 7 = refused, 9 = don't know)", "low": 1.0, "high": 9.0},
68
+ "general_health_condition": {"unit": "NHANES health code (1 = excellent, 5 = poor, 7 = refused, 9 = don't know)", "low": 1.0, "high": 9.0},
69
+ "globulin": {"unit": "g/L", "low": 5.0, "high": 70.0},
70
+ "glucose": {"unit": "mmol/L", "low": 1.0, "high": 60.0},
71
+ "grimage": {"unit": "years", "low": 0.0, "high": 150.0},
72
+ "grimage2adm": {"unit": "pg/mL", "low": 1.0, "high": 10000.0},
73
+ "grimage2b2m": {"unit": "pg/mL", "low": 100000.0, "high": 100000000.0},
74
+ "grimage2gdf15": {"unit": "pg/mL", "low": 10.0, "high": 100000.0},
75
+ "grimage2leptin": {"unit": "pg/mL", "low": 10.0, "high": 1000000.0},
76
+ "grimage2logcrp": {"unit": "natural log of mg/L", "low": -5.0, "high": 6.0},
77
+ "grimage2packyrs": {"unit": "pack-years", "low": -50.0, "high": 250.0},
78
+ "grimage2pai1": {"unit": "pg/mL", "low": 100.0, "high": 2000000.0},
79
+ "grimage2timp1": {"unit": "pg/mL", "low": 1000.0, "high": 5000000.0},
80
+ "hdl_cholesterol": {"unit": "mmol/L", "low": 0.1, "high": 5.0},
81
+ "health_compared_to_one_year_ago": {"unit": "NHANES change code (1 = better, 2 = worse, 3 = same, 7 = refused, 9 = don't know)", "low": 1.0, "high": 9.0},
82
+ "healthcare_use_index": {"unit": "NHANES visit-count code (0 = none, 8 = 16 or more)", "low": 0.0, "high": 8.0},
83
+ "healthcare_visits_past_year": {"unit": "NHANES visit-count code (0 = none, 8 = 16 or more, 77 = refused, 99 = don't know)", "low": 0.0, "high": 99.0},
84
+ "hematocrit": {"unit": "%", "low": 5.0, "high": 75.0},
85
+ "hemoglobin": {"unit": "g/dL", "low": 2.0, "high": 25.0},
86
+ "hemoglobin_a1c": {"unit": "%", "low": 2.0, "high": 20.0},
87
+ "hospital_overnight_past_year": {"unit": "NHANES yes/no code (1 = yes, 2 = no, 7 = refused, 9 = don't know)", "low": 1.0, "high": 9.0},
88
+ "iron": {"unit": "umol/L", "low": 1.0, "high": 120.0},
89
+ "lactate_dehydrogenase": {"unit": "U/L", "low": 20.0, "high": 5000.0},
90
+ "ldl_cholesterol": {"unit": "mmol/L", "low": 0.0, "high": 20.0},
91
+ "lymphocyte_count": {"unit": "10^3 cells/uL", "low": 0.0, "high": 500.0},
92
+ "lymphocyte_percent": {"unit": "%", "low": 0.0, "high": 100.0},
93
+ "mean_cell_hemoglobin": {"unit": "pg", "low": 10.0, "high": 60.0},
94
+ "mean_cell_hemoglobin_concentration": {"unit": "g/dL", "low": 20.0, "high": 45.0},
95
+ "mean_cell_volume": {"unit": "fL", "low": 40.0, "high": 150.0},
96
+ "mean_platelet_volume": {"unit": "fL", "low": 4.0, "high": 20.0},
97
+ "monocyte_count": {"unit": "10^3 cells/uL", "low": 0.0, "high": 100.0},
98
+ "monocyte_percent": {"unit": "%", "low": 0.0, "high": 100.0},
99
+ "neutrophil_count": {"unit": "10^3 cells/uL", "low": 0.0, "high": 500.0},
100
+ "neutrophil_percent": {"unit": "%", "low": 0.0, "high": 100.0},
101
+ "nt_probnp": {"unit": "pg/mL", "low": 0.001, "high": 100000.0},
102
+ "phosphorus": {"unit": "mmol/L", "low": 0.1, "high": 5.0},
103
+ "platelet_count": {"unit": "10^3 cells/uL", "low": 1.0, "high": 2000.0},
104
+ "potassium": {"unit": "mmol/L", "low": 1.5, "high": 10.0},
105
+ "pulse": {"unit": "bpm", "low": 20.0, "high": 250.0},
106
+ "red_blood_cell_count": {"unit": "10^6 cells/uL", "low": 1.0, "high": 10.0},
107
+ "red_cell_distribution_width": {"unit": "%", "low": 8.0, "high": 40.0},
108
+ "self_reported_health_index": {"unit": "score (0 = best, 8 = worst)", "low": 0.0, "high": 8.0},
109
+ "smoking_intensity": {"unit": "cotinine code (0 = none, 1 = light, 2 = moderate, 3 = heavy)", "low": 0.0, "high": 3.0},
110
+ "sodium": {"unit": "mmol/L", "low": 100.0, "high": 180.0},
111
+ "systolic_blood_pressure": {"unit": "mmHg", "low": 50.0, "high": 260.0},
112
+ "told_angina": {"unit": "NHANES yes/no code (1 = yes, 2 = no, 7 = refused, 9 = don't know)", "low": 1.0, "high": 9.0},
113
+ "told_arthritis": {"unit": "NHANES yes/no code (1 = yes, 2 = no, 7 = refused, 9 = don't know)", "low": 1.0, "high": 9.0},
114
+ "told_asthma": {"unit": "NHANES yes/no code (1 = yes, 2 = no, 7 = refused, 9 = don't know)", "low": 1.0, "high": 9.0},
115
+ "told_cancer": {"unit": "NHANES yes/no code (1 = yes, 2 = no, 7 = refused, 9 = don't know)", "low": 1.0, "high": 9.0},
116
+ "told_chronic_bronchitis": {"unit": "NHANES yes/no code (1 = yes, 2 = no, 7 = refused, 9 = don't know)", "low": 1.0, "high": 9.0},
117
+ "told_congestive_heart_failure": {"unit": "NHANES yes/no code (1 = yes, 2 = no, 7 = refused, 9 = don't know)", "low": 1.0, "high": 9.0},
118
+ "told_coronary_heart_disease": {"unit": "NHANES yes/no code (1 = yes, 2 = no, 7 = refused, 9 = don't know)", "low": 1.0, "high": 9.0},
119
+ "told_diabetes": {"unit": "NHANES diabetes code (1 = yes, 2 = no, 3 = borderline, 7 = refused, 9 = don't know)", "low": 1.0, "high": 9.0},
120
+ "told_emphysema": {"unit": "NHANES yes/no code (1 = yes, 2 = no, 7 = refused, 9 = don't know)", "low": 1.0, "high": 9.0},
121
+ "told_heart_attack": {"unit": "NHANES yes/no code (1 = yes, 2 = no, 7 = refused, 9 = don't know)", "low": 1.0, "high": 9.0},
122
+ "told_high_blood_pressure": {"unit": "NHANES yes/no code (1 = yes, 2 = no, 7 = refused, 9 = don't know)", "low": 1.0, "high": 9.0},
123
+ "told_liver_condition": {"unit": "NHANES yes/no code (1 = yes, 2 = no, 7 = refused, 9 = don't know)", "low": 1.0, "high": 9.0},
124
+ "told_osteoporosis": {"unit": "NHANES yes/no code (1 = yes, 2 = no, 7 = refused, 9 = don't know)", "low": 1.0, "high": 9.0},
125
+ "told_overweight": {"unit": "NHANES yes/no code (1 = yes, 2 = no, 7 = refused, 9 = don't know)", "low": 1.0, "high": 9.0},
126
+ "told_stroke": {"unit": "NHANES yes/no code (1 = yes, 2 = no, 7 = refused, 9 = don't know)", "low": 1.0, "high": 9.0},
127
+ "told_thyroid_disease": {"unit": "NHANES yes/no code (1 = yes, 2 = no, 7 = refused, 9 = don't know)", "low": 1.0, "high": 9.0},
128
+ "told_weak_or_failing_kidneys": {"unit": "NHANES yes/no code (1 = yes, 2 = no, 7 = refused, 9 = don't know)", "low": 1.0, "high": 9.0},
129
+ "total_bilirubin": {"unit": "umol/L", "low": 1.0, "high": 600.0},
130
+ "total_cholesterol": {"unit": "mmol/L", "low": 1.0, "high": 30.0},
131
+ "total_iron_binding_capacity": {"unit": "umol/L", "low": 10.0, "high": 200.0},
132
+ "total_protein": {"unit": "g/L", "low": 30.0, "high": 120.0},
133
+ "transferrin_saturation": {"unit": "%", "low": 0.0, "high": 100.0},
134
+ "treated_for_anemia_past_3_months": {"unit": "NHANES yes/no code (1 = yes, 2 = no, 7 = refused, 9 = don't know)", "low": 1.0, "high": 9.0},
135
+ "triglycerides": {"unit": "mmol/L", "low": 0.1, "high": 60.0},
136
+ "uric_acid": {"unit": "umol/L", "low": 50.0, "high": 1200.0},
137
+ "urine_albumin": {"unit": "mg/L", "low": 0.1, "high": 20000.0},
138
+ "urine_albumin_creatinine_ratio": {"unit": "mg/g", "low": 0.0, "high": 100000.0},
139
+ "urine_creatinine": {"unit": "umol/L", "low": 50.0, "high": 300000.0},
140
+ "vitamin_b12": {"unit": "pmol/L", "low": 20.0, "high": 10000.0},
141
+ "white_blood_cell_count": {"unit": "10^3 cells/uL", "low": 0.05, "high": 500.0}
142
+ }
143
+ }
@@ -100,11 +100,6 @@ class Shimmer:
100
100
  return Measurement(width, width)
101
101
 
102
102
 
103
- def get_console() -> Console:
104
- """The console the live display prints to (theme-aware in notebooks)."""
105
- return _console
106
-
107
-
108
103
  def display_enabled(verbose) -> bool:
109
104
  """Whether the display should render at all (False means fully silent)."""
110
105
  return bool(verbose)
@@ -57,8 +57,6 @@ class Logger:
57
57
  self.warning_logged = False
58
58
  self.report_hook_percent_state = None
59
59
  self.indent_level = 1
60
- # TODO add file handler in future
61
- # e.g. logging.StreamHandler(None) if log_file_path is None else logging.FileHandler(name)
62
60
 
63
61
  # ensure only one stream handler exists in one logger instance
64
62
  if len(self.logger.handlers) == 0:
@@ -265,7 +263,7 @@ class Logger:
265
263
  saved_terminator = self.logger_stream_handler.terminator
266
264
  self.logger_stream_handler.terminator = ""
267
265
  self.logger_stream_handler.flush()
268
- self.logger_stream_handler.terminator = saved_terminator #
266
+ self.logger_stream_handler.terminator = saved_terminator
269
267
 
270
268
  token = "⚠️" if self.warning_logged else "✅"
271
269
 
@@ -281,9 +279,8 @@ class Logger:
281
279
  )
282
280
  else:
283
281
  raise NotImplementedError
284
- # self.logger.info("|")
285
282
  self.logger_stream_handler.flush()
286
- self.warning_logged = False #
283
+ self.warning_logged = False
287
284
 
288
285
  def request_report_hook(self, bn: int, rs: int, ts: int) -> None:
289
286
  """A callback required by the request lib:
@@ -313,7 +310,6 @@ class Logger:
313
310
  if rs * bn >= ts:
314
311
  self.report_hook_percent_state = None
315
312
  self.report_progress(count=100, total=100, indent_level=self.indent_level) # 100%
316
- # self.finish_progress(progress_name="download")
317
313
 
318
314
 
319
315
  class LoggerManager:
@@ -358,7 +354,6 @@ class LoggerManager:
358
354
  )
359
355
  prev_progress_percent = new_progress_percent
360
356
  yield next(iterator)
361
- # logger.finish_progress(progress_name=progress_name, indent_level=indent_level)
362
357
 
363
358
 
364
359
  def main_info(message, indent_level=1):
@@ -72,15 +72,18 @@ from ._models import (
72
72
  Hannum,
73
73
  Hep,
74
74
  HepatoXu,
75
+ HomeostaticDysregulation,
75
76
  Horvath2013,
76
77
  HRSInCHPhenoAge,
77
78
  HypoClock,
78
79
  IntrinClock,
80
+ KDMAge,
79
81
  Knight,
80
82
  LeeControl,
81
83
  LeeRefinedRobust,
82
84
  LeeRobust,
83
85
  Lin,
86
+ LinAge2,
84
87
  LinearReferenceClock,
85
88
  Mammalian1,
86
89
  Mammalian2,
@@ -117,6 +120,7 @@ from ._models import (
117
120
  PedBE,
118
121
  Petkovich,
119
122
  PhenoAge,
123
+ PhenoAgeSaoPaulo,
120
124
  PipekElasticNet,
121
125
  PipekFilteredH,
122
126
  PipekRetrainedH,
@@ -238,14 +242,17 @@ __all__ = [
238
242
  "Hannum",
239
243
  "Hep",
240
244
  "HepatoXu",
245
+ "HomeostaticDysregulation",
241
246
  "Horvath2013",
242
247
  "HypoClock",
243
248
  "IntrinClock",
249
+ "KDMAge",
244
250
  "Knight",
245
251
  "LeeControl",
246
252
  "LeeRefinedRobust",
247
253
  "LeeRobust",
248
254
  "Lin",
255
+ "LinAge2",
249
256
  "LinearModel",
250
257
  "LinearReferenceClock",
251
258
  "Mammalian1",
@@ -284,6 +291,7 @@ __all__ = [
284
291
  "PedBE",
285
292
  "Petkovich",
286
293
  "PhenoAge",
294
+ "PhenoAgeSaoPaulo",
287
295
  "PipekElasticNet",
288
296
  "PipekFilteredH",
289
297
  "PipekRetrainedH",
@@ -31,6 +31,7 @@ class pyagingModel(nn.Module, ABC):
31
31
  self.postprocess_dependencies = None
32
32
 
33
33
  self.features = None
34
+ self.feature_units = None
34
35
  self.base_model_features = self.features
35
36
 
36
37
  self.base_model = None
@@ -1,8 +1,47 @@
1
+ import math
2
+
1
3
  import torch
2
4
  import torch.nn as nn
3
5
 
6
+ # ``predict/_pred_utils`` imports ``..models`` in turn, so these two lines close a cycle.
7
+ # It holds because ``_pred_utils`` only takes names ``models/__init__`` has already bound
8
+ # from ``_base_models`` by the time this module runs; importing a name defined here would
9
+ # break it.
10
+ from ..predict._inverse_transforms import mortality_to_phenoage_saopaulo
11
+ from ..predict._transforms import PHENOAGE_CRP_FLOOR_MG_DL, crp_index, log1p_crp
4
12
  from ._base_models import pyagingModel
5
13
 
14
+ # LinAge2's ``foldOutliers`` cap, in MAD-scaled z units, applied to every feature.
15
+ LINAGE2_FOLD_CAP = 6
16
+
17
+ # The 22 yes/no items ``popPCFIfs1`` sums into fs1Score, which is also the denominator.
18
+ # ``told_congestive_heart_failure`` (MCQ160B) is read by the reference and then never
19
+ # used, so it is absent here on purpose and the divisor stays 22.
20
+ LINAGE2_COMORBIDITY_ITEMS = (
21
+ "told_high_blood_pressure",
22
+ "told_diabetes",
23
+ "told_weak_or_failing_kidneys",
24
+ "told_asthma",
25
+ "treated_for_anemia_past_3_months",
26
+ "told_arthritis",
27
+ "told_coronary_heart_disease",
28
+ "told_angina",
29
+ "told_heart_attack",
30
+ "told_stroke",
31
+ "told_emphysema",
32
+ "told_thyroid_disease",
33
+ "told_overweight",
34
+ "told_chronic_bronchitis",
35
+ "told_liver_condition",
36
+ "told_cancer",
37
+ "fractured_hip",
38
+ "fractured_wrist",
39
+ "fractured_spine",
40
+ "told_osteoporosis",
41
+ "confusion_or_memory_problems",
42
+ "hospital_overnight_past_year",
43
+ )
44
+
6
45
 
7
46
  class AltumAge(pyagingModel):
8
47
  def __init__(self):
@@ -411,6 +450,81 @@ class HRSInCHPhenoAge(pyagingModel):
411
450
  return x
412
451
 
413
452
 
453
+ class HomeostaticDysregulation(pyagingModel):
454
+ """Mahalanobis distance from a young, healthy NHANES III reference cohort."""
455
+
456
+ def __init__(self):
457
+ super().__init__()
458
+ for sex in ["male", "female"]:
459
+ for name in ["reference_mean", "reference_sd", "center", "precision", "log_hd_sd"]:
460
+ self.register_buffer(f"{name}_{sex}", torch.empty(0))
461
+
462
+ def preprocess(self, x):
463
+ return log1p_crp(self.features, x)
464
+
465
+ def postprocess(self, x):
466
+ """Score the log Mahalanobis distance from the sex's reference cohort.
467
+
468
+ Notes
469
+ -----
470
+ ``center`` is not zero. ``hd_calc`` takes each column's mean and standard
471
+ deviation with ``na.rm = TRUE`` over the full reference column and drops
472
+ incomplete rows only afterwards, so the surviving rows' mean is not the
473
+ centring constant; the residual offset reaches 0.19 standard deviations
474
+ and is what ``center`` holds.
475
+
476
+ The distance is divided by the projection cohort's standard deviation of
477
+ ``log(distance)``, which is how ``hd_nhanes`` reports it. That constant is
478
+ stored per sex so a single sample can be scored without a cohort.
479
+ """
480
+ biomarkers, female = x[:, :-1], x[:, -1]
481
+
482
+ def score(sex):
483
+ mean, sd, center, precision, log_hd_sd = (
484
+ getattr(self, f"{name}_{sex}").to(device=x.device, dtype=x.dtype)
485
+ for name in ("reference_mean", "reference_sd", "center", "precision", "log_hd_sd")
486
+ )
487
+ deviation = (biomarkers - mean) / sd - center
488
+ squared = (deviation @ precision * deviation).sum(dim=1)
489
+ return torch.log(torch.sqrt(squared)) / log_hd_sd
490
+
491
+ return torch.where(female == 1, score("female"), score("male")).unsqueeze(-1)
492
+
493
+
494
+ class KDMAge(pyagingModel):
495
+ """Klemera-Doubal biological age with sex-specific NHANES III parameters."""
496
+
497
+ def __init__(self):
498
+ super().__init__()
499
+ for sex in ["male", "female"]:
500
+ for name in ["q", "k", "s"]:
501
+ self.register_buffer(f"{name}_{sex}", torch.empty(0))
502
+ self.register_buffer(f"s_ba2_{sex}", torch.empty(0))
503
+
504
+ def preprocess(self, x):
505
+ return log1p_crp(self.features, x)
506
+
507
+ def postprocess(self, x):
508
+ """Solve the Klemera-Doubal closed form for biological age.
509
+
510
+ Notes
511
+ -----
512
+ The denominator sums over every biomarker, matching ``kdm_calc``'s
513
+ deliberate choice not to rescale the estimate for missing markers.
514
+ """
515
+ biomarkers, age, female = x[:, :-2], x[:, -2], x[:, -1]
516
+
517
+ def estimate(sex):
518
+ q, k, s, s_ba2 = (
519
+ getattr(self, f"{name}_{sex}").to(device=x.device, dtype=x.dtype) for name in ("q", "k", "s", "s_ba2")
520
+ )
521
+ numerator = ((biomarkers - q) * k / s**2).sum(dim=1)
522
+ denominator = ((k / s) ** 2).sum()
523
+ return (numerator + age / s_ba2) / (denominator + 1 / s_ba2)
524
+
525
+ return torch.where(female == 1, estimate("female"), estimate("male")).unsqueeze(-1)
526
+
527
+
414
528
  class Knight(pyagingModel):
415
529
  def __init__(self):
416
530
  super().__init__()
@@ -496,6 +610,128 @@ class Lin(pyagingModel):
496
610
  return x
497
611
 
498
612
 
613
+ class LinAge2(pyagingModel):
614
+ """Principal-component clinical clock trained on NHANES IV mortality (Fong et al. 2025)."""
615
+
616
+ def __init__(self):
617
+ super().__init__()
618
+ # The 59 names the loadings, medians and MADs are indexed by, in SVD row order.
619
+ # Set from the constants clocks/notebooks/linage2.ipynb derives when the clock is built.
620
+ self.model_features = None
621
+ for sex in ["male", "female"]:
622
+ for name in ["median", "mad", "loadings", "beta", "means", "beta_null", "mean_null", "mrdt"]:
623
+ self.register_buffer(f"{name}_{sex}", torch.empty(0))
624
+ self.register_buffer(f"pc_index_{sex}", torch.empty(0, dtype=torch.long))
625
+ self.register_buffer("log_mask", torch.empty(0, dtype=torch.bool))
626
+ self.register_buffer("skip_mask", torch.empty(0, dtype=torch.bool))
627
+
628
+ def preprocess(self, x):
629
+ return x
630
+
631
+ def _model_vector(self, x):
632
+ """Assemble the 59-feature vector from the user-facing inputs.
633
+
634
+ Notes
635
+ -----
636
+ Every missing-value default the reference implementation applies falls out
637
+ of the comparisons themselves: a NaN questionnaire code never equals 1, so
638
+ it counts as "no" in ``comorbidity_index``, and it never equals 4, 5, 1 or 2,
639
+ so ``self_reported_health_index`` collapses to 0 — which is what ``popPCFIfs1``
640
+ and ``popPCFIfs2`` get from their explicit NA defaults of "no" and "same".
641
+ Those defaults are the *healthiest* profile, so an absent questionnaire block
642
+ biases the biological age downward; the registry notes say so.
643
+ """
644
+
645
+ def column(name):
646
+ return x[:, self.features.index(name)]
647
+
648
+ # digiCot: a four-level step function on raw cotinine in ng/mL. NaN has no bin
649
+ # in the reference either, so it propagates rather than reading as a non-smoker.
650
+ cotinine = column("cotinine")
651
+ smoking = (cotinine >= 10).to(x.dtype) + (cotinine >= 100).to(x.dtype) + (cotinine >= 200).to(x.dtype)
652
+ smoking = torch.where(torch.isnan(cotinine), cotinine, smoking)
653
+
654
+ yes_count = sum((column(item) == 1).to(x.dtype) for item in LINAGE2_COMORBIDITY_ITEMS)
655
+ # DIQ010 == 3 is borderline diabetes and counts alongside DIQ010 == 1.
656
+ comorbidity = (yes_count + (column("told_diabetes") == 3).to(x.dtype)) / len(LINAGE2_COMORBIDITY_ITEMS)
657
+
658
+ health = column("general_health_condition")
659
+ versus = column("health_compared_to_one_year_ago")
660
+ severity = (health == 4).to(x.dtype) * 2 + (health == 5).to(x.dtype) * 4
661
+ trend = 1 - (versus == 1).to(x.dtype) * 0.5 + (versus == 2).to(x.dtype)
662
+
663
+ # The raw HUQ050 visit-count code used as a number; 77 (refused), 99 (don't
664
+ # know) and missing all become 0.
665
+ visits = column("healthcare_visits_past_year")
666
+ healthcare = torch.where(
667
+ (visits == 77) | (visits == 99) | torch.isnan(visits), torch.zeros_like(visits), visits
668
+ )
669
+
670
+ # Friedewald, with the reference's mg/dL divisor applied to mmol/L inputs.
671
+ # ``populateLDL`` substitutes a hard 0 mmol/L when any of the three lipids is
672
+ # missing, which z-scores to roughly -3.6 for a male; reference_values keep an
673
+ # absent column away from that path, but a NaN within a present column reaches it.
674
+ ldl = column("total_cholesterol") - column("triglycerides") / 5 - column("hdl_cholesterol")
675
+ ldl = torch.where(torch.isnan(ldl), torch.zeros_like(ldl), ldl)
676
+
677
+ # 1.1312e-4 converts urine creatinine from µmol/L to g/L, giving mg albumin per g.
678
+ albumin_creatinine = column("urine_albumin") / (column("urine_creatinine") * 1.1312e-4)
679
+
680
+ derived = {
681
+ "smoking_intensity": smoking,
682
+ "comorbidity_index": comorbidity,
683
+ "self_reported_health_index": severity * trend,
684
+ "healthcare_use_index": healthcare,
685
+ "ldl_cholesterol": ldl,
686
+ "urine_albumin_creatinine_ratio": albumin_creatinine,
687
+ }
688
+ columns = [derived[name] if name in derived else column(name) for name in self.model_features]
689
+ return torch.stack(columns, dim=1)
690
+
691
+ def postprocess(self, x):
692
+ """Score the sex-specific Cox model on the folded principal components.
693
+
694
+ Notes
695
+ -----
696
+ The 13 log-transformed features take a plain ``log`` with no floor. The
697
+ reference lets ``log(0)`` reach the fold as ``-inf``, where it becomes exactly
698
+ ``-6``; clamping the input first — as ``PhenoAge.preprocess`` does before its
699
+ natural log — would land a below-detection reading on a different z-score, so
700
+ this clock deliberately does not floor.
701
+
702
+ The ±6 fold covers all 59 features, including the five that skip z-scoring:
703
+ ``self_reported_health_index`` and ``healthcare_use_index`` both run 0-8 raw
704
+ and saturate at 6.
705
+
706
+ ``chronAge`` enters both the full and the null Cox model in months, and the two
707
+ age coefficients differ, so age is a genuine covariate of the delta rather than
708
+ an offset that cancels.
709
+ """
710
+ vector = self._model_vector(x)
711
+ age_months = x[:, self.features.index("age")] * 12
712
+ female = x[:, self.features.index("female")]
713
+
714
+ transformed = torch.where(self.log_mask, torch.log(vector), vector)
715
+
716
+ def estimate(sex):
717
+ median, mad, loadings, beta, means, beta_null, mean_null, mrdt = (
718
+ getattr(self, f"{name}_{sex}").to(device=x.device, dtype=x.dtype)
719
+ for name in ("median", "mad", "loadings", "beta", "means", "beta_null", "mean_null", "mrdt")
720
+ )
721
+ normalized = torch.where(self.skip_mask, transformed, (transformed - median) / mad)
722
+ folded = normalized.clamp(-LINAGE2_FOLD_CAP, LINAGE2_FOLD_CAP)
723
+ components = folded @ loadings
724
+
725
+ # The stored indices are the Cox formula's 1-based PC labels.
726
+ selected = components[:, getattr(self, f"pc_index_{sex}") - 1]
727
+ terms = torch.cat([age_months.unsqueeze(1), selected], dim=1)
728
+ risk = ((terms - means) * beta).sum(dim=1)
729
+ null_risk = beta_null * (age_months - mean_null)
730
+ return (age_months + (risk - null_risk) / math.log(2) * mrdt) / 12
731
+
732
+ return torch.where(female == 1, estimate("female"), estimate("male")).unsqueeze(-1)
733
+
734
+
499
735
  class Mammalian1(pyagingModel):
500
736
  def __init__(self):
501
737
  super().__init__()
@@ -1451,7 +1687,22 @@ class PhenoAge(pyagingModel):
1451
1687
  super().__init__()
1452
1688
 
1453
1689
  def preprocess(self, x):
1454
- return x
1690
+ """Apply Levine's natural-log transform to C-reactive protein.
1691
+
1692
+ The published coefficient is fit against ln(CRP in mg/dL); users supply
1693
+ the raw measurement so the same column can feed clocks that log it
1694
+ differently.
1695
+
1696
+ Notes
1697
+ -----
1698
+ CRP is clamped to ``PHENOAGE_CRP_FLOOR_MG_DL`` before the log, so a zero
1699
+ — from a below-detection reading, a constant imputer, or a column the
1700
+ input never had — yields a finite age instead of ``-inf`` propagating
1701
+ into every downstream summary.
1702
+ """
1703
+ index = crp_index(self.features)
1704
+ crp = torch.clamp(x[:, index : index + 1], min=PHENOAGE_CRP_FLOOR_MG_DL)
1705
+ return torch.cat([x[:, :index], torch.log(crp), x[:, index + 1 :]], dim=1)
1455
1706
 
1456
1707
  def postprocess(self, x):
1457
1708
  """
@@ -1465,6 +1716,33 @@ class PhenoAge(pyagingModel):
1465
1716
  return age
1466
1717
 
1467
1718
 
1719
+ class PhenoAgeSaoPaulo(pyagingModel):
1720
+ """PhenoAge refit without creatinine, albumin, and alkaline phosphatase."""
1721
+
1722
+ def __init__(self):
1723
+ super().__init__()
1724
+ for name in ["m_n", "m_d", "ba_n", "ba_d", "ba_i"]:
1725
+ self.register_buffer(name, torch.empty(0))
1726
+
1727
+ def preprocess(self, x):
1728
+ """Apply BioAge's log1p transform to C-reactive protein, not ``PhenoAge``'s ``ln``."""
1729
+ return log1p_crp(self.features, x)
1730
+
1731
+ def postprocess(self, x):
1732
+ """Convert the Gompertz mortality score to phenotypic age.
1733
+
1734
+ Notes
1735
+ -----
1736
+ The constants are refit alongside the coefficients and differ from
1737
+ Levine's published ones.
1738
+ """
1739
+ m_n, m_d, ba_n, ba_d, ba_i = (
1740
+ buffer.to(device=x.device, dtype=x.dtype)
1741
+ for buffer in (self.m_n, self.m_d, self.ba_n, self.ba_d, self.ba_i)
1742
+ )
1743
+ return mortality_to_phenoage_saopaulo(x, m_n, m_d, ba_n, ba_d, ba_i)
1744
+
1745
+
1468
1746
  class RepliTali(pyagingModel):
1469
1747
  def __init__(self):
1470
1748
  super().__init__()
@@ -6,12 +6,14 @@ from ._inverse_transforms import (
6
6
  anti_log_log,
7
7
  anti_logp2,
8
8
  mortality_to_phenoage,
9
+ mortality_to_phenoage_saopaulo,
9
10
  petkovichblood,
10
11
  stubbsmultitissue,
11
12
  )
12
13
  from ._pred import predict_age
13
14
  from ._pred_utils import (
14
15
  add_pred_ages_and_clock_metadata_adata,
16
+ check_feature_ranges,
15
17
  check_features_in_adata,
16
18
  cleanup_clock_memory,
17
19
  load_clock,
@@ -34,10 +36,12 @@ __all__ = [
34
36
  "anti_log_log",
35
37
  "anti_logp2",
36
38
  "binarize",
39
+ "check_feature_ranges",
37
40
  "check_features_in_adata",
38
41
  "cleanup_clock_memory",
39
42
  "load_clock",
40
43
  "mortality_to_phenoage",
44
+ "mortality_to_phenoage_saopaulo",
41
45
  "petkovichblood",
42
46
  "predict_age",
43
47
  "predict_ages_with_model",
@@ -1,5 +1,7 @@
1
1
  import math
2
2
 
3
+ import torch
4
+
3
5
 
4
6
  def anti_log_linear(x, adult_age=20):
5
7
  """
@@ -49,6 +51,35 @@ def mortality_to_phenoage(x):
49
51
  return age
50
52
 
51
53
 
54
+ def mortality_to_phenoage_saopaulo(x, m_n, m_d, ba_n, ba_d, ba_i):
55
+ """
56
+ Applies a convertion from a CDF of the mortality score from a Gompertz
57
+ distribution to phenotypic age, using constants supplied by the caller.
58
+
59
+ ``mortality_to_phenoage`` hardcodes Levine's 2018 published constants. A
60
+ refit of that model fits its own mortality-to-age constants alongside its
61
+ coefficients, so they are passed in rather than baked in.
62
+
63
+ Parameters
64
+ ----------
65
+ x : torch.Tensor
66
+ The linear predictor, one value per sample.
67
+
68
+ m_n, m_d : torch.Tensor
69
+ Numerator and denominator of the Gompertz mortality exponent.
70
+
71
+ ba_n, ba_d, ba_i : torch.Tensor
72
+ Scale, rate, and intercept converting mortality back to years.
73
+
74
+ Returns
75
+ -------
76
+ torch.Tensor
77
+ Phenotypic age in years.
78
+ """
79
+ mortality_score = 1 - torch.exp(m_n * torch.exp(x) / m_d)
80
+ return torch.log(ba_n * torch.log(1 - mortality_score)) / ba_d + ba_i
81
+
82
+
52
83
  def petkovichblood(x):
53
84
  """
54
85
  Applies a convertion from the output of an ElasticNet to mouse age in months.
@@ -6,6 +6,7 @@ import torch
6
6
  from ..logger._live import ClockRunDisplay, DisplayLogger, display_enabled, quiet_hf_bars
7
7
  from ._pred_utils import (
8
8
  add_pred_ages_and_clock_metadata_adata,
9
+ check_feature_ranges,
9
10
  check_features_in_adata,
10
11
  load_clock,
11
12
  predict_ages_with_model,
@@ -106,6 +107,10 @@ def predict_age(
106
107
  display.stage(clock_name, "matching features")
107
108
  check_features_in_adata(adata, model, pipeline_logger)
108
109
 
110
+ # Warn if the input values look implausible for these features
111
+ display.stage(clock_name, "checking feature ranges")
112
+ check_feature_ranges(adata, model, pipeline_logger)
113
+
109
114
  # Perform age prediction applying preprocessing and postprocessing steps
110
115
  display.stage(clock_name, "predicting")
111
116
 
@@ -14,6 +14,7 @@ except Exception:
14
14
  import gc
15
15
 
16
16
  from ..models import pyagingModel
17
+ from ..utils._feature_ranges import resolve_feature_bounds
17
18
  from ..utils._hf import PyAgingResourceNotFoundError, download_clock_weights
18
19
  from ..utils._utils import progress
19
20
 
@@ -161,6 +162,11 @@ def check_features_in_adata(
161
162
  may introduce biases if not accounted for in downstream analyses. If reference values are
162
163
  provided, then they are used instead of zeros.
163
164
 
165
+ Alongside the missing-feature bookkeeping the function records a boolean mask of the columns
166
+ that came from the input, under ``.uns["{clock_name}_supplied_features_mask"]``. Substituted
167
+ values are the pipeline's own, so :func:`check_feature_ranges` uses the mask to judge only
168
+ what the user actually supplied.
169
+
164
170
  Examples
165
171
  --------
166
172
  >>> updated_adata = check_features_in_adata(adata, bitage, ["gene1", "gene2"], logger)
@@ -201,6 +207,8 @@ def check_features_in_adata(
201
207
  # Add missing features and percent missing values to the clock
202
208
  adata.uns[f"{model.metadata['clock_name']}_percent_na"] = percent_missing
203
209
  adata.uns[f"{model.metadata['clock_name']}_missing_features"] = missing_features
210
+ # Columns the input carried; check_feature_ranges judges only these.
211
+ adata.uns[f"{model.metadata['clock_name']}_supplied_features_mask"] = existing_features_mask
204
212
 
205
213
  # Raises error if there are no features in the data
206
214
  if percent_missing == 100:
@@ -238,6 +246,146 @@ def check_features_in_adata(
238
246
  )
239
247
 
240
248
 
249
+ _MAX_REPORTED_FEATURES = 5
250
+
251
+
252
+ def _describe_range(low: float, high: float) -> str:
253
+ """Phrase a violated range, keeping half-bounded ranges readable."""
254
+ if np.isinf(low):
255
+ return f"above {high:g}"
256
+ if np.isinf(high):
257
+ return f"below {low:g}"
258
+ return f"outside [{low:g}, {high:g}]"
259
+
260
+
261
+ def _supplied_columns(adata: anndata.AnnData, model: pyagingModel, n_features: int) -> np.ndarray:
262
+ """Return the indices of the feature columns that came from the input data.
263
+
264
+ :func:`check_features_in_adata` substitutes a reference value, or 0, for every
265
+ feature the input did not carry, so those columns say nothing about the user's
266
+ units. It leaves behind a mask of the columns it did not substitute, which this
267
+ reads. A matrix assembled some other way has no mask, and then every column
268
+ counts as supplied.
269
+ """
270
+ mask = adata.uns.get(f"{model.metadata['clock_name']}_supplied_features_mask")
271
+ if mask is None:
272
+ return np.arange(n_features)
273
+ return np.flatnonzero(np.asarray(mask, dtype=bool))
274
+
275
+
276
+ # Columns compared per pass. The comparison is vectorised, but a clock with 453,152
277
+ # features against a large cohort would otherwise build a boolean array the size of the
278
+ # whole matrix, so the scan walks the columns in blocks of bounded width.
279
+ _SCAN_BLOCK_COLUMNS = 4096
280
+
281
+
282
+ def _find_offenders(matrix: np.ndarray, columns: np.ndarray, low: np.ndarray, high: np.ndarray) -> list:
283
+ """Return ``(column index, out-of-range count)`` for each offending column.
284
+
285
+ NaN compares false against both bounds, so missing values drop out of the
286
+ count without being tested for separately.
287
+ """
288
+ offenders = []
289
+ for start in range(0, columns.size, _SCAN_BLOCK_COLUMNS):
290
+ block = columns[start : start + _SCAN_BLOCK_COLUMNS]
291
+ values = matrix[:, block]
292
+ counts = ((values < low[block]) | (values > high[block])).sum(axis=0)
293
+ offenders.extend((int(block[position]), int(counts[position])) for position in np.flatnonzero(counts))
294
+ return offenders
295
+
296
+
297
+ @progress("Check feature ranges")
298
+ def check_feature_ranges(
299
+ adata: anndata.AnnData,
300
+ model: pyagingModel,
301
+ logger,
302
+ indent_level: int = 2,
303
+ ) -> None:
304
+ """
305
+ Warn when input values fall outside a feature's plausible range.
306
+
307
+ Ranges come from the package-wide registry (per-feature entry, else the
308
+ modality default for the clock's ``data_type``). Out-of-range values usually
309
+ mean wrong units or swapped columns, so this warns and never blocks: the
310
+ data is not inspected for clinical abnormality and is never modified.
311
+
312
+ Only the features the input actually carried are judged. Everything else in
313
+ the matrix was put there by :func:`check_features_in_adata`, and several
314
+ clocks use an out-of-range sentinel such as ``-1`` as their reference value,
315
+ so including those columns would report the pipeline's own substitutions as
316
+ if they were the user's data.
317
+
318
+ Parameters
319
+ ----------
320
+ adata : anndata.AnnData
321
+ The AnnData object whose ``.obsm["X_{clock_name}"]`` matrix holds the
322
+ clock's feature values, one column per model feature.
323
+
324
+ model : pyagingModel
325
+ The pyagingModel of the aging clock of interest. Clocks saved before the
326
+ ``feature_units`` attribute existed are supported.
327
+
328
+ logger : Logger
329
+ A logger object used to report the out-of-range features.
330
+
331
+ indent_level : int, optional
332
+ The indentation level for the logger, by default 2.
333
+
334
+ Returns
335
+ -------
336
+ None
337
+ Nothing is returned and nothing is modified; the findings are logged.
338
+
339
+ Notes
340
+ -----
341
+ NaN values are ignored: missing features are handled by
342
+ :func:`check_features_in_adata`, and should not also be reported here. The
343
+ reported percentage is therefore the share of non-NaN values that fall
344
+ outside the range, and the feature counts are out of the supplied features
345
+ rather than out of all of the clock's features.
346
+ """
347
+ try:
348
+ units, low, high = resolve_feature_bounds(
349
+ model.features,
350
+ model.metadata.get("data_type"),
351
+ getattr(model, "feature_units", None),
352
+ )
353
+ except Exception as exc:
354
+ # Deliberately broad: one clock whose stored feature_units disagree with its
355
+ # features must not abort predict_age for every user.
356
+ logger.warning(f"Could not resolve feature ranges: {exc}", indent_level=indent_level + 1)
357
+ return
358
+
359
+ matrix = adata.obsm[f"X_{model.metadata['clock_name']}"]
360
+ if CUPY_AVAILABLE and isinstance(matrix, cp.ndarray):
361
+ matrix = cp.asnumpy(matrix)
362
+ matrix = np.asarray(matrix, dtype=float)
363
+
364
+ columns = _supplied_columns(adata, model, len(units))
365
+ offenders = _find_offenders(matrix, columns, low, high)
366
+
367
+ if not offenders:
368
+ logger.info("All feature values are within their expected ranges.", indent_level=indent_level + 1)
369
+ return
370
+
371
+ truncated = f" Showing the first {_MAX_REPORTED_FEATURES}." if len(offenders) > _MAX_REPORTED_FEATURES else ""
372
+ logger.warning(
373
+ f"{len(offenders)} of {len(columns)} supplied features have values outside their expected range. "
374
+ f"This usually means the data is in different units than the clock expects.{truncated}",
375
+ indent_level=indent_level + 1,
376
+ )
377
+ for index, count in offenders[:_MAX_REPORTED_FEATURES]:
378
+ observed = matrix[:, index]
379
+ observed = observed[~np.isnan(observed)]
380
+ unit = f" {units[index]}" if units[index] else ""
381
+ logger.warning(
382
+ f"{model.features[index]}: {100 * count / observed.size:.2f}% of values "
383
+ f"{_describe_range(low[index], high[index])}{unit} "
384
+ f"(observed {observed.min():g} to {observed.max():g})",
385
+ indent_level=indent_level + 2,
386
+ )
387
+
388
+
241
389
  @progress("Predict ages with model")
242
390
  def predict_ages_with_model(
243
391
  adata: anndata.AnnData,
@@ -1,4 +1,5 @@
1
1
  import numpy as np
2
+ import torch
2
3
 
3
4
 
4
5
  def scale(x, scaler):
@@ -96,3 +97,59 @@ def quantile_normalize_with_gold_standard(x, gold_standard_means):
96
97
  x_normalized[i, :] = normalized_data[original_order_indices]
97
98
 
98
99
  return x_normalized
100
+
101
+
102
+ # Lowest C-reactive protein ``PhenoAge`` will take the natural log of, in mg/dL. Its
103
+ # clamp is the only CRP transform that needs a floor, and the value matches the registry
104
+ # floor in data/feature_ranges.json so that anything the clamp touches has already been
105
+ # reported by check_feature_ranges.
106
+ PHENOAGE_CRP_FLOOR_MG_DL = 0.01
107
+
108
+
109
+ def crp_index(features):
110
+ """Locate the C-reactive protein column, or explain why there is not one.
111
+
112
+ pyaging 0.5.0 renamed this feature from ``log_crp`` and moved the log into the
113
+ clock, so 0.5.0 code cannot run a weight file built before it.
114
+
115
+ Raises
116
+ ------
117
+ ValueError
118
+ If ``features`` has no ``c_reactive_protein`` entry.
119
+ """
120
+ try:
121
+ return features.index("c_reactive_protein")
122
+ except ValueError:
123
+ pass
124
+ legacy = " Its features call it 'log_crp', the name pyaging used before 0.5.0." if "log_crp" in features else ""
125
+ raise ValueError(
126
+ "This clock has no 'c_reactive_protein' feature, so its C-reactive protein transform "
127
+ f"cannot be applied.{legacy} Weights built before pyaging 0.5.0 do not work with "
128
+ "pyaging 0.5.0 or later. Unset PYAGING_DATA_REVISION, or pin it to v0.5.0 or a later "
129
+ "tag, to download weights that match the installed version; pin pyaging itself to "
130
+ "<0.5.0 to keep using the older weights."
131
+ )
132
+
133
+
134
+ def log1p_crp(features, x):
135
+ """Apply BioAge's ``lncrp`` transform to the C-reactive protein column alone.
136
+
137
+ BioAge fits ``lncrp`` against ``log1p(CRP in mg/dL)``, not the natural log
138
+ ``PhenoAge`` uses, so every clock ported from that package shares this
139
+ transform; users supply the raw measurement so one column can feed clocks
140
+ that log it differently.
141
+
142
+ Notes
143
+ -----
144
+ CRP is not floored. ``log1p`` is finite everywhere it is defined, and
145
+ ``log1p(0) == 0`` is a point BioAge's own fitted preimage includes, so a
146
+ below-detection reading coded as ``0``, a constant imputer, or an absent
147
+ column all pass through as the reference scores them. Only a value at or
148
+ below ``-1`` mg/dL is outside the domain, and that is not a measurement;
149
+ those samples become ``NaN`` so they surface in the output instead of
150
+ carrying a value the clock made up for them.
151
+ """
152
+ index = crp_index(features)
153
+ crp = x[:, index : index + 1]
154
+ crp = torch.where(crp > -1, crp, torch.nan)
155
+ return torch.cat([x[:, :index], torch.log1p(crp), x[:, index + 1 :]], dim=1)
@@ -268,7 +268,7 @@ def add_metadata_to_anndata(
268
268
  """
269
269
  if metadata is None:
270
270
  logger.warning("No metadata provided. Leaving adata.obs empty", indent_level=2)
271
- return adata
271
+ return
272
272
 
273
273
  # Add metadata to the AnnData object
274
274
  logger.info("Adding provided metadata to adata.obs", indent_level=2)
@@ -311,7 +311,7 @@ def add_unstructured_data(adata: anndata.AnnData, imputer_strategy: str, logger,
311
311
  -------
312
312
  >>> from anndata import AnnData
313
313
  >>> adata = AnnData(np.random.rand(5, 3))
314
- >>> adata = add_unstructured_data(adata, "mean", logger)
314
+ >>> add_unstructured_data(adata, "mean", logger)
315
315
  # This will add the imputer strategy 'mean' and the data type 'dna_methylation' to the AnnData object.
316
316
 
317
317
  """
@@ -1,5 +1,6 @@
1
1
  # pyaging/utils/__init__.py
2
2
 
3
+ from ._feature_ranges import get_feature_ranges, resolve_feature_ranges
3
4
  from ._utils import (
4
5
  cite_clock,
5
6
  download,
@@ -16,8 +17,10 @@ __all__ = [
16
17
  "download",
17
18
  "find_clock_by_doi",
18
19
  "get_clock_metadata",
20
+ "get_feature_ranges",
19
21
  "load_clock_metadata",
20
22
  "print_model_details",
21
23
  "progress",
24
+ "resolve_feature_ranges",
22
25
  "show_all_clocks",
23
26
  ]
@@ -0,0 +1,165 @@
1
+ """Package-wide ground truth for feature units and plausibility ranges."""
2
+
3
+ import json
4
+ import math
5
+ from functools import lru_cache
6
+ from importlib import resources
7
+
8
+ import numpy as np
9
+
10
+ _UNBOUNDED = {"unit": None, "low": None, "high": None}
11
+
12
+
13
+ @lru_cache(maxsize=1)
14
+ def load_feature_range_registry() -> dict:
15
+ """
16
+ Load and cache the feature range registry shipped with the package.
17
+
18
+ Returns
19
+ -------
20
+ dict
21
+ The parsed registry, with keys ``schema_version``, ``modality_defaults``,
22
+ and ``features``. The same object is returned on every call, so callers
23
+ must not mutate it.
24
+ """
25
+ source = resources.files("pyaging.data").joinpath("feature_ranges.json")
26
+ return json.loads(source.read_text(encoding="utf-8"))
27
+
28
+
29
+ def resolve_feature_bounds(features, data_type, feature_units=None):
30
+ """Resolve each feature's unit and bounds as parallel sequences.
31
+
32
+ Same resolution rules as :func:`resolve_feature_ranges`, which is written in
33
+ terms of this. The largest clocks carry 453,152 features, and a dict per
34
+ feature is a measurable share of a prediction's run time, so callers that
35
+ only need to compare numbers take the arrays instead.
36
+
37
+ Parameters
38
+ ----------
39
+ features : list of str
40
+ Feature names, in the order the caller uses them.
41
+
42
+ data_type : str or None
43
+ The clock's modality.
44
+
45
+ feature_units : list of str or str, optional
46
+ Units that override the registry unit, as in :func:`resolve_feature_ranges`.
47
+
48
+ Returns
49
+ -------
50
+ tuple of (list of str or None, numpy.ndarray, numpy.ndarray)
51
+ The resolved units, and the lower and upper bounds as float arrays whose
52
+ unbounded sides are ``-inf`` and ``inf``.
53
+
54
+ Raises
55
+ ------
56
+ ValueError
57
+ If ``feature_units`` is a list whose length differs from ``features``.
58
+ """
59
+ features = list(features)
60
+ if feature_units is None or isinstance(feature_units, str):
61
+ overrides = [feature_units] * len(features)
62
+ elif len(feature_units) != len(features):
63
+ raise ValueError(f"feature_units has {len(feature_units)} entries but there are {len(features)} features")
64
+ else:
65
+ overrides = list(feature_units)
66
+
67
+ registry = load_feature_range_registry()
68
+ entries = registry["features"]
69
+ default = registry["modality_defaults"].get(data_type, _UNBOUNDED)
70
+ default_low = -math.inf if default["low"] is None else float(default["low"])
71
+ default_high = math.inf if default["high"] is None else float(default["high"])
72
+
73
+ units = [override or default["unit"] for override in overrides]
74
+ low = np.full(len(features), default_low)
75
+ high = np.full(len(features), default_high)
76
+ # Most features on a methylation clock are CpGs with no entry of their own, so
77
+ # only pay for the per-feature lookup when the registry has something to say.
78
+ if entries.keys() & set(features):
79
+ for index, feature in enumerate(features):
80
+ entry = entries.get(feature)
81
+ if entry is None:
82
+ continue
83
+ units[index] = overrides[index] or entry["unit"]
84
+ low[index] = -math.inf if entry["low"] is None else float(entry["low"])
85
+ high[index] = math.inf if entry["high"] is None else float(entry["high"])
86
+ return units, low, high
87
+
88
+
89
+ def resolve_feature_ranges(features, data_type, feature_units=None) -> list[dict]:
90
+ """
91
+ Resolve each feature to its unit and plausibility bounds.
92
+
93
+ A per-feature registry entry wins over the modality default for the clock's
94
+ ``data_type``; features in neither are unbounded.
95
+
96
+ Parameters
97
+ ----------
98
+ features : list of str
99
+ Feature names, in the order the caller uses them.
100
+
101
+ data_type : str or None
102
+ The clock's modality, e.g. ``"DNA methylation"`` or ``"clinical biomarkers"``.
103
+ A modality with no default leaves unlisted features unbounded.
104
+
105
+ feature_units : list of str or str, optional
106
+ Units that override the registry unit. A single string applies to every
107
+ feature; a list must have one entry per feature, and a ``None`` entry
108
+ falls back to the registry unit for that feature.
109
+
110
+ Returns
111
+ -------
112
+ list of dict
113
+ One record per feature, in the order of ``features``, each with keys
114
+ ``feature``, ``unit``, ``low``, and ``high``. Unbounded sides are
115
+ ``-inf`` and ``inf``.
116
+
117
+ Raises
118
+ ------
119
+ ValueError
120
+ If ``feature_units`` is a list whose length differs from ``features``.
121
+ """
122
+ units, low, high = resolve_feature_bounds(features, data_type, feature_units)
123
+ return [
124
+ {"feature": feature, "unit": unit, "low": float(lower), "high": float(upper)}
125
+ for feature, unit, lower, upper in zip(features, units, low, high, strict=True)
126
+ ]
127
+
128
+
129
+ def get_feature_ranges(clock_name: str):
130
+ """
131
+ Return a clock's feature units and normal ranges as a DataFrame.
132
+
133
+ Parameters
134
+ ----------
135
+ clock_name : str
136
+ The name of the aging clock. Case-insensitive.
137
+
138
+ Returns
139
+ -------
140
+ pandas.DataFrame
141
+ One row per clock feature, with columns ``feature``, ``unit``, ``low``,
142
+ and ``high``.
143
+
144
+ Raises
145
+ ------
146
+ ValueError
147
+ If the loaded clock carries no feature list.
148
+
149
+ Examples
150
+ --------
151
+ >>> get_feature_ranges("phenoage") # doctest: +SKIP
152
+ """
153
+ import pandas as pd
154
+
155
+ from ..predict import load_clock
156
+
157
+ model = load_clock(clock_name, verbose=False)
158
+ if model.features is None:
159
+ raise ValueError(f"clock {clock_name!r} has no feature list, so its feature ranges cannot be resolved")
160
+ records = resolve_feature_ranges(
161
+ model.features,
162
+ model.metadata.get("data_type"),
163
+ getattr(model, "feature_units", None),
164
+ )
165
+ return pd.DataFrame.from_records(records)
@@ -2,8 +2,8 @@
2
2
 
3
3
  Clock weights live in one repository per clock under the ``pyaging``
4
4
  organization (``pyaging/<clock_name>``); shared assets (example data, the
5
- aggregate metadata file) live in the legacy data repository, which also
6
- serves as a fallback for clocks that have not been migrated yet.
5
+ aggregate metadata file) live in the legacy data repository, which is also
6
+ the fallback whenever a clock's own repository cannot be read.
7
7
 
8
8
  Set the ``PYAGING_DATA_REVISION`` environment variable to pin downloads to a
9
9
  specific revision of the data repositories (e.g. a release tag such as
@@ -95,7 +95,7 @@ def download_clock_weights(clock_name: str, dir: str = "pyaging_data", logger=No
95
95
  """Download a clock's weight file, preferring its dedicated repository.
96
96
 
97
97
  Each clock lives in ``pyaging/<clock_name>``; the legacy shared data
98
- repository is used as a fallback for clocks that are not migrated yet.
98
+ repository is the fallback when the per-clock repository cannot be read.
99
99
  The repo's ``config.json`` is fetched alongside the weights - it carries
100
100
  the audited clock metadata and is the file the Hub counts as a download.
101
101
  """
@@ -86,10 +86,6 @@ def load_clock_metadata(dir: str, logger, indent_level: int = 2) -> dict:
86
86
  dir : str
87
87
  Retained for backward compatibility. Hugging Face files use its standard cache.
88
88
 
89
- verbose : bool
90
- Whether to show the progress display and warnings. Animated in
91
- notebooks and terminals, a plain summary when output is captured,
92
- and fully silent when False. Defaults to True.
93
89
  logger : object
94
90
  Logger object used for logging information, warnings, and errors.
95
91
  indent_level : int, optional
@@ -275,7 +271,10 @@ def cite_clock(clock_name: str, dir: str = "pyaging_data", verbose: bool = True)
275
271
  clock_dict = all_clock_metadata.get(clock_name)
276
272
  citation = clock_dict.get("citation") if clock_dict else None
277
273
  if citation:
278
- step.payload(f" {citation}")
274
+ # A derived clock can carry more than one: the work that produced it and
275
+ # the method reference it starts from. Give each its own line.
276
+ for entry in [citation] if isinstance(citation, str) else citation:
277
+ step.payload(f" {entry}")
279
278
  step.payload(Text(f" Please also consider citing pyaging: {pyaging_citation}", style=MUTED))
280
279
  step.done(f"citation for {clock_name}")
281
280
  elif clock_dict:
File without changes
File without changes
File without changes