# CHANGELOG — InsuTrialKit-Kor

## [2026-04-28]

### 수행 내용
- InsuTrialKit-Kor MVP 빌드: 인슐린펌프·CGM 다기기 raw → long-form 표준화 + ADA 2023 outcome 14종 산출 + Korean RCT report + sample size calculator
- 4개 full adapter (Dexcom Clarity, Libre LibreView, Tandem t:connect, Medtronic CareLink) + 4개 stub adapter (Omnipod, CamAPS, MiniMed 780G, Guardian 4) signature dispatch
- ADA 2023/ATTD 2022 14-metric outcome (TIR, TBR1/2, TAR1/2, mean, GMI, CV, SD, MAGE, J-index, hypo events, sensor wear%, days)
- 한국 reference effect size DB (JSON, HbA1c tertile-stratified) + 두 표본 평균 비교 N/arm 계산기
- 합성 데이터 generator (3 환자 × 14일 × 5분, 4개 device 형식)
- end-to-end CLI 데모 (`python3 main.py demo`)

### 주요 결정 사항
- **YAML 대신 JSON**: PyYAML 의존성 회피 + 표준 라이브러리 json만 사용 (codebase 단순화). 사용자 명세상 "YAML/JSON 둘 중 하나" 허용.
- **자체 markdown table renderer**: pandas `to_markdown()`이 `tabulate` 패키지 필요 → 환경에 없음 → 자체 `_df_to_md()` 구현으로 의존성 최소화.
- **3개 full adapter 명세 → 4개 구현**: Medtronic CareLink는 명세상 "XLSX"였으나 합성 데이터는 CSV로 생성하고, parser는 XLSX/CSV 둘 다 처리. Tandem/Dexcom/Libre 포함 4개 모두 풀 어댑터화 (명세 허용 범위 내).
- **Stub adapter 패턴**: 4개 미구현 device는 filename keyword로 dispatch + generic CSV (timestamp+glucose) 파싱 시도. 시그니처 dispatch 시연 + 향후 확장 hook.
- **inverse normal CDF 자체 구현**: scipy 의존 없이 Beasley-Springer-Moro 근사로 z-score 계산 → power.py 순수 stdlib + math.
- **MAGE 간이 추정**: 피크-트로프 > 1 SD인 excursion의 평균. 정식 MAGE는 알고리즘 복잡(turning-point detection 등) → 명세상 "간이 추정" 허용.
- **24h break-in cut**: 명세 데이터 위생 요구. apply_breakin_cut() 함수로 ingest 단계 자동 적용.
- **subject_id 우선순위**: Libre adapter가 Patient 컬럼을 Serial Number보다 우선하도록 fix (초기 구현에서 SN-0000 등으로 잘못 그룹화되는 버그 수정).

### 변경된 파일
- `README.md` — 신규. 목적/도메인/카테고리/기능/실행법/검수 체크리스트/출처/디스클레이머
- `main.py` — 신규. argparse CLI 진입점, 5개 서브커맨드
- `outcomes.py` — 신규. ADA 2023 14-metric + gap detection + break-in cut
- `power.py` — 신규. two-arm RCT N/arm 계산기 + Korean tertile DB 로더
- `report.py` — 신규. Markdown report (group×period 표, heatmap normalized, Bland-Altman pairs)
- `adapters/__init__.py` — 신규. dispatch loop
- `adapters/dexcom.py` — 신규. Dexcom Clarity CSV adapter (full)
- `adapters/libre.py` — 신규. Libre LibreView CSV adapter (full, Patient > Serial 우선순위)
- `adapters/tandem.py` — 신규. Tandem t:connect CSV adapter (full, basal/bolus/carb 포함)
- `adapters/medtronic.py` — 신규. CareLink CSV/XLSX adapter (full, 다중 skiprows fallback)
- `adapters/stub_devices.py` — 신규. Omnipod/CamAPS/MiniMed780G/Guardian4 stub
- `data/gen_synth.py` — 신규. 4-device 합성 raw export generator
- `data/effect_sizes_kr.json` — 신규. 한국 reference effect size DB (placeholder)
- `data/__init__.py` — 신규. 빈 패키지 마커
- `QA.md` — 신규. 검수 로그
- `CHANGELOG.md` — 신규(본 파일)

### 재현 방법
```bash
cd "/Users/sangjoonpark/2026 metabolic daily idea/projects/2026-04-28-1-insu-trial-kit-kor"

# end-to-end (가장 빠른 검증)
python3 main.py demo

# 단계별
python3 main.py gendata
python3 main.py ingest --input data/ --output out.csv
python3 main.py outcomes --input out.csv --output report.md
python3 main.py samplesize --delta 5 --sd 12 --alpha 0.05 --power 0.8 --tertiles
```

필요 의존성: Python 3.9+ (3.11 권장), pandas, numpy. 외부 네트워크 호출 없음.