aging-clock

Aging Clock — 생물학적 나이 추정 스킬

무엇을 하는 스킬인가

DNA 메틸화(β값) 데이터로부터 생물학적 나이를 추정하는 Horvath 스타일 에피제네틱 시계를 만들고, Age Acceleration(역연령 대비 가속도)을 산출하는 전체 파이프라인입니다.

핵심 산출물:

• 학습된 ElasticNet 회귀 모델 (.joblib)
• 예측 나이와 Age Acceleration CSV
• 평가 리포트 (MAE, 상관계수, 산점도 PNG)
• (선택) PyTorch MLP 기반 딥러닝 버전

언제 이 스킬을 쓰는가

다음 중 하나라도 해당하면 이 스킬을 로드하고 워크플로우를 따를 것:

• 사용자가 DNA 메틸화·에피제네틱·노화 시계·생물학적 나이·Horvath clock을 언급
• GEO accession (GSE로 시작)·Illumina 450K/EPIC array·β값 데이터를 다룸
• CpG 사이트 수십만 차원 데이터를 회귀로 풀고자 함
• 예측 나이와 역연령의 차이(Age Acceleration)를 구하려 함
• 한국인 코호트(KoGES/K-CHIP) 기반 노화 연구를 계획함

단순한 회귀 질문(예: "sklearn ElasticNet 예제")은 이 스킬을 호출하지 않음.

워크플로우 (이 순서대로 진행)

STEP 0 — 사전 확인

사용자에게 다음을 확인:

• 분석 목적(연구용 / 교육용 / 서비스 PoC)
• 입력 데이터 형태 (GEO accession ID / 로컬 CSV / Pandas DataFrame)
• 실행 환경 (macOS / Linux / WSL2)
• 의료 서비스화 의도가 있는지 → 있다면 반드시 references/kr-regulations.md를 먼저 읽을 것

STEP 1 — 환경 준비

scripts/setup_env.sh를 사용자 환경에 맞게 안내. 주요 패키지:

numpy pandas scikit-learn scipy matplotlib seaborn GEOparse joblib

선택 패키지: torch (딥러닝 버전), pyreadr (RData 대응).

한국 네트워크에서 pip이 느리면 카카오 미러(https://mirror.kakao.com/pypi/simple/)를 권장.

STEP 2 — 데이터 수집

두 경로 중 하나:

• 경로 A (GEO 리포지토리): scripts/data.py의 download_geo() + build_beta_matrix() + extract_age() 사용. 추천 accession은 references/geo-datasets.md 참조.
• 경로 B (사용자 제공 CSV): 행=CpG, 열=샘플 포맷의 β값 행렬과 샘플별 나이 메타데이터가 필요함을 안내.

GEO 데이터는 수 GB까지 갈 수 있으므로 디스크 용량·다운로드 시간을 미리 안내할 것.

STEP 3 — 전처리

scripts/data.py의 preprocess_beta()를 그대로 사용:

1. 전치(샘플 행 / CpG 열)
2. 결측값 → 컬럼 평균으로 보완
3. 상수 컬럼(std < 1e-6) 제거
4. β값을 [0.001, 0.999]로 클리핑 후 logit 변환

STEP 4 — 모델 학습

기본 경로는 ElasticNet(scripts/model.py의 train_clock()):

• ElasticNetCV — l1_ratio를 [0.1, 0.5, 0.7, 0.9, 0.95, 0.99, 1.0]에서 탐색
• 5-fold CV, n_alphas=50, max_iter=20000
• 학습/테스트 = 8:2 분할

딥러닝 버전이 필요하면 scripts/mlp.py의 AgingMLP 사용 (HuberLoss + AdamW, Dropout 0.3).

STEP 5 — 평가와 Age Acceleration

scripts/evaluate.py를 사용하여:

• MAE와 상관계수 출력 (목표: MAE 3~5세, Corr 0.9 이상)
• age_acceleration()으로 잔차 기반 Age Acceleration 산출
• plot_pred_vs_true()로 산점도 저장 (한글 폰트 자동 설정 포함)

STEP 6 — 산출물 저장

• 모델: outputs/clock_model.joblib
• 예측 CSV: outputs/predictions.csv (샘플ID, 역연령, 예측 나이, Age Acceleration)
• 산점도: outputs/pred_vs_true.png
• 메타 JSON: outputs/meta.json (사용 accession, CpG 수, MAE, Corr, 학습 시각)

STEP 7 — 재현성·운영 체크리스트 확인

references/reproducibility-checklist.md의 항목을 하나씩 검토하며 안내.

STEP 8 — 규제·윤리 확인 (서비스화 계획이 있을 때)

references/kr-regulations.md를 열어 다음을 확인:

• 개인정보보호법(PIPA) — 유전정보는 민감정보
• 생명윤리법 — IRB 심의 대상 여부
• 식약처 SaMD 가이드라인 — 예측·진단 목적이면 의료기기 허가 대상
• ISMS-P 인증 — 의료정보 취급 기업은 실질 요구됨
• 디지털의료제품법(2024 개정)

한 번에 실행하는 CLI

사용자가 "한 번에 돌려줘"라고 요청하면 scripts/run_pipeline.py를 사용:

python scripts/run_pipeline.py \
  --geo-id GSEXXXXXX \
  --output-dir ./outputs \
  --model-type elasticnet \
  --seed 42

파일 맵

aging-clock/
├── SKILL.md                          (이 파일)
├── scripts/
│   ├── setup_env.sh                  가상환경 + 패키지 설치
│   ├── data.py                       GEO 다운로드·β값 행렬·메타데이터·전처리
│   ├── model.py                      ElasticNet 학습
│   ├── mlp.py                        PyTorch MLP 버전 (선택)
│   ├── evaluate.py                   평가·Age Acceleration·시각화
│   └── run_pipeline.py               end-to-end CLI
├── references/
│   ├── geo-datasets.md               추천 GEO accession과 특징
│   ├── reproducibility-checklist.md  재현성·MLOps 체크리스트
│   └── kr-regulations.md             한국 법·제도 상세 (PIPA/IRB/SaMD/ISMS-P)
└── assets/
    └── korean-fonts.py               matplotlib 한글 폰트 자동 설정 헬퍼

주의사항

• 절대 모델 결과를 의학적 진단·조언으로 제시하지 말 것. 생성하는 리포트의 서두에 면책 문구를 자동 삽입할 것.
• 민감정보(유전·의료)를 다룰 때는 가명·익명처리 여부를 사용자에게 확인할 것.
• MAE가 10세 이상으로 벌어지면 데이터 품질·전처리 누락·샘플 수 부족을 의심할 것.