# CHANGELOG — HepatoLipidFlux

## [2026-05-18]

### 수행 내용
- MASLD/MASH 동물모델 간 지질 플럭스 정량 도구 MVP(HepatoLipidFlux) 신규 구축.
- 5개 핵심 기능 구현: (1) VLDL-TG 분비율(선형구간 자동탐지+회귀),
  (2) MIDA 기반 DNL 플럭스 엔진, (3) 지방산 산화 플럭스(회수율 보정),
  (4) MASH 모델 참조범위+QC 경고, (5) 코호트 통계(ANOVA/혼합효과)+기전 분류.
- 순수 Python 계산 모듈 `flux_core.py`, Streamlit 앱 `app.py`,
  재현 가능한 합성 데이터 생성기 `generate_sample_data.py` 작성.
- 합성 샘플 CSV 4종(시계열·isotopomer·산화·메타) 생성.
- QA 6개 항목 수행, 전체 PASS.

### 주요 결정 사항
- 계산 로직을 `flux_core.py`로 분리하여 Streamlit 비의존·테스트 가능하도록 설계.
  → app 없이도 import/검증 가능, 유지보수 용이.
- VLDL 선형구간 자동탐지: 0번 시점부터 r² 임계 유지 최장구간 선택 방식 채택.
  잡음에 의한 일시적 r² 하락에 견고하도록 "연속 2회 실패 시 중단" 규칙 추가
  (단일 실패 즉시 중단 시 잡음으로 선형구간을 놓치는 문제 해결).
- MIDA는 `(1-f)·자연존재비 + f·이항분포` 최소제곱 모델 채택 — 전구체
  enrichment 가정에 의존하므로 ±20% 민감도를 항상 함께 산출하도록 결정.
- statsmodels 미설치 환경 대비: 혼합효과 모델은 try/except로 선택 처리,
  ANOVA도 scipy 없을 때 순수 Python fallback 구현.
- 합성 데이터의 VLDL 기울기·산화 추적자 용량을 마우스 문헌 참조범위
  (VLDL 180-560 mg/kg/h, 산화 140-420 µmol/kg/h)에 맞도록 보정.
- 동물의 약 80%는 후기 포화를, 20%는 선형 유지하도록 생성 → 비선형
  감지·선형구간 자동탐지 기능이 데모에서 모두 작동하도록 함.

### 변경된 파일
- `flux_core.py` (신규) — 계산 모듈: VLDL 회귀, MIDA, 산화, QC, 통계, 기전분류.
- `app.py` (신규) — Streamlit 5탭 앱, 데모 데이터 로드 지원.
- `generate_sample_data.py` (신규) — 시드 고정 합성 데이터 생성기.
- `data/*.csv` (신규) — 합성 샘플 데이터 4종.
- `requirements.txt` (신규) — 고정 버전 의존성.
- `README.md` (신규) — 목적·기능·실행법·QA·데이터출처·면책.
- `QA.md` (신규) — QA 점검 로그 (전체 PASS).

### 재현 방법
1. `cd 2026-05-18-3-hepato-lipid-flux`
2. 구문 검사: `python3 -c "import ast; [ast.parse(open(f).read()) for f in ['app.py','flux_core.py','generate_sample_data.py']]"`
3. 데이터 생성: `python3 generate_sample_data.py` (시드 20260518 고정)
4. 모듈 import 확인: `python3 -c "import flux_core"`
5. 전체 앱 실행: `pip install -r requirements.txt` 후 `streamlit run app.py`
6. 앱 사이드바 "데모 데이터 로드" 클릭 → 5개 탭 모두 동작 확인.