# GlucoClampTracer (글루코클램프트레이서)

하이퍼인슐린혈성-정상혈당 클램프(hyperinsulinemic-euglycemic clamp) 실험으로부터
**in vivo 인슐린 감수성**을 정량하는 단독 실행형 Streamlit 도구.

- **도메인**: DM (당뇨병)
- **카테고리**: 동물실험 도구 (animal experiment tool)
- **대상 사용자**: 내분비·대사·약리 동물실험 연구실

> ⚠ **참고용 · 연구용 도구입니다 (for reference / research use only).**
> 본 도구의 계산 결과는 동물실험 데이터 분석 보조용이며,
> 임상 진단·치료 목적으로 사용할 수 없습니다.

---

## 한 줄 요약

포도당 주입율(GIR) 시계열, 동위원소 트레이서 enrichment, 조직 2-deoxyglucose
측정값을 입력하면 → 정상상태 윈도우를 자동 선택하고, Steele 방정식으로
Ra/Rd, HGP 억제율, 조직 특이적 포도당 흡수지수를 계산하며, 코호트 통계까지 산출한다.

---

## 5개 핵심 기능

| # | 기능 | 설명 |
|---|------|------|
| 1 | **클램프 원자료 입력 + 정상상태 자동 선택** | 펌프 GIR 로그(mL/h·µL/min) · 혈당 샘플 · 체중 CSV 입력 → 사용자 정의 기준(혈당 CV, 목표 범위, 윈도우 길이)으로 정상상태 윈도우 자동 탐지 및 시각화 · 체중/제지방량(lean mass) 정규화 |
| 2 | **트레이서 동역학 엔진** | [3-3H]glucose(섬광계수 dpm)와 [6,6-2H2]glucose(LC-MS/GC-MS enrichment) 모두 지원 · 정상상태/비정상상태 Steele 방정식 선택 · priming/hot-GINF 보정 · Ra·Rd·HGP·HGP 억제율(기저 대비) 계산 |
| 3 | **조직 특이적 2-DG 흡수** | 혈장 [14C/3H]2-DG 소실곡선 AUC 보정 → 골격근(gastrocnemius·soleus·EDL·tibialis)·심장·BAT·WAT·간의 조직 특이적 Rg'(포도당 대사지수) 계산 · 조직 비교 막대그래프 |
| 4 | **모델 참조 + QC 플래그** | C57BL/6·db/db·ob/ob·DIO·ZDF·GK 모델별 전형적 GIR/HGP 참조 범위 내장 · 혈당 비수렴·트레이서 불안정·GINF 보정 누락 자동 경고 |
| 5 | **코호트 통계 + 리포트** | 그룹별 GIR/Rd/HGP 억제율/조직 Rg'의 일원배치 ANOVA · 쌍별 비교(Welch t-검정 + Bonferroni) · 혼합효과모형(statsmodels 설치 시) · 한국어/영어 method+result 리포트 export |

---

## 실행 방법

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

# 2. (선택) 합성 샘플 데이터 재생성 — 이미 data/ 에 포함되어 있음
python3 generate_sample_data.py

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

브라우저에서 자동으로 열리며, 사이드바에서 **"데모 데이터 로드"**를 선택하면
업로드 없이 합성 데이터로 모든 기능을 바로 확인할 수 있다(완전 오프라인 동작).

> `statsmodels`는 선택 의존성입니다. 미설치 시 혼합효과모형만 비활성화되고,
> ANOVA·쌍별 비교 등 나머지 기능은 scipy 기반으로 정상 동작합니다.

---

## 파일 구성

```
2026-05-18-1-gluco-clamp-tracer/
├── app.py                  # Streamlit 앱 (메인 진입점, 5개 기능 탭)
├── clamp_core.py           # 순수 Python 계산 모듈 (Steele 방정식 등, 단독 테스트 가능)
├── generate_sample_data.py # 합성 샘플 데이터 생성 스크립트 (재현용)
├── requirements.txt        # 고정 버전 의존성
├── data/
│   ├── clamp_timeseries.csv   # 펌프 GIR / 혈당 / 체중 시계열 (18마리)
│   ├── tracer_enrichment.csv  # [3-3H] / [6,6-2H2]glucose 트레이서 데이터
│   └── tissue_2dg.csv         # 조직 특이적 2-DG-6-P 측정값 (8개 조직)
├── README.md
└── QA.md                   # QA 점검 로그
```

### 입력 CSV 스키마

**clamp_timeseries.csv**: `animal_id, group, model, time_min, gir_mL_per_h,
glucose_mg_dL, body_weight_g, lean_mass_g`
(time_min < 0 = 기저, ≥ 0 = 클램프)

**tracer_enrichment.csv**: `animal_id, group, model, state(basal/clamp),
tracer_3h_infusion_dpm_min, plasma_3h_sa_dpm_per_mg, plasma_2h2_enrichment_pct,
plasma_glucose_mg_dL, hot_ginf_dpm_min`

**tissue_2dg.csv**: `animal_id, group, model, tissue, tissue_2dg6p_dpm_per_g,
plasma_2dg_auc_dpm_min_per_mL, mean_plasma_glucose_mg_per_mL`

---

## 핵심 계산식

- **정상상태 GIR → mg/kg/min**: 20% 덱스트로스(0.2 mg/µL) 가정, 체중으로 정규화
- **정상상태 Steele**: `Ra = F / SA` (방사성) 또는 `Ra = F / (E/100)` (안정동위원소)
- **비정상상태 Steele(1조구획)**: `Ra = [F − pV·Ḡ·(dE/dt)] / Ē`
- **HGP_basal** = Ra_basal, **HGP_clamp** = Ra_clamp − GIR
- **HGP 억제율(%)** = (HGP_basal − HGP_clamp) / HGP_basal × 100
- **조직 Rg'** = [조직 2-DG-6-P] / [혈장 2-DG AUC] × [평균 혈장 포도당]

---

## QA 체크리스트

- [x] 모든 `.py` 파일 Python 구문 검사 (`ast.parse`)
- [x] `generate_sample_data.py` 실행 → CSV 3종 생성 확인
- [x] 생성된 CSV pandas 로드/파싱 확인
- [x] `clamp_core.py` 단독 import (streamlit 불필요)
- [x] `clamp_core.py` 자체 검증 (`python3 clamp_core.py`)
- [x] 전체 파이프라인 스모크 테스트 (18마리, 3그룹)
- [x] 오프라인 동작 — 외부 네트워크/API 호출 없음
- [x] 앱·README에 참고용·연구용 면책 문구 표기

자세한 결과는 `QA.md` 참조.

---

## 데이터 출처

`data/` 의 CSV는 모두 **합성(synthetic) 데이터**이며,
`generate_sample_data.py`가 고정 시드(20260518)로 생성한다.
실제 동물 데이터가 아니며, 외부 데이터를 다운로드하지 않는다.

모델별 참조 범위(`clamp_core.MODEL_REFERENCE`)는 클램프 문헌의
전형적 값을 근사한 것으로, 정밀 분석 시 각 실험실 기준값으로 교체 권장.

---

## 한계 및 주의

- 합성 데이터 기반 MVP — 실제 실험 데이터로의 적용 전 검증 필요.
- 비정상상태 Steele는 단순화 적용(인접 basal/clamp 시점) — 정밀 분석에는
  dense 시계열 enrichment 자료 권장.
- 본 도구는 **연구 보조용**이며 임상적 판단을 대체하지 않는다.

---

*2026 metabolic daily idea pipeline · 2026-05-18 · DM 동물실험 도구*