# LinAge2 Biological Age Clock Input Template (userData.csv)

This README explains how to use the `LinAge2_userData_template.csv` file to compute **LinAge2 Biological Age (BA)** using the R script provided by Gruber et al. (npj Aging, 2025).

---

## 1. Overview

**LinAge2** is a clinical biological age clock that estimates mortality and healthspan risk based on 60 routinely available lab and biometric variables.
It uses sex-specific principal component (PC) models trained on NHANES data. You can input your own or patients’ data in NHANES-compatible units and run the official `linAge2.R` script to obtain:

- Biological Age (LinAge2 BA)
- ΔAge (BA − Chronological Age)
- Individual PC contributions (metabolic, inflammatory, renal, etc.)
- Suggested intervention domains (see Supplementary Table 5 of the paper)

---

## 2. File Structure

Each row in the CSV corresponds to one subject. The column **SEQN** (sequence number) is a required identifier.  
The script will output a new file `userData_out.csv` containing your original data plus computed BA and PC values.

---

## 3. Variable Definitions and Units

### Demographics
| Column | Description | Units / Format |
|--------|-------------|----------------|
| SEQN | Sequence ID (any number) | integer |
| RIDAGEYR | Chronological age | years |
| SEX | Biological sex | "Male" / "Female" |
| RACE_ETHNICITY | Optional, improves normalization | NHANES category |

### Vitals / Anthropometrics
| Column | Description | Units |
|--------|-------------|--------|
| HEIGHT_cm | Standing height | cm |
| WEIGHT_kg | Body weight | kg |
| BMI_kg_m2 | Body Mass Index | kg/m² |
| WAIST_cm | Waist circumference | cm |
| SYSTOLIC_BP_mmHg | Systolic blood pressure | mmHg |
| DIASTOLIC_BP_mmHg | Diastolic blood pressure | mmHg |
| PULSE_bpm | Resting pulse rate | bpm |

### Complete Blood Count (CBC)
| Column | Description | Units |
|--------|-------------|--------|
| WBC_10e9_per_L | White blood cells | ×10⁹/L |
| NEUTROPHIL_percent | % neutrophils | % |
| LYMPHOCYTE_percent | % lymphocytes | % |
| MONOCYTE_percent | % monocytes | % |
| EOSINOPHIL_percent | % eosinophils | % |
| BASOPHIL_percent | % basophils | % |
| HEMOGLOBIN_g_dL | Hemoglobin | g/dL |
| HEMATOCRIT_percent | Hematocrit | % |
| RBC_10e12_per_L | Red blood cell count | ×10¹²/L |
| MCV_fL | Mean corpuscular volume | fL |
| MCH_pg | Mean corpuscular hemoglobin | pg |
| MCHC_g_dL | Mean corpuscular hemoglobin concentration | g/dL |
| RDW_percent | Red cell distribution width | % |
| PLATELETS_10e9_per_L | Platelet count | ×10⁹/L |

### Metabolic / Renal Panel
| Column | Description | Units |
|--------|-------------|--------|
| GLUCOSE_mg_dL_fasting | Fasting glucose | mg/dL |
| BUN_mg_dL | Blood urea nitrogen | mg/dL |
| CREATININE_mg_dL | Serum creatinine | mg/dL |
| SODIUM_mmol_L | Sodium | mmol/L |
| POTASSIUM_mmol_L | Potassium | mmol/L |
| CHLORIDE_mmol_L | Chloride | mmol/L |
| CO2_BICARBONATE_mmol_L | CO₂ (bicarbonate) | mmol/L |
| CALCIUM_mg_dL | Calcium | mg/dL |
| ANION_GAP_mmol_L | (Na - Cl - CO₂) | mmol/L |

### Liver / Protein Panel
| Column | Description | Units |
|--------|-------------|--------|
| ALT_U_L | Alanine aminotransferase | U/L |
| AST_U_L | Aspartate aminotransferase | U/L |
| ALK_PHOS_U_L | Alkaline phosphatase | U/L |
| TOTAL_BILIRUBIN_mg_dL | Total bilirubin | mg/dL |
| ALBUMIN_g_dL | Serum albumin | g/dL |
| TOTAL_PROTEIN_g_dL | Total serum protein | g/dL |

### Lipids
| Column | Description | Units |
|--------|-------------|--------|
| TOTAL_CHOLESTEROL_mg_dL | Total cholesterol | mg/dL |
| LDL_C_mg_dL | LDL cholesterol | mg/dL |
| HDL_C_mg_dL | HDL cholesterol | mg/dL |
| TRIGLYCERIDES_mg_dL | Triglycerides | mg/dL |

### Endocrine / Inflammatory
| Column | Description | Units |
|--------|-------------|--------|
| HBA1c_percent | Hemoglobin A1c | % |
| INSULIN_uIU_mL | Fasting insulin | µIU/mL |
| URIC_ACID_mg_dL | Uric acid | mg/dL |
| CRP_mg_L | C-reactive protein | mg/L |

### Derived / Kidney & Lifestyle
| Column | Description | Units / Values |
|--------|-------------|----------------|
| eGFR_mL_min_1.73m2 | Estimated GFR (optional) | mL/min/1.73m² |
| BUN_CREAT_RATIO | BUN/Creatinine ratio | unitless |
| SMOKING_STATUS_CurrentFormerNever | Smoking | categorical |
| ALCOHOL_drinks_per_week | Alcohol intake | number |
| PHYSICAL_ACTIVITY_level | Self-reported | categorical |

### Optional Functional Indicators (Healthspan Context Only)
| Column | Description | Units |
|--------|-------------|--------|
| COGNITIVE_DigitSymbolScore | NHANES cognitive test | score |
| GAIT_SPEED_m_per_s | Walking speed | m/s |
| ADL_All_Basic_OK_yes_no | Basic ADL self-report | yes/no |
| IADL_All_Instrumental_OK_yes_no | Instrumental ADL self-report | yes/no |

---

## 4. Usage Instructions

1. Fill in each row with the subject’s clinical values (in correct units).  
2. Save the file as `userData.csv` in the same folder as the `linAge2.R` script.  
3. In R, run:
   ```R
   source("linAge2.R")
   ```
4. The script outputs:
   - Biological Age (LinAge2_BA)
   - ΔAge (BA − CA)
   - PC values (PC1M…PCnM)
   - Annotated table with suggested intervention domains

---

## 5. Notes

- Missing values: Leave blank; the script will handle NA values or impute using cohort medians.  
- Units must match NHANES conventions. Incorrect scaling will distort results.  
- Variables marked *optional* are not strictly required for BA calculation but improve interpretability.  
- LinAge2 is calibrated for adults (age ≥20 years).  
- For multi-subject datasets, use consistent column order and units.

---

## Reference
Fong, S., Denisov, K.A., Nefedova, A.A., Kennedy, B.K., & Gruber, J. (2025). *LinAge2: Providing actionable insights and benchmarking with epigenetic clocks.* npj Aging, 11(29). https://doi.org/10.1038/s41514-025-00221-4