# HepatoLipidFlux (헤파토리피드플럭스)

> **참고용·연구용 도구입니다 (for research / reference use only).**
> 본 도구는 동물실험 데이터의 탐색·정량을 돕는 연구 보조 도구이며,
> 임상 진단·치료 의사결정에 사용해서는 안 됩니다.

## 목적

MASLD/MASH(대사성간질환) **동물모델**에서 in vivo **간 지질 플럭스**를
표준화된 지표로 정량하는 단독 실행형 Streamlit MVP입니다.
원시 추적자/시계열 데이터를 입력받아 VLDL-TG 분비율, MIDA 기반
fractional DNL(de novo lipogenesis), 지방산 산화 플럭스, 그리고
코호트 통계를 산출합니다.

- **도메인**: MASLD (대사성간질환)
- **카테고리**: 동물실험 도구 (animal experiment tool)
- **대상 사용자**: 간질환/대사 동물실험 연구실

## MVP 한 줄 설명

tyloxapol/poloxamer VLDL-TG 분비 시계열, 중수소수(2H2O)/13C de novo
lipogenesis enrichment, 지방산 산화 추적자 측정값을 입력받아
VLDL-TG 분비율, MIDA 기반 fractional DNL, 산화 플럭스 및 코호트
통계를 계산합니다.

## 5개 핵심 기능

1. **VLDL-TG 분비율** — tyloxapol / poloxamer-407 주사 후 혈장 TG
   시계열을 입력하면 초기 **선형(early) 구간을 자동 탐지**하여 회귀,
   분비율을 계산합니다. 체중/제지방량 정규화를 제공하며 후기 비선형
   포화(saturation) 구간을 감지하면 경고합니다.
2. **DNL 플럭스 엔진 (MIDA)** — 2H2O body-water enrichment 또는
   [13C]acetate/glucose 전구체 enrichment + 간 TG 지방산 mass
   isotopomer 분포를 입력받아 MIDA(이항모델)로 fractional DNL(신생합성
   분율)과 합성률을 계산합니다. 전구체 풀 enrichment 가정을 명시적으로
   표시하고 ±20% 민감도를 함께 보여줍니다.
3. **지방산 산화 플럭스** — [13C]palmitate 추적자의 호기 13CO2 /
   케톤체 enrichment로부터 회수율(bicarbonate recovery) 보정 산화
   플럭스를 계산합니다.
4. **MASH 모델 참조 + QC** — GAN diet, CDAHFD, MCD, AMLN, HFD,
   db/db, ob/ob 모델의 대표적 분비율/DNL 분율/산화 플럭스 참조범위를
   내장하고, 비선형 분비·불안정 enrichment·전구체 가정 누락 등에 대해
   자동 경고를 생성합니다.
5. **코호트 통계 + 리포트** — 그룹별 VLDL 분비율/DNL 분율/산화
   플럭스의 ANOVA 및 (가능 시) 혼합효과 모델을 수행하고,
   "합성억제형(synthesis-suppressing) / 분비변화형(secretion-altering)
   / 산화촉진형(oxidation-promoting)" 기전 분류 요약과 한국어/영어
   Method+Result 섹션을 export합니다.

## 실행 방법

```bash
# 1) 의존성 설치
pip install -r requirements.txt

# 2) 합성 샘플 데이터 생성 (data/ 폴더에 CSV 4종 생성)
python3 generate_sample_data.py

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

앱 사이드바의 **"데모 데이터 로드 (Load demo data)"** 버튼을 누르면
`data/` 폴더의 합성 CSV로 모든 기능을 오프라인에서 바로 체험할 수
있습니다. 파일을 업로드하지 않아도 동작합니다.

## 파일 구성

| 파일 | 설명 |
|------|------|
| `app.py` | Streamlit 앱 (메인 진입점, 5개 탭) |
| `flux_core.py` | 순수 Python 계산 모듈 (Streamlit 비의존, 테스트 가능) |
| `generate_sample_data.py` | 재현 가능한 합성 데이터 생성 스크립트 |
| `data/` | 합성 샘플 CSV (시계열·isotopomer·산화·메타) |
| `requirements.txt` | 고정 버전 의존성 |
| `README.md` | 본 문서 |
| `QA.md` | QA 점검 로그 |

### 입력 CSV 포맷

- **plasma_tg_timeseries.csv**: `animal_id, group, time_min, plasma_tg_mg_dl` (long)
- **dnl_isotopomer.csv**: `animal_id, group, precursor_enrichment, n_label_sites, M0, M1, M2, ...` (wide)
- **oxidation_tracer.csv**: `animal_id, group, tracer_dose_umol, co2_recovery_fraction, ketone_label_fraction, body_weight_g, bicarbonate_recovery, duration_h` (wide)
- **animal_meta.csv**: `animal_id, group, body_weight_g, lean_mass_g, batch`

## 계산 방법 요약

- **VLDL 분비율**: 0번 시점부터 r² 임계값(기본 0.95)을 유지하는 최장
  초기 구간을 자동 선택해 선형회귀. 기울기 → mg/dL/h → 혈장량(체중
  비례 가정) 환산 → mg/kg BW/h 정규화.
- **MIDA fractional DNL**: 측정 isotopomer 분포를
  `(1-f)·자연존재비 + f·이항(신생합성)분포` 로 모델링,
  최소제곱으로 f 추정. 전구체 enrichment를 이항분포 확률 p로 사용.
- **산화 플럭스**: `(투여 추적자 µmol × 표지 회수분율) / (체중kg ×
  시간h)` 를 bicarbonate 회수율로 보정.
- **통계**: 일원배치 ANOVA(scipy), batch 임의효과 혼합모델
  (statsmodels, 가능 시).

## 데이터 출처

본 MVP에 포함된 모든 데이터는 **합성(synthetic)** 데이터입니다.
`generate_sample_data.py`가 난수 시드(`20260518`) 고정으로 마우스
문헌의 대표적 범위(체중 25–41 g, 혈장 TG 50–250 mg/dL, 2H2O
enrichment ~4%, fractional DNL 0.05–0.45 등)를 본떠 생성합니다.
실제 동물·환자 데이터, 외부 API, 네트워크 호출을 일절 사용하지
않습니다. 내장 MASH 모델 참조범위는 일반적 문헌 경향을 본뜬
**연구용 참고치**이며 절대 기준이 아닙니다.

## QA 체크리스트

`QA.md`에 전체 로그가 기록되어 있습니다. 요약:

- [x] `app.py`, `flux_core.py`, `generate_sample_data.py` 구문 검사 (`ast.parse`)
- [x] `generate_sample_data.py` 실행 → CSV 4종 생성 확인
- [x] 생성된 CSV를 pandas로 재로딩하여 파싱 확인
- [x] `flux_core.py` 단독 import (Streamlit 비의존) 확인
- [x] 데모 데이터로 VLDL 회귀 + MIDA 함수 기능 점검 (정상 수치 확인)
- [x] `app.py`는 구문 검사 (streamlit 미설치 환경)

## 한계 및 주의

- 합성 데이터 기반 MVP이며, 실제 분석에는 실험실 검증과 적절한
  보정 계수(혈장량 비율, bicarbonate 회수율, 라벨 위치 수 등)
  설정이 필요합니다.
- MIDA는 전구체 풀 enrichment 가정에 의존하므로, 결과 해석 시 앱이
  표시하는 민감도 정보를 반드시 함께 검토하십시오.
- 다시 강조: **연구용·참고용 도구이며 임상 사용을 금합니다.**