# CHANGELOG — GlyceSurrogate-Kor

## [2026-05-22]

### 수행 내용
- 당뇨병(DM) 도메인 · 연구 아이디어 생성 카테고리의 독립 실행형 오프라인 MVP **GlyceSurrogate-Kor** 구축.
- 시험수준 대리성(trial-level surrogacy) 메타회귀 엔진을 순수 numpy/scipy로 구현 (statsmodels 미설치):
  가중최소제곱(WLS) R²\_trial + Fisher-z 95% CI, 대리역치효과(STE, 예측밴드 교차 + 방향 가드),
  PTE(매개분석 framing, [0,1] 클램프), surrogate-paradox 탐지, 등급화(strong/moderate/weak/invalid),
  미검증 조합 마이닝 + 검증가설 + 표본수 제안.
- CLI(`main.py`, `--surrogacy/--paradox/--gaps/--hypotheses/--all/--data/--top/--csv-out`),
  공유 엔진(`surrogacy.py`), 선택적 Streamlit UI(`app.py`), 합성 데모 CSV(`data/demo_trials.csv`),
  `README.md`, `QA.md` 작성.
- ACCORD/VADT(강화혈당조절) → surrogate paradox, SGLT2i HbA1c→경성결과 → weak surrogacy 라는
  임상 교훈을 데모에서 재현.

### 주요 결정 사항
- **statsmodels 대신 직접 구현:** 미설치 + 제약 조건. WLS·예측밴드·STE를 1차 원리로 작성.
- **예측밴드 스케일 수정:** 신규시험 분산을 단위가중(=1)이 아닌 `s²/w_med`(관측 역분산 가중치 중앙값)로
  설정 → 역분산 가중 적합과 스케일 일치, STE 산출 가능.
- **STE 방향 가드:** 기울기가 이득 방향(`sign·β1<0`)일 때만 STE 반환 (paradox/무관계 셀은 None).
- **요약의 "strongest" 셀:** paradox 셀(invalid) 제외하고 valid 셀 중 최고 R² 선택.
- **CHANGELOG 위치:** 서브프로젝트 단위로 프로젝트 디렉터리 내부에 작성 (워크스페이스 루트의 대형
  파이프라인 CHANGELOG는 건드리지 않음).

### 변경된 파일
- `surrogacy.py` — 메타회귀 엔진 (신규).
- `main.py` — CLI 진입점 (신규).
- `app.py` — Streamlit UI (신규).
- `data/demo_trials.csv` — 합성·예시 데모 데이터 (신규).
- `README.md`, `QA.md`, `CHANGELOG.md` — 문서 (신규).

### 재현 방법
1. `cd projects/2026-05-22-1-glyce-surrogate-kor/`
2. `python3 main.py --help` → 사용법 확인.
3. `python3 main.py --all` → 요약 + 대리성 표 + paradox + 가설 전체 출력.
4. `python3 main.py --data <your.csv> --surrogacy` → 사용자 데이터 분석 (스키마는 README 참조).
5. (선택) `streamlit run app.py` → 웹 UI.
6. 검증: `python3 -c "import ast; ast.parse(open('main.py').read()); ast.parse(open('app.py').read())"`
   및 QA.md의 테스트 스위트.

### 검수 결과 (의도 부합)
- 요청한 5개 핵심 기능 모두 구현·검증됨 (R²∈[0,1], grade 부여, paradox 플래그, 가설 생성, 표본수 제안).
- 오프라인·무설치·면책문구 제약 충족.
- 추가 구현: `surrogacy.py`로 엔진 분리(CLI/UI 공유), `--csv-out` 내보내기, 빌드 중 발견한 STE
  스케일/방향 버그 수정 (QA.md §7에 기록).