# HepatoLipidClear-Kor (헤파토리피드클리어)

> ⚠️ **면책 / Disclaimer**: 본 도구는 **연구용·교육용·참고용**입니다.
> **임상 진단·치료 의사결정에 직접 사용하지 마십시오.** 모든 데모 데이터는 합성(synthetic)입니다.
> 산출값은 가정(특히 CO₂ 생성률·기질 용량·표준식 조성)에 민감하며, 검증된 임상 도구가 아닙니다.

## 개요

- **도메인**: MASLD (대사이상 지방간질환)
- **카테고리**: 인체실험 도구 (in-clinic 경구 지방부하·¹³C 호기검사 분석 계산기)
- **한 줄**: 경구 지방부하검사(OFTT, 시점별 TG·apoB48·retinyl)와 ¹³C 호기검사(δ¹³C/PDR)의 원시 시점값을 올리면, 식후 지질 incremental AUC·peak·Tmax·청소율과 호기 cumulative PDR·산화율·반감기를 산출하는 standalone Streamlit 간 대사 동적검사 분석기.
- **오프라인**: 외부 네트워크/API 호출 0. 합성 데모 데이터 내장.

## 핵심 기능

1. **OFTT 모듈** (`oftt.py`): 시점별 TG(±apoB48·retinyl) → total·incremental AUC(0–6/0–8h), peak·Tmax, 기저 복귀(청소) 시간, 섭취 지방량 대비 normalize(iAUC/g fat).
2. **¹³C 호기검사 모듈** (`breath.py`): δ¹³C(‰) → PDR(%/h) 변환(CO₂ 생성률: 측정값 입력 또는 BSA 기반 추정 300 mmol/m²/h 선택·명시), cumulative PDR(40/120분), 산화율, kel·반감기(비선형 단일지수 fit 또는 로그-선형 폴백).
3. **검사 표준화 체크리스트**: 고지방식 조성·열량, 금식 시간, 기질 용량, CO₂ 가정값을 결과 메타데이터로 기록(재현성).
4. **QC·코호트**: 시점 누락·δ¹³C 기저 이상·음수 PDR·음수 농도 플래그, 군간 비교 표·곡선 오버레이, 산출 공식·파라미터 footnote 자동 기록.
5. **단위·동위원소 처리** (`units.py`): TG mg/dL↔mmol/L, δ¹³C(‰ vs PDB)↔비, apoB48 단위 토글.

## 산출 공식 (footnote)

```
iAUC      = ∫(C(t) − baseline) dt           (사다리꼴 적분)
iAUC/gfat = iAUC ÷ 섭취 총 지방량(g)
PDR(t)[%/h] = DOB(t)/1000 × VCO₂[mmol/h] × R_PDB / Dose[mmol ¹³C] × 100
DOB(t)    = δ¹³C(t) − δ¹³C(baseline)         [‰]
R_PDB     = 0.0112372                         (PDB 국제표준 ¹³C/¹²C 절대비)
VCO₂(추정) = 300 mmol/m²/h × BSA
BSA       = 0.007184 × W(kg)^0.425 × H(cm)^0.725   (Du Bois)
cPDR[%]   = ∫ PDR dt(h)                       (사다리꼴, 0–40/120분 보간 끝점)
t½        = ln(2) / kel
```

## 구성

| 파일 | 역할 |
|---|---|
| `app.py` | Streamlit 진입점 (5개 탭 UI) + 검수 가능 헬퍼 `run_oftt_table`/`run_breath_table` |
| `oftt.py` | 식후 지질 AUC/peak/clearance |
| `breath.py` | δ¹³C→PDR/cPDR/kel/반감기, BSA·VCO₂ 추정 |
| `auc.py` | 공통 trapezoidal AUC·peak·복귀시간 |
| `units.py` | 단위·동위원소 변환 |
| `demo_data.py` | 합성 데모 생성 + `data/` CSV 작성 |
| `reference.yaml` | PDR 변환식·CO₂ 추정식·표준 고지방식·정상참고치·출처 |
| `data/*.csv` | 합성 데모 3종 (정상/지연청소 OFTT, 호기 δ¹³C) |
| `requirements.txt` | pinned 의존성 |
| `QA.md` | 검수 로그 |

## 실행

```bash
# (권장) 가상환경에서
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# 데모 CSV 재생성(이미 data/ 에 포함됨)
python3 demo_data.py

# 앱 실행
streamlit run app.py
```

전역 패키지 설치는 하지 마십시오. `requirements.txt`만 사용하십시오.

## 검수 체크리스트

- [x] 모든 `.py` AST 구문 검사 통과
- [x] 핵심 계산(iAUC·peak/Tmax·PDR/h·cPDR·반감기) 손계산 비교 검증
- [x] 합성 데모 CSV 3종 `pandas.read_csv` 로드 성공
- [x] QC 플래그(시점 누락·음수값) 동작 확인
- [x] 비선형 fit 실패 시 로그-선형 폴백 동작 확인
- [x] app.py import-safe (streamlit은 `main()` 내부 import)

자세한 로그: `QA.md`

## 출처 (방법론)

- Frayn KN. *Metabolic Regulation: A Human Perspective* — 식후 지질 대사.
- Cobelli / Toffolo — minimal-model 기반 식후 청소 개념.
- Mihas C et al. *Curr Vasc Pharmacol* 2011 — OFTT 리뷰.
- Ghoos YF et al. *Gastroenterology* 1993 — ¹³C-octanoate 호기검사.
- Schadewaldt P; Sanaka M et al. — ¹³C 호기검사 PDR/cPDR/kel 산출 표준식.

CO₂ 생성률 표준 가정값 300 mmol/m²/h 는 호기검사 문헌에서 널리 쓰이는 추정 기준값이며,
가능하면 실측 VCO₂(간접열량계) 사용을 권장합니다. 본 가정은 결과 메타데이터로 기록됩니다.