# GlucoDynamics-Kor (글루코다이내믹스코어)

> **⚠️ 디스클레이머 — 반드시 읽으세요**
> 본 도구는 **연구용·교육용·참고용**이며 **임상 의사결정에 직접 사용을 금지**합니다.
> 모든 산출값은 입력 데이터·가정·근사식(특히 HOMA2 근사, Stumvoll 단순형,
> C-peptide 디컨볼루션 표준 kinetics)에 의존하며, 진단·치료·환자 관리 목적으로
> 사용할 수 없습니다. 합성 데모 데이터는 절차적으로 생성된 가상의 값으로 실제
> 환자 데이터가 아닙니다.

## 도메인 / 카테고리
- **도메인**: DM (당뇨·대사)
- **카테고리**: 인체실험 도구 — in-clinic 동적·유발 대사검사 분석 계산기

## 한 줄 소개
OGTT / MMTT / euglycemic-clamp 시점별 혈당·인슐린·C-peptide CSV를 올리면,
인슐린 **감수성·분비 지표 전 패널**을 단위 자동 보정·AUC 방법 선택과 함께
**per-participant·코호트**로 산출하고 **QC 플래그**를 주는, 완전 오프라인
Streamlit 대사 동적검사 분석기.

---

## 기능

### 1. 검사 모드 / 단위
- 프로토콜 템플릿: **75g OGTT(0–120)**, **확장 OGTT(0–180)**, **MMTT(0–180)**,
  **Euglycemic clamp**. 임의 시점도 CSV로 지원.
- 단위 토글 + 자동 변환·canonical 표기:
  - 혈당 `mg/dL ↔ mmol/L` (×18.0156)
  - 인슐린 `µU/mL ↔ pmol/L` (×6.945)
  - C-peptide `ng/mL ↔ nmol/L` (×0.331)

### 2. 인슐린 감수성 지표
| 지표 | 공식 / 비고 |
|---|---|
| HOMA-IR | FPG[mmol/L]·FPI[µU/mL] / 22.5 |
| HOMA2-IR (근사) | 비선형 HOMA2의 로그선형 **근사**(참고용) |
| QUICKI | 1 / (log₁₀FPI + log₁₀FPG[mg/dL]) |
| Matsuda / ISI | 10000 / √(FPG·FPI·meanG·meanI) — meanG/meanI는 **시간가중 평균** |
| Gutt ISI(0,120) | (75000 + (G0−G120)·0.19·BW) / (120·meanG·ln(meanI)) |
| Stumvoll ISI | 단순형(참고용) |
| Clamp M-value | 안정상태 GIR 평균(mg/kg/min) |
| M/I | M-value / 안정상태 인슐린 |

### 3. 인슐린 분비 지표
| 지표 | 공식 / 비고 |
|---|---|
| HOMA-β | 20·FPI / (FPG[mmol/L]−3.5) |
| Insulinogenic index | (I30−I0)/(G30−G0) |
| CIR30 (corrected insulin response) | 100·I30 / (G30·(G30−70)) |
| ISR (C-peptide 디컨볼루션) | van Cauter 1992 2-구획 표준 kinetics, 연령·BSA(Du Bois) 보정, 비음수 디컨볼루션 |
| Oral Disposition Index | Insulinogenic index × Matsuda |

### 4. AUC 엔진
- **total / incremental(기저 차감) / positive-incremental** 선택
- **사다리꼴** 적분, **불균등 시간 간격** 지원, 영점교차 보간(positive iAUC 정확도)
- 구간 분리: **0–120 / 0–180** (프로토콜에 따라 자동)

### 5. QC / 코호트
- 플래그: 공복(0분) 누락, 중복·비단조 시점, 혈당/인슐린/C-peptide 단위 이상치,
  음의(역생리) 값, 경구부하 후 무반응 등
- 다중 피험자 → **코호트 비교 표 + 막대그래프**
- 모든 결과 하단에 **산출 공식·파라미터를 footnote로 자동 기록**

---

## 기술 스택
Python · Streamlit · pandas · numpy · scipy(디컨볼루션 NNLS) · matplotlib · PyYAML.
**완전 오프라인** — 외부 네트워크/API 호출 0.
scipy 미설치 시 ISR은 정상상태 근사로 graceful fallback.

## 파일 구성
```
app.py            Streamlit 진입점 + 비-UI 분석 로직(analyze_participant 등)
metrics.py        감수성/분비 지표 + 단위 변환
auc.py            AUC 엔진(trapezoidal, total/incremental/positive)
deconvolution.py  ISR (van Cauter 1992 kinetics + NNLS 디컨볼루션)
demo_data.py      합성 OGTT(정상/IGT/T2DM)·clamp 생성
reference.yaml    프로토콜·단위계수·정상참고치
verify.py         검수 스크립트(손계산 대조 포함)
data/             합성 데모 CSV 4종
requirements.txt  pinned 의존성
QA.md             검수 로그
```

## 실행법
```bash
# (선택) 의존성 설치 — 전역 금지, --user 사용
python3 -m pip install --user -r requirements.txt

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

# 앱 실행
streamlit run app.py

# 검수(계산 로직 단위테스트 + 손계산 대조)
python3 verify.py        # 종료코드 0 = 통과
```

CSV 스키마: `time_min, glucose, insulin[, cpeptide]` (clamp는 `gir` 열 추가).
여러 명을 한 파일에 담으려면 `participant` 열 추가.

---

## 검수 체크리스트
- [x] 모든 `.py` AST 구문 검사 통과
- [x] 핵심 지표 합성 데이터 호출 시 NaN/에러 없음
- [x] 손계산 대조: HOMA-IR, QUICKI, Matsuda, Insulinogenic index, AUC(평탄/삼각/불균등/positive)
- [x] ISR 디컨볼루션 유한·비음수 산출(NNLS, 오버플로 경고 제거)
- [x] 합성 데모 CSV 4종 pandas 로드
- [x] 생리학적 방향성(HOMA-IR: NGT<IGT<T2DM, Matsuda: NGT>T2DM)
- [x] app.py 비-UI 로직(normalize_units / analyze_participant / qc_flags / footnotes) 직접 호출

## 출처 (참고문헌)
- Matthews DR, et al. **HOMA**. Diabetologia 1985;28:412–419.
- Levy JC, et al. **HOMA2**. Diabetes Care 1998;21:2191–2192.
- Katz A, et al. **QUICKI**. J Clin Endocrinol Metab 2000;85:2402–2410.
- Matsuda M, DeFronzo RA. **Matsuda ISI**. Diabetes Care 1999;22:1462–1470.
- Gutt M, et al. **ISI(0,120)**. Diabetes Res Clin Pract 2000;47:177–184.
- Stumvoll M, et al. **Stumvoll index**. Diabetes Care 2000;23:295–301.
- Sluiter WJ, et al. **CIR**. Diabetes 1976;25:241–244.
- Utzschneider KM, et al. **Oral disposition index**. Diabetes Care 2009;32:335–341.
- Van Cauter E, et al. **C-peptide ISR / kinetics**. Diabetes 1992;41:368–377.
- DeFronzo RA, et al. **Euglycemic clamp**. Am J Physiol 1979;237:E214–E223.
- ADA Standards of Care / WHO OGTT 기준 / KDA 진료지침 (OGTT 분류).

> 단위 변환계수·근사식·kinetic 파라미터는 위 출처의 공개값을 사용했으며,
> HOMA2·Stumvoll·van Cauter long half-life는 **근사 구현**임을 명시합니다.
> 정밀 임상 적용이 필요한 경우 각 원저의 공식 계산기를 사용하십시오.