# GlycemicNIMargin-Kor (글리세믹엔아이마진코어)

당뇨 RCT용 **비열등성(non-inferiority) 마진 산출·정당화 + MMRM 기반 탈락보정 표본수 계산기**.
HbA1c / CGM-TIR 종단 endpoint를 다루며, 규제 제출용 통계 정당화 문서(국문/영문)까지
자동 생성하는 standalone 설계 도구.

- **도메인**: 당뇨병 (DM / Diabetes Mellitus)
- **카테고리**: 인체실험 도구 (RCT 설계·계산기)
- **버전**: 1.0 (2026-05-17)
- **동작**: 완전 오프라인. 외부 네트워크/API 호출 없음.

---

## ⚠️ 의학적 안전성 면책

> 본 도구는 **참고용·연구용** RCT 설계 계산기입니다.
> 실제 임상시험의 표본수·마진·통계 설계는 **반드시 생물통계학자(biostatistician)
> 검토**를 거쳐야 하며, 최신 규제 가이던스(ICH E9/E10, FDA/EMA/MFDS)를
> 확인하십시오. 본 도구의 산출값은 closed-form 근사이며 실제 프로토콜의
> 확정 표본수가 아닙니다.

---

## 핵심 기능 (5개)

1. **NI 마진 정당화 엔진** — fixed-margin(M2) / synthesis(95-95) 방법.
   과거 위약대조 시험의 활성약-위약 효과를 입력하면 "활성약 효과의 50%(M2) 보존"
   논리로 δ를 산출하고, ICH E10 용어로 정당화 문단을 국문/영문 자동 작성.
   HbA1c·FPG·CGM-TIR·중증저혈당률 endpoint별 마진 프리셋 라이브러리 내장.
2. **MMRM 표본수 계산** — 종단(baseline·12·24·52주) 측정, AR(1)/unstructured
   공분산, MAR 가정 탈락보정, 검정력 곡선. 단순 ANCOVA(단일시점) 대비 효율 비교.
3. **공동 1차 endpoint 다중성 처리** — HbA1c + TIR 공동 1차 시 상관 r 입력 →
   Hochberg / gatekeeping / Bonferroni / 미보정 절차별 표본수, FWER 통제.
   공동 검정력은 이변량 정규분포로 계산.
4. **탈락 시나리오 시뮬레이터** — 탈락률 5~25%, 패턴별(MCAR / MAR_early /
   MAR_late) 검정력 민감도 히트맵.
5. **규제 제출 문서 생성** — 표본수 근거·마진 정당화·가정·참고문헌을
   IND/프로토콜 통계 섹션 형식(국문/영문) 텍스트로 생성, 다운로드 가능.

---

## 파일 구성

| 파일 | 설명 |
|------|------|
| `core.py` | 순수 계산 함수 (numpy/scipy만 사용, statsmodels 의존 없음) |
| `app.py` | Streamlit UI 래퍼 |
| `main.py` | argparse CLI 진입점 (오프라인 시연용) |
| `data/margin_presets.json` | endpoint별 마진 프리셋 라이브러리 + 출처 |
| `README.md` | 본 문서 |
| `QA.md` | 검수 로그 |
| `CHANGELOG.md` | 작업 이력 |

---

## 실행법

### 1) CLI (Streamlit 불필요 — 오프라인 시연)

```bash
python3 main.py --help                  # 도움말
python3 main.py --demo                  # 예제 시나리오(HbA1c NI RCT) 전체 출력
python3 main.py --margin-fixed 0.8 0.5  # fixed-margin 마진만 계산
python3 main.py --samplesize 0.4 1.0    # MMRM 비열등성 표본수만 계산
```

### 2) Streamlit 앱

```bash
streamlit run app.py
```

탭 ①~⑤를 순서대로 사용. 탭 ⑤ 규제 문서 생성은 탭 ①(마진)·②(표본수)를
먼저 실행해야 활성화됩니다.

### 의존성

- Python 3.8+
- `numpy`, `scipy` — 권장 (정확한 통계 계산). 미설치 시 `core.py`는
  표준라이브러리 근사(Acklam inverse-CDF, Monte-Carlo)로 graceful degradation.
- `streamlit`, `pandas` — Streamlit 앱(`app.py`)에만 필요. CLI는 불필요.
- **전역 pip 설치 금지** — 본 프로젝트는 추가 설치를 요구하지 않으며,
  numpy/scipy 미설치 환경에서도 CLI는 동작합니다.

---

## 검수 체크리스트

- [x] `core.py` / `app.py` / `main.py` 구문 파싱(`ast.parse`) 통과
- [x] `data/margin_presets.json` JSON 파싱 통과
- [x] `python3 main.py --help` 정상 출력
- [x] `python3 main.py --demo` 5개 기능 전체 정상 계산·출력
- [x] `norm_ppf` 표준라이브러리 근사 vs scipy 일치(1e-6 이내)
- [x] 탈락 히트맵이 단일시점 계획 표본수 기준으로 의미있는 검정력(~80%) 산출
- [x] 면책 문구가 README·CLI·앱 출력에 모두 포함

상세 로그는 `QA.md` 참조.

---

## 수식 출처

- **비열등성 2-표본 t-test 표본수**: Chow SC, Shao J, Wang H.
  *Sample Size Calculations in Clinical Research*, 2nd ed. (2008), Ch.3.
- **95-95 synthesis(2-CI) 방법**: ICH E10 (2001); Hung HMJ et al.
  "A regulatory perspective on choice of margin..." *Stat Med* (2005).
- **MMRM 종단 설계효과**: Lu K, Luo X, Chen PY. "Sample size estimation
  for repeated measures analysis..." *Int J Biostat* (2008);
  Hedeker D, Gibbons RD. *Longitudinal Data Analysis* (2006), Ch.13.
- **다중성(공동 1차)**: Hochberg Y. (1988); Dmitrienko A et al.
  *Multiple Testing Problems in Pharmaceutical Statistics* (2010).
- **결측/탈락 보정**: EMA Missing Data guideline (CPMP/EWP/1776/99 Rev.1).
- **CGM TIR 임상 기준**: Battelino T et al. *Diabetes Care* (2019) —
  International Consensus on Time-in-Range.
- **규제 프레임**: ICH E9 (통계 원칙), ICH E10 (대조군 선택);
  FDA/EMA/MFDS 당뇨병 의약품 가이던스.

프리셋 SD/상관 값은 공개 당뇨 RCT 메타분석에서 흔히 인용되는 대표값으로,
실제 적용 시 자사 과거 데이터로 갱신해야 합니다 (`data/margin_presets.json` 참조).