# MetaCalorimetria-Kor (메타칼로리메트리아)

**도메인**: Obesity
**카테고리**: 인체실험 도구 (in-clinic 간접열량측정 분석 계산기)

메타볼릭카트 / ventilated hood 의 분당 VO₂·VCO₂ raw export 를 올리면
안정상태(steady state)를 자동검출하고 **Weir REE · RQ · Frayn 기질산화 · 예측식 대비
대사적응 · 식이유발열생성(DIT)** 를 산출하는 완전 오프라인 standalone Streamlit 분석기.

---

## ⚠️ 디스클레이머 (필수)

> **본 도구는 연구용·참고용이며 임상 의사결정에 직접 사용 금지.**
> 모든 산출값은 측정 장비의 교정 상태, 호흡가스 안정성, 환자 상태에 좌우됩니다.
> 의료적 진단·처방·영양처방을 대체하지 않으며, 검증된 임상 절차와 전문가 판단을 반드시 거쳐야 합니다.

---

## 핵심 기능

1. **다기종 import·정규화** — COSMED / Vyntus / Quark / Vmax export 컬럼 매핑 프리셋
   + 사용자 정의 매핑. 단위 자동 인식(mL/min ↔ L/min, VO₂ 중앙값 기반).
2. **안정상태 자동검출** — warm-up 구간 제외 + 슬라이딩 윈도우 CV(VO₂·VCO₂·RQ)
   임계 기반 안정구간 추천 + 수동 override 슬라이더 + 시각 확인 플롯.
3. **REE·기질산화** — Weir REE(단백 보정 on/off), RQ, Frayn 탄수화물·지방 산화율
   (g/min, kcal/day), 비단백 RQ(npRQ).
4. **예측식 비교** — Mifflin-St Jeor · Harris-Benedict · Henry/Schofield ·
   Cunningham(제지방 기반) 대비 측정 REE 비율 → 대사적응(metabolic adaptation) 지표.
5. **DIT / postprandial** — 식후 EE 곡선, 기저 대비 incremental AUC, 섭취 에너지 대비
   % thermogenesis. QC 플래그(RQ 0.67~1.0 밖·음수 산화율·결측), 코호트 비교,
   CSV/텍스트 리포트 export.

---

## 단위 규약 (중요)

- 내부 계산은 **VO₂·VCO₂ 를 L/min** 으로 통일.
- Weir 표준형:
  `REE(kcal/day) = [3.941·VO₂(L/min) + 1.106·VCO₂(L/min)]·1440 − 2.17·UN(g/day)`
  (mL/min 으로 계산 시 동일 결과를 1000 으로 나눈 형태; importer 가 mL→L 변환)
- `1440` = 분/일. 단백 보정 UN = 24h 요소질소(g/day), off 시 0.

---

## 실행법

```bash
# 1) (권장) 가상환경
python3 -m venv .venv && source .venv/bin/activate

# 2) 의존성 설치 (전역 금지 — 가상환경 내에서만)
pip install -r requirements.txt

# 3) 데모 CSV 생성 (이미 data/ 에 포함되어 있으면 생략 가능)
python3 demo_data.py

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

브라우저가 열리면 사이드바에서 **합성 데모** 또는 **CSV 업로드** 선택 →
탭(안정상태 / 기질산화·예측식 / DIT / QC·Export)에서 분석.

---

## 파일 구성

| 파일 | 역할 |
|------|------|
| `app.py` | Streamlit 진입점 (메인 UI, 4개 탭) |
| `calorimetry.py` | Weir REE / RQ / Frayn 기질산화 / DIT / QC |
| `steady_state.py` | 슬라이딩 윈도우 CV 안정상태 검출 |
| `predictive.py` | Mifflin·Harris-Benedict·Henry·Cunningham + 대사적응 |
| `importers.py` | 다기종 컬럼 매핑·단위 자동인식·정규화 |
| `demo_data.py` | 합성 안정/불안정/DIT 곡선 생성 |
| `reference.yaml` | 기종 컬럼 프리셋·예측식 출처·정상 참고치·상수 |
| `data/*.csv` | 합성 데모 3종 (COSMED 스타일, mL/min) |
| `requirements.txt` | pinned 의존성 |
| `QA.md` | 검수 로그 |

---

## 검수 체크리스트

- [x] 6개 `.py` 전부 AST 구문 검사 통과
- [x] Weir REE 손계산 일치 (VO₂=0.25, VCO₂=0.20 → RQ 0.800, REE 1737.29 kcal/day)
- [x] Frayn 손계산 일치 (cho 0.1075, fat 0.0835 g/min)
- [x] 단백 보정(UN=10) REE = base − 21.7
- [x] 데모 CSV 3종 pandas 로드 + 단위 자동인식(mL/min) 검증
- [x] 안정구간: steady 데모 검출 성공 / unstable 데모 검출 실패(의도대로)
- [x] DIT AUC 양수·non-NaN, % thermogenesis 산출
- [x] QC 플래그 (RQ 범위 밖·음수 가스) 동작
- 자세한 로그는 `QA.md` 참조.

---

## 출처 (참고 문헌)

- Weir JB de V. *J Physiol* 1949;109:1-9. (간접열량측정 EE 식)
- Frayn KN. *J Appl Physiol* 1983;55:628-34. (가스교환 기반 기질산화)
- Mifflin MD et al. *Am J Clin Nutr* 1990;51:241-7.
- Harris JA, Benedict FG. Carnegie Institution of Washington, 1919.
- Henry CJK. *Public Health Nutr* 2005;8:1133-52. (Oxford/Schofield 계열)
- Cunningham JJ. *Am J Clin Nutr* 1980;33:2372-4. (FFM 기반 RMR)

> 식 계수·정상 RQ/REE 범위는 위 문헌의 고전 값을 사용하였으며,
> 구현 검증용 합성 데이터에 한해 동작을 확인하였습니다. 실제 임상 적용 전
> 기관 프로토콜·장비 교정·문헌 재확인이 필요합니다.